basic password hashing, still need to rework recovery
[bse.git] / site / docs / config.pod
CommitLineData
61551101
TC
1=head1 NAME
2
3config.pod - documents BSE configuration file options
4
5=head1 DESCRIPTION
6
7BSE historically used Constants.pm to keep most configuration
8information. The plan is to make sure any new configuration is kept
9in bse.cfg, and to slowly move most configuration information into
10bse.cfg.
11
12Keeping configuration information in Constants.pm makes it difficult
13to perform upgrades and makes it impossible to use tools such as
14mod_perl, at least if you want more than one site on the machine.
15
71721575
TC
16F<bse.cfg> is read as a utf-8 encoded file.
17
61551101
TC
18=head1 CONFIGURATION ENTRIES
19
41f10371
TC
20=head2 [site]
21
22Contains URL configuration for the site.
23
24=over
25
26=item url
27
28The normal URL for the non-secure parts of the site.
29
30=item secureurl
31
32The secure URL for the shop, products and other portions of the site
33that should use SSL. This isn't checked to make sure it is https.
34
35=item name
36
37Used as the site "name" in a few places.
38
39=item adminurl
40
41If set, this is used as the base URL for accessing the administrative
42functions of your site.
43
44=item secureadmin
45
46Ignored if C<adminurl> is set.
47
48If this is true then C<secureurl> is used as the base URL for
49accessing the administrative functions of your site, otherwise C<url>
50is used as the base URL. Default: false (C<url>'s value is used)
51
c5f849c7
TC
52=item forward_from
53
54Configure the IP address of one or more front-end proxies. This can
55be a regular expression except that C<.> is translated to C<\.> and
56C<*> is tranlated to C<.*> to give more glob() like matching.
57
58If the reqesting host matches then admin site URL matching is done
59against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
60
61Default: no front-end server configured.
62
41f10371
TC
63=back
64
61551101
TC
65=head2 [paths]
66
67Contains various file system paths.
68
69=over
70
71=item downloads
72
73This is where the files uploads with the file wizard are stored. It
74must be writable by the web server user.
75
76=item admin_templates
77
78Directory containing administrative templates. Note: this is not
79completely implemented for now, so assume the default. Default: admin
80directory under $TMPLDIR.
81
82=item templates
83
02d87eea
TC
84Directory base for most templates. This can contain references like
85$(section/key) to other configuration entries. Split on the systems
86PATH separators (run: perl -V:path_sep)
aefcabcb
TC
87
88=item local_templates
89
90Local Directory base for templates. This is searched before the
02d87eea
TC
91templates directory. This can contain references like $(section/key)
92to other configuration entries. Split on the system's PATH separator.
61551101 93
5abe2da5
TC
94=item public_html
95
96Web server document root. Static pages are generated under this
97directory. Default: $CONTENTBASE.
98
ca9aa2bf
TC
99=item images
100
101Where uploaded images are stored. This is not yet completely
102implemented. Default: $IMAGEDIR.
103
331fd099
TC
104=item libraries
105
106Local search path for BSE::Custom, or the class configured by
107C<custom_class> in [basic].
108
3c32512d
TC
109=item siteuser_images
110
111Where uploaded siteuser images are stored. This must be set in the
112config file. The default bse.cfg include an entry to use the current
113values of [paths].downloads
114
efcc5a30
TC
115=item dynamic_cache
116
117Pregenerated dynamic article pages are stored here. This must be
118defined if you site contains any dynamicly generated pages.
119
195977cd
TC
120=item scalecache
121
122The directory where cached versions of scaled thumbnails are stored.
123Defaults to image_dir/scaled. This must be in the document tree. If
124you set this you should also set scalecacheurl.
125
126=item scalecacheurl
127
128The URL to the directory represented by scalecache. Defaults to
129/images/scaled.
130
61551101
TC
131=back
132
133=head2 [extensions]
134
135This section is used by the file wizard to map uploaded file
136extensions to MIME content types. This can be used to extend
137BSE::FileEditor's internal extension map. It cannot override that
138map.
139
140The key for each entry is the extension, without the leading '.'.
141
142eg.
143
144 xls = application/msexcel
145
146=head2 [templates]
147
148Used for translating symbolic template names into full names under the
149template directory.
150
151In each case the default is the name with a C<.tmpl> extension.
152
153=over
154
155=item user/logon
156
157user logon page
158
159=item user/register
160
161user registration page
162
163=back
164
165=head2 [admin templates]
166
167Used for translating the names of administration templates into filenames.
168
169In each case the default is the name with a C<.tmpl> extension.
170
171=over
172
173=item filelist
174
175article file wizard
176
d2730773
TC
177=item catalog
178
179Catalog editor page. Default admin/edit_catalog.tmpl
180
181=item 1
182
183=item 2
184
185=item 3
186
187=item 4
188
189=item 5
190
191Article edit pages. Default admin/edit_<number>.tmpl
192
193=item steps
194
195Step child/parent management page. Default admin/edit_steps.tmpl
196
61551101
TC
197=back
198
199=head2 [html]
200
201Minor html items.
202
203=over
204
205=item charset
206
207The value of the charset keyword when outputting HTML from a script.
208Set to the empty string to suppress the charset keyword. Default:
209iso-8859-1.
210
5af99440
TC
211=item redirect_links
212
213If this is a non-zero number, then all but mailto links are redirected
214to C<nuser.pl/redirect> so you can display a diclaimer. If this
215contained alphabetics it's treated as a comma separated list of url
216schemes that should be handled via C<nuser.pl/redirect>. If 0 or not
217present, no redirection is done.
218
219The redirect URL includes a hash of the url, title and the redirect
220salt to prevent using this mechanism by external sites for cookie
221stealing attacks.
222
223=item redirect_salt
224
225The salt used in generating the has for redirect_links. Default: an
226empty string.
227
8a3b8db8
TC
228=item validate
229
230If non-zero then any HTML output is validated with HTML::Tidy.
231Validation errors and warnings are sent to the audit log. See [html
232tidy].
233
61551101
TC
234=back
235
236=head2 [basic]
237
238=over
239
240=item cookie_lifetime
241
242The expiry time for cookies. This should be in the form supported by
243CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
244number, and a time character (s - seconds, m - minutes, h - hours, d -
245days, M - months). Default: +3h
246
a8ddb0f3
TC
247=item cookie_domain
248
249This overrides the domain value set for cookies. This is useful if
250you allow the site to run under both example.com and www.example.com,
251if you set cookie_domain to example.com then a user visiting
252www.example.com will still have their cookies when they visit
253example.com.
254
3c8b9c2c
TC
255=item cookie_name
256
257This overrides the cookie name used to store the session id. Default:
258sessionid. This is useful when you have 2 sites under the same
259top-level domain, and helps disambiguate the cookie returned by the
260browser.
261
61551101
TC
262=item minpassword
263
264Minimum password length in characters. Default: 4.
265
b19047a6
TC
266=item randomdata
267
268Device to read random data from. This device should not block when it
269runs out of entropy.
270
6e3d2da5
TC
271=item sign
272
273If this is true then the encrypted messages containing the customer's
274credit card number are sent to the shop owner signed. To avoid
275keeping a passphrase and signing key on the server you can set this to
276false (0). This has the effect that anyone could send you an unsigned
277message encrypted with your public key, though this may not be a
278security threat. Default: True.
279
ca9aa2bf
TC
280=item link_titles
281
282If this is true then the links to your articles within BSE will be
283followed by a / and then by a simplified version of the article title.
284The aim is to include at least some title information in the URL
285without modifying the name of the HTML file. Default: False.
286
9168c88c
TC
287=item access_control
288
289If this is true then the user/group/permissions database is used to
290control access to the system. Default: False.
291
147e99e8
TC
292=item access_filter_steps
293
294If this is true, then the drop-down lists of possible stepparents and
295stepchildren on the article edit pages are filtered for access control.
296Default: False.
297
444957b9
TC
298=item access_filter_parents
299
300If this is true, then the drop-down lists of possible parents on the
301newsletter edit pages are filtered for access control.
302Default: False.
303
d49f56a6
TC
304=item server_auth
305
306Set this to non-zero to enable authentication via server
307authentication (usually Basic Authentication.) You should normally
308set this if you set htusers below. Default: 0 (disabled)
309
9168c88c
TC
310=item htusers
311
312This should be the path to a file to be updated with the list of users
313and crypt() versions of their passwords. If this is set then the
314security system will check for a user set by the browser before
315attempting a form based logon. Default: None.
316
331fd099
TC
317=item custom_class
318
319The name of the custom class for your site. This is currently only
320used for article editing customizations. This class should derive
321from BSE::CustomBase. Default: BSE::Custom.
322
671a9877 323=item jit_dynamic_pregen
efcc5a30
TC
324
325If this is true, then pre-generation for dynamic pages will be delayed
326until the page is displayed to a user. Default: off.
327
74b21f6d
TC
328=item staticajax
329
330If true, the ifAjax and ajax tags will be active for static pages.
331
195977cd
TC
332=item cache_thumbnails
333
334If set to zero the results of the thumbimage/gthumbimage body/template
335tags will not be cached. Default: 1 (caching is enabled).
336
b902f9de
TC
337=item static_thumbnails
338
339If true and cache_thumbnails is true then thumbnails for the thumbnail
340cache will be generated when a static page is regenerated, and the
341link from the page will link to the image in the cache rather than to
342C<thumb.pl>. Default: 1 (static thumbnails enabled).
343
73e6b73a
TC
344=item alias_prefix
345
346The prefix applied to articles that use a linkAlias url. This should
347start with a /.
348
349=item use_alias
350
351If this is non-zero then an article with linkAlias set will use an
352alias url instead of the "real" url. You will need to configure a
353RewriteRule or ErrorDocument to page.pl to direct the user to the
354correct URL. Default: 1.
355
356=item alias_suffix
357
358If this is non-zero then the title is cleaned up (all but
359alphanumerics removed) and appended to the alias URL generated.
360
8a153d74
TC
361=item default_popupimage
362
363This is the default popup image class for the popimage[] and
364gpopimage[] tags. Default: popup.
365
bf909925
TC
366=item warn_obsolete
367
368Some obsolete tags will warn to stderr if this is non-zero. Default:
369don't warn.
370
3f36e485
TC
371=item no_cache_dynamic
372
373If non-zero, the default, dynamic responses will include a
374C<Cache-Control: no-cache> header. This can be overridden for
375articles via , article flags, C<[template >
376I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
377Default: 1.
378
80f59f40
TC
379=item redir_to_alias
380
381If true then page.pl will 301 redirect (Moved Permanently) requests
382for an article by its id to the generated link if the article has a
383link alias. Default: false. Must only be used with use_alias true.
384
4cf6a60c
TC
385=item track_uploads
386
387If this is non-zero, and a cache is configured (see [cache]), file
388uploads are tracked in entries in the cache.
389
390The fileprogress.pl script can be called by Ajax to display file
391upload progress information to the user. The upload state is updated
392a maximum of once a second.
393
dbe8a12a
TC
394=item http_only_session
395
396If this is non-zero, the default, the session cookie sent to the
397browser has the C<HttpOnly> attribute set. This can prevent session
398cookie hijacking. Default: 1.
399
400=item secure_session
401
402If this is non-zero then the session cookie sent to the browser has
403the C<Secure> attribute set. This means that the cookie will only be
404visible over https. This is only useful when the only URL the site is
405visited over is a https URL. Default: 0.
406
407=item make_userid_cookie
408
409If this is non-zero, the default, then when the site member logs in, a
410javascript visible cookie, C<userid> will be set that contains the
411login name of the user. BSE's back-end doesn't use this cookie, its
412only use is for Javascript to enable/disable user interface elements.
413Default: 1.
414
b19047a6
TC
415=back
416
417=head2 [mail]
418
35c0719f 419This section controls how BSE sends email.
b19047a6
TC
420
421=over
422
423=item smtp_server
424
425The host or IP address of your mail server. If this is not set
426C<sendmail> will be used instead. If this is set you must also set
427I<helo>.
428
429=item helo
430
431The name that BSE uses to identify itself when sending mail via SMTP.
432Required if I<smtp_server> is set.
433
434=item sendmail
435
436The path to the C<sendmail> binary. Default: /usr/lib/sendmail
437
438=item sendmail_opts
439
440The options supplied to sendmail. Default: -t -oi
441
442You may want to add the -odq option to this if you want mail queued
443rather than sent immediately.
444
67b69296
TC
445=item set_errors_to_from
446
447If true, we add an Errors-To header set to the same as the From
448header. Default: true.
449
0c2e7f7a
TC
450=item html_system_email
451
452If non-zero then emails sent via the compose mail system that aren't
453being sent to a member record, will be sent as HTML, if the HTML
454template is available.
455
295deb8d
TC
456=item inline_css
457
458If this is C<style> (the default) then use CSS::Inliner to attempt to
459inline CSS in mail if the text "<style" is found in the generated
460HTML.
461
462If this is C<force> then we always attempt to inline CSS.
463
464If this is any other value then don't inline CSS.
465
5a892458
TC
466=item inline_css_flags
467
468A comma separated list of flags to supply to CSS::Inliner->new().
469Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
470attributes, and C<leave_style> to leave the HTML style block in place.
471
472Default: no flags.
473
295deb8d
TC
474=item inline_css_report
475
476If this is true and CSS inlining fails, log an error to the audit
477log. This is intended for use in debugging and should be disabled in
478production. Default: false (disabled)
479
61551101
TC
480=back
481
ca9aa2bf 482=head2 [children of I<id>]
721cd24c
TC
483
484Where I<id> is the identifier for an article.
485
486=over
487
488=item template
489
490the name of the default template for children of the given parent
491
492=item template_dirs
493
494a comma-separated list of extra directories under $TMPLDIR to search
495for templates that can be used for children of the given parent article.
496
497=back
498
ca9aa2bf
TC
499=head2 [article I<id>]
500
501Where I<id> is the identifier of an article.
502
503=over
504
505=item template_dirs
506
507A comma-separated list of extra directories under $TMPLDIR to search
508for templates that can be used for children of the given parent
509article.
510
511=item extra_templates
512
513A comma-separated list of extra templates under $TMPLDIR that can be
514used for the given article.
515
516=back
517
caa7299c
TC
518=head2 [level I<level>]
519
520=over
521
522=item template
523
524The default template for this level of article, assuming it hasn't
525been set in the [children of I<article id>] section.
526
527=item template_dirs
528
529A comma-separated list of extra directories under $TMPLDIR to search
530for templates that can be used for articles at the given I<level>.
531
532=back
533
534=head2 [catalogs]
535
536=over
537
538=item template
539
540The default template for catalogs.
541
542=back
543
544=head2 [products]
545
546=over
547
548=item template
549
550The default template for products.
551
d64413ee
TC
552=item extra_templates
553
554A comma separated list of extra templates that can be used for
555products.
556
caa7299c
TC
557=back
558
61551101
TC
559=head2 [messages]
560
561This can be used to control translation of error messages. Each key
562has a prefix identifying the module that uses the error, followed by
563'/' followed by a specific identifier for the message.
564
565Message parameters, expressed as $I<digit>, are replaced with the
566parameters passed to the message. C<$$> is replaced with C<$>.
567
568Each message identifier below is documented with the id, when it
569occurs, the default message, and any parameters.
570
571=over
572
573=item user/needlogon
574
575the user attempted to logon without entering a logon name. Default:
576"Please enter a logon name". No parameters.
577
578=item user/needpass
579
580the user attempted to logon without entering a password. Default:
581"Please enter your password." No parameters.
582
583=item user/baduserpass
584
585the user's logon name or password was not found or did not match.
586Default: "Invalid user or password". No parameters.
587
588=item user/notloggedon
589
590the user attempted to logoff while not logged on. Default: "You
591aren't logged on". No parameters.
592
593=item user/optsoldpass
594
595the user entered a new password on the options page without entering
596their old password. Default: "You need to enter your old password to
597change your password". No parameters.
598
a53374d2
TC
599=item shop/logonrequired
600
601Displayed if the user attempts to checkout when [shop].require_logon
602is true.
603
61551101
TC
604=back
605
2404a911
TC
606=head2 [downloads]
607
608=over
609
610=item must_be_paid
611
612if non-zero, the order must be marked as paid for before the file can
613be downloaded.
614
615=item must_be_filled
616
617if non-zero the order must be marked as filled before the files can be
618downloaded.
619
4afdbb1b
TC
620=item require_logon
621
622if non-zero the user must be registered/logged on to download I<any>
623file.
624
32696f84
TC
625=item log_downufile
626
627if non-zero, downloads of userfiles will be logged. Default: 0
628
629=item log_downufile_maxage
630
631the maximum age of entries in the user file download log, in days.
632Default: 30.
633
2404a911
TC
634=back
635
b19047a6
TC
636=head2 [confirmations]
637
638Control over confirmation emails.
639
640=over
641
642=item subject
643
644The subject of email confirmation emails. Default: Subcription
645Confirmation.
646
647=item from
648
649The from field for the email. Default: $SHOP_FROM
650
651=back
652
531fb3bc
TC
653=head2 [subscriptions]
654
655Control over subscription messages.
656
657=over
658
659=item from
660
661The from field for the email. Default: $SHOP_FROM.
662
d09682dd
TC
663=item testname
664
665Default for the "Test Name" field for sending test subscription
666messages.
667
668=item testemail
669
670Default for the "Test Email" field for sending test subscription
671messages.
672
673=item testtextonly
674
675Set to 1 if you want the "Test Text Only" box checked by default for
676sending test subscription messages.
677
678=item testing
679
680Set to 0 to disable display of the test subscription messages portions
681of the subscriptions send form.
682
99b7cef0
TC
683=item text_link_inline
684
685Set to format links as they appear in the text version of emails.
686C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
687the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
688
689=item text_link_list
690
691Set to format links as they appear at the footer of the body text. If
692this is set to the empty string then no list appears. C<$1>, C<$2>,
693C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
694replaced with newline. Default: C<[$3] $2>
695
696=item text_link_list_prefix
697
698A line of text produced above the list of URLs if there is one.
699Default: C<----->. $n in this is replaced with newlines.
700
531fb3bc
TC
701=back
702
99b7cef0
TC
703For example, if the configuration is:
704
705 text_link_inline="$1" ($3)
706 text_link_list_prefix=$n$n-------
707 text_link_list=($3) "$1"$n => $2
708
709and the body text is:
710
711 doclink[3]
712 link[http://www.example.com/|Example]
713
714the result will be:
715
716 "The Shop" (1)
717 "Example" (2)
718
719
720 -------
721 (1) "The Shop"
722 => http://www.yoursite.com/shop/index.html
723 (2) "Example"
724 => http://www.example.com/
725
6e3d2da5
TC
726=head2 [search]
727
728=over
729
730=item highlight_partial
731
732If this is true then partial matches will be highlight in search
733result excerpts. Default: True
734
54c97cf6
TC
735=item keep_inaccessible
736
737If this is true then resulting articles that can't be accessed by the
738user are listed in the search results. Default: false.
739
d401b996
TC
740=item wordre
741
742The default regular expression used to match words in text during
743indexing. Default: \w+
744
745=item wordre_I<fieldname>
746
747The field specific word match regular expression for the built-in
748search indexer. Default: the value of C<wordre>.
749
65ad6c28
TC
750=item indexer
751
752Module used to build the search index. Default: BSE::Index::BSE.
753
754=item index_priority
755
756For C<BSE::Index::BSE>, the optimization priority. The default of
757C<speed> builds the index in memory and is very fast, but can consume
758a lot of memory. Otherwise, set this to C<memory> to reduce memory
759usage.
760
761C<memory> priority index building requires that the DBM::Deep module
762be installed.
763
6e3d2da5
TC
764=back
765
61693c75
TC
766=head2 [search highlight]
767
768Sets the prefix and suffix used for highlighting matches for different
769fields.
770
771These are used by the highlight_result, excerpt, pageTitle, author,
772keywords and matchFile tags.
773
774Each field has a prefix and suffix entry. The key is
775I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
a9634cc9 776file_I<fieldname>_prefix and file_I<fieldname>_suffix.
61693c75
TC
777
778The default prefix is <b>. The default suffix is </b>.
779
780For example you can do:
781
782 [search highlight]
783 body_prefix=<span class="searchfound">
784 body_suffix=</span>
785
6e3d2da5
TC
786=head2 [shop]
787
788=over
789
7b81711b
TC
790=item enabled
791
792Used by some templates to check if the shop is enabled. Set this to 1
793to enable the shop, or 0 to disable it.
794
57d988af
TC
795=item secureurl_articles
796
797If this is false then shop articles will not use the secureurl as their
798baseurl. Default: True
799
6e3d2da5
TC
800=item register_if_files
801
802If true the customer is required to register before checkout if there
803are any for sale files attached to products in the cart. Default: True
804
805=item require_logon
806
807If true the customer is required to be logged on before checkout,
808whether or not for sale files are attached to products in the cart.
809Default: False.
810
08123550
TC
811=item payment_types
812
813A comma-separated list of acceptable payment types. Default: 0
814
815The possible payment types are:
816
817=over
818
819=item *
820
8210 - the user enters a credit card number, name and expiry date
822
823=item *
824
8251 - the customer will send a cheque
826
827=item *
828
8292 - contact customer for details
830
13a986ee
TC
831=item *
832
40cc2f24 8334 - paypal - see L<paypal.pod>
13a986ee 834
08123550
TC
835=back
836
81f3292d
TC
837Other types can be added by adding entries to the [payment type names]
838and [payment type descs] sections.
839
08123550
TC
840=item address1
841
842=item address2
843
844=item address3
845
846These are used by various shop templates to present an address that a
847cheque payment should be sent to.
848
331fd099
TC
849=item from
850
851From email address for emails sent by the shop. Overides $SHOP_FROM
852in Constants.pm
853
854=item to_name
855
856To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
857in Constants.pm
858
859=item to_email
860
861To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
862in Constants.pm
863
d9a3fa87
TC
864=item bcc_email
865
866BCC email address for order confirmation emails sent to the customer.
867Default: No bcc.
868
d09682dd
TC
869=item noencrypt
870
871If this is true then orders sent to you by the shop will not be
872encrypted. Enabling this disabled acceptance of credit card orders,
873and the default for C<payment_types> will become C<1> instead or C<0>.
874
875Please realize that other potentially commercially sensitive
876information is being sent in the clear to a central location,
877unencrypted.
878
879=item email_order
880
881If true, then the order is email to to_email, possibly with credit
882card information included. Default: $SHOP_EMAIL_ORDER.
883
d49f56a6
TC
884=item display_I<field>
885
886Used to translate the stored order field name into a presentation name
887suitable for error messages.
888
41e7c841
TC
889=item cardprocessor
890
891The name of a class to load to process credit card transactions online.
892
893Currently this can be either DevHelp::Payments::Test or
894DevHelp::Payments::Inpho.
895
26c634af
TC
896=item crypt_module
897
898Name of the encryption module to use. Default: $SHOP_CRYPTO.
899
900=item crypt_signing_id
901
902Id of the key to sign the order email with. If this is non-empty then
903the email is signed even if [basic].sign is false. Default:
904$SHOP_SIGNING_ID.
905
906=item crypt_gpg
907
908Path to the GnuPG program. Default: $SHOP_GPG
909
745a6c13 910=item crypt_passphrase
26c634af
TC
911
912Passphrase of the key used to sign the email. Default:
913$SHOP_PASSPHRASE.
914
745a6c13
TC
915=item show_card_type
916
917If true, request the card type when requesting credit card
918information. Default: False.
919
56f87a80
TC
920=item cart_entry_limit
921
922Maximum number of entries in the cart. This limits the number of
923distinct products (with options) in the cart, not the total
924quantities. Default: Unlimited.
925
d99ed4c4 926=item currency_code
13a986ee
TC
927
928The shop currency as a 3-letter currency code. Default: AUD.
929Currencies other than "AUD" aren't supported by most of the system.
930
40cc2f24
TC
931=item country_code
932
933Set to non-zero if you're using country codes in the order country
934field. If this is set then the delivCountry is supplied as is to
935various parts of the system, otherwise it is translated from a country
936name to a country code. Default: 0.
937
6e3d2da5
TC
938=back
939
bd3a048c
AMS
940=head2 [shipping]
941
942=over
943
944=item couriers
945
946A space-separated list of modules under Courier::, e.g. "Fastway::Road
947AustraliaPost::Air". These will be made available as shipping methods
948on the checkout page.
949
950=item sourcepostcode
951
952The post code from which products are shipped.
953
954=item fastwayfranchisee
955
956The name of the Fastway franchisee used to ship products from the
957sourcepostcode.
958
959=item fastwayfranchiseecode
960
961The Fastway franchisee code for the customer, if any.
962
963=back
964
41e7c841
TC
965=head2 [Shop Order Validation]
966
967This section can contain extra order validation information, including
968specifying required fields, display names and extra validation rules.
969
6e3d2da5
TC
970=head2 [fields]
971
972=over
973
974=item title_size
975
976The maximum length of the article title field. Default: 255. Should
977not be set higher than this unless you change the database schema.
978
979=back
980
ee6577c3
TC
981=head2 [interest]
982
983Controls the interest.pl script.
984
985=over
986
987=item notify
988
989Email address that is notified of the interest. Defaults to $SHOP_FROM.
990
ca9aa2bf 991=back
ee6577c3 992
6e3d2da5
TC
993=head2 [debug]
994
995Used for debugging.
996
997=over
998
999=item logon_cookies
1000
1001When a user logs on, and the site url is different to the secure url
1002BSE attempts to refresh to the other "side" of the site to set the
1003same cookie.
1004
1005BSE does some simple comparisons to attempt to determine whether the
1006logon form was triggered on the secure side of the site (possibly from
1007the shop) or on the insecure side. Since CGI doesn't necessarily give
1008us all the information required, it's possible it will guess wrong.
1009
d2730773
TC
1010Setting this option to 1 will enable debugging information sent to
1011standard error, which will be sent to the error log on Apache. This
1012probably isn't useful on IIS.
1013
1014=item file_unlink
1015
1016Reports errors to STDERR (hence to the error log on Apache) if there
1017is a problem deleting the actual file when an attached file is
1018removed.
1019
1020=item mail_encryption
1021
1022Reports debugging information to standard error while encrypting your
1023mail.
6e3d2da5 1024
2d873eb6
TC
1025=item cookies
1026
1027Reports cookies received from the browser and sent to the browser to
1028STDERR (hence to the error log on Apache.)
1029
4175638b
TC
1030=item dump_session
1031
1032If nonzero the session hash is dumped to STDERR after it is retrived
1033from the database.
1034
af74f0b4
TC
1035=item subscription_expiry
1036
1037If non-zero then subscription expiry date calculations are dumped to
1038STDERR.
1039
efcc5a30
TC
1040=item jit_dynamic_regen
1041
1042If non-zero then information about jit_dynamic_regen is sent to
1043STDERR.
1044
db7d73a7
TC
1045=item ifUserCan
1046
1047If non-zero then the ifUserCan tag will output some trace information
1048to STDERR.
1049
ca9aa2bf
TC
1050=back
1051
1052=head2 [uri]
1053
1054Contains various URIs.
1055
1056This is underused, so don't rely on it yet.
1057
1058=over
1059
1060=item cgi
1061
1062The URI to the CGI directory. Default: /cgi-bin
1063
1064=item images
1065
1066The URI where images are kept. Default: /images
1067
1068=item shop
1069
1070=item articles
1071
9168c88c 1072=back
ca9aa2bf 1073
9168c88c 1074=head2 [articles]
ca9aa2bf 1075
9168c88c
TC
1076This will provide translations from symbolic names to article ids.
1077
1078Currently this is used for converting article ids in the access
1079control code, and for looking up the id of the shop.
6e3d2da5 1080
0b406a07
TC
1081=head2 [printable type]
1082
1083If the user supplies a template name to printable.pl then you can use
1084a different content type by adding an entry to this section. The key
1085is the template name, and the value is the full content type.
1086
918735d1
TC
1087=head2 [search index scores]
1088
1089This section is used when generating the search index to override the
1090default scores for each field in the articles.
1091
1092The default scores are:
1093
74b21f6d
TC
1094 Field Score Notes
1095 ----- ----- -----
1096 title 5
1097 body 3
1098 keyword 4
1099 pageTitle 5
1100 author 4
1101 summary 0
1102 description 0 Products only
1103 product_code 0 Products only
1104 file_displayName 2 displayName for files
1105 file_description 2 description for files
1106 file_notes 1 notes for files
918735d1
TC
1107
1108=head2 [article flags]
1109
1110=head2 [product flags]
1111
1112=head2 [catalog flags]
1113
1114Flags that can be set for articles, products and catalogs
1115respectively. Note that flags for articles are also visible in
1116products and catalogs.
1117
1118All flag Ids are single letters or digits. Uppercase letters are
1119reserved for use by BSE internally, leaving lower-case letters and
1120digits for your own use.
1121
1122Use the id of the flag as the key, and a description of the flag as
1123it's value.
1124
95989433
TC
1125=head2 [article uris]
1126
1127Each key is an article id, the values are base URIs to store the HTML
1128form of those articles and their children under.
1129
1130=head2 [protect link]
1131
1132The keys are ids of articles that shouldn't have their link field
1133overwritten. The value should be a true value, but is otherwise
1134ignored.
1135
d09682dd
TC
1136=head2 [datadump]
1137
1138=over
1139
1140=item to
1141
1142The recipient for the data dump email sent by datadump.pl. Default:
1143$DATA_EMAIL.
1144
1145=item from
1146
1147the From for the data dump email sent by datadump.pl. Default:
1148$SHOP_FROM.
1149
1150=back
1151
2a295ea9
TC
1152=head2 [site users]
1153
1154Configuration for site users.
1155
1156=over
1157
1158=item nopassword
1159
1160If this is set to true then no passwords are required during
1161registration, a confirmation email is sent immediately upon
1162registration and that confirmation email contains a link the user can
1163use to manage their details.
1164
1165This option has some security concerns since it can leave links to the
1166user's information in the browser history. This option is not
1167recommended.
1168
1169You cannot use this to control access to the shop.
1170
1171=item require_name1
1172
1173=item require_name2
1174
1175=item require_address
1176
1177=item require_city
1178
1179=item require_state
1180
1181=item require_postcode
1182
1183=item require_telephone
1184
1185=item require_facsimile
1186
1187=item require_country
1188
1189=item require_title
1190
1191=item require_organization
1192
1193Set these to true to require the corresponding field during
1194registration, and to keep it required after modification. Default:
1195false.
1196
1197If you enable any of these, you should enable C<info_on_register> as
1198well, or modify the registration template to include the given fields.
1199
1200=item display_I<field name>
1201
1202Controls how the given field is displayed in error messages. If you
1203change the field names on the registration and/or options forms you
1204should probably change them here too. Default: internal field name
1205with the first character converted to upper-case.
1206
1207=item info_on_register
1208
1209If this is set then the user info is prompted for during user
1210registration. The information still isn't required unless the
1211appropriate require_I<field> option is set. Default: false.
1212
1213=item register_refresh
1214
1215The default URL to refresh to on completing registration if no r
1216parameter is supplied.
1217
1218=item subscribe_all
1219
1220If this is set then the subcription checkboxes are all checked on
1221registration by default. Default: false.
1222
1223The user will only receive the subscriptions if they leave them checked
1224and follow the link in the confirmation email.
1225
1226=item subscribe_I<id>
1227
1228Where I<id> is the number identifying a subscription. If this is set
1229then the subscription checkbox for that subscription will be checked
1230by default on the registration form. Default: false.
1231
1232The user will only receive the subscriptions if they leave it checked
1233and follow the link in the confirmation email.
1234
1235You can get the I<id> of a subcription by looking at the Edit link on the
1236subscriptions management page, the number after "id=" is the id.
1237
9063386f
TC
1238=item billing_on_main_opts
1239
1240If set to zero then user billing options will be managed on a separate
1241page. This is controlled by the user/options_base.tmpl template.
1242
1243=item user_register
1244
1245If set to zero then users cannot register themselves. Default: true,
1246allowing users to register themselves.
1247
cf9f9cbc
TC
1248=item notify_register
1249
1250If true then an email is sent when a new user registers on your site.
1251The email address sent to is the first set of [site
1252users].notify_register_email, [shop].from or $SHOP_FROM from
1253Constants.pm
1254
1255No email is sent if a new user is created from the administration user
1256interface.
1257
1258See also: notify_register_email, notify_register_subject.
1259
1260=item notify_register_email
1261
1262The email to sent the registration notification too. See
1263notify_register above.
1264
1265=item notify_register_subject
1266
1267The subject of the notification email sent when a new user registers.
1268Any {I<field>} is replaced with the given field from the registered
1269user. See notify_register above.
1270
1271Default: New user {userId} registered
1272
6c83a514
TC
1273=item notify_register_customer
1274
1275If non-zero then email id C<notify_register_customer> will be sent to
1276new user on registration. By default this uses template
1277user/email_register, subject "Thank you for registering" which can be
f197f061
TC
1278overridden in [email notify_register_customer] or via the
1279C<set_subject> tag.
1280
1281=item notify_register_customer_admin
1282
1283If non-zero then the behaviour described for
1284C<notify_register_customer> will take place when a new member is added
1285by an administrator. Defaults to the value of
1286C<notify_register_customer>.
6c83a514 1287
2a295ea9
TC
1288=back
1289
81f3292d
TC
1290=head2 [payment type names]
1291
1292This section and [payment type descs] are used to configure new
1293paymeny type ids.
1294
1295The key is the integer representing the payment type. The value is
1296the name used in tags for checking the payment type.
1297
1298You can also add a description (currently unused) to [payment type
1299descs].
1300
1301You should use numbers starting from 10 to avoid conflicts with future
1302BSE payment types.
1303
1304=head2 [payment type descs]
1305
1306See [payment type names].
1307
1308=head2 [payment type required]
1309
1310Set the key given by the payment type id to a value of a
1311comma-separated list of fields required for that payment type.
1312
3ae524f3
TC
1313=head2 [help style I<style-name>]
1314
1315This type of configuration section is used to set values for a style
1316of help icon. Only the C<template> and C<prefix> values are used
1317directly by the code, the others are used by the default helpicon
1318templates.
1319
1320=over
1321
1322=item prefix
1323
1324The URI to the help files for this style. Default: /help/ in style
1325"user", /admin/help/ in style "admin".
1326
1327=item template
1328
1329The template used to produce the icon. Default: helpicon in style
1330user, admin/helpicon in style "admin".
1331
1332=item icon
1333
1334URI to the help icon image. Default: /images/admin/help.gif
1335
1336=item iconwidth
1337
1338The width of the help icon image. Default: 16
1339
1340=item iconheight
1341
1342The height of the help icon image. Default: 16
1343
1344=back
1345
1346If you just want to change the help icon image for user help icons you
1347might do:
1348
1349 [help style user]
1350 icon=/images/help.gif
1351
4175638b
TC
1352=head2 [affiliate]
1353
1354=over
1355
1356=item allowed_referer
1357
1358A semi-colon (;) separated list of referer domains that are allowed to
1359link to the C<a_set> target of L<affiliate.pl>.
1360
1361If the user's browser supplies a referer header then it will be
1362checked against this list.
1363
1364=item require_referer
1365
1366If this is set then the C<a_set> target of L<affiliate.pl> will
1367require that the user's browser supply a Referer header.
1368
1369=item default_refresh
1370
1371If no C<r> parameter is supplied to the C<a_set> target of
1372L<affiliate.pl> then this is used as the default refresh.
1373
1374Default: the site base url.
1375
829c9ed9
TC
1376=item subscription_required
1377
1378This is either the numeric or text of a subscription for which the
1379affiliate must have an active subscription.
1380
fdc2b7a2
TC
1381=item flag_required
1382
1383A single letter flag which the site administrator must set for the
1384affiliate page to be displayed for the given member.
1385
ea646070
TC
1386=item set_cookie
1387
1388If this is set then affiliate.pl will set the named cookie to the
1389affiliate id.
1390
1b5a718f
TC
1391=item other_cookies
1392
1393This is a comma-separated list of other cookies that should be set by
1394the a_set target. The values for the cookies should be passed to the
1395a_set target. For example with:
1396
1397 [affiliate]
1398 other_cookies=alpha,beta
1399
1400if the url:
1401
1402 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1403
1404is accessed, then the cookie alpha is set to "1", beta is set to "2".
1405The cookie gamma will not be set since it's not listed.
1406
ea646070
TC
1407=item linkbaseurl
1408
1409Used as the link base URL for the afflink.tmpl side bar template when
1410an affiliate id is set. Default: example.com
1411
1412=item linkbasedesc
1413
1414Used at the text of the link for the afflink.tmpl side bar template
1415when an affiliate id is set. Default: Your Site.
1416
1417=item linkdefurl
1418
1419Used as the link URL for the afflink.tmpl side bar template when an
1420affiliate id is not set. Default: example.com
1421
1422=item linkdefdesc
1423
1424Used as the text of the link for the afflink.tmpl side bar template
1425when an affiliate id is not set. Default: Our site
1426
4175638b
TC
1427=back
1428
3c32512d
TC
1429=head2 [BSE Siteuser Images]
1430
1431Each key is the id of a member image, with a corresponding [BSE
1432Siteuser Image I<image_id>] section. The values are ignored.
1433
1434=head2 [BSE Siteuser Image I<image_id>]
1435
1436Provides information about a single member image "template".
1437
1438=over
1439
1440=item description
1441
1442Short description on the image, like "Logo". Used in error messages.
1443
1444=item help
1445
1446Longer description of the image. Accessible with the member_image tag.
1447
1448=item minwidth
1449
1450=item minheight
1451
1452=item maxwidth
1453
1454=item maxheight
1455
1456The minimum and maximum dimensions of the image.
1457
1458=item widthsmallerror
1459
1460=item heightsmallerror
1461
1462=item widthlargeerror
1463
1464=item heightlargeerror
1465
1466Error messages displayed in the when the image is outside the
1467configured dimensions.
1468
1469=item largeerror
1470
1471=item smallerror
1472
1473Default error messages for the above.
1474
1475=item maxspace
1476
1477Maximum storage the image can use in bytes. Default: 1000000.
1478
1479=item spaceerror
1480
1481Error message displayed if the image uses too much storage.
1482
1483=back
1484
ab2cd916
TC
1485=head2 [editor]
1486
1487Various editor settings.
1488
1489=over
1490
1491=item allow_thumb
1492
1493If this is non-zero the system will attempt to load the configured
1494thumbnail class, and put thumbnail images on the image manager page
1495rather than full-size images. Default: off
1496
1497=item thumbs_class
1498
1499The name of a perl class that implement's BSE's thumbnail API. At
1500this point the only class that implements that is BSE::Thumb::Imager,
1501supplied with BSE. Default: None
1502
1503=item default_thumbnail
1504
1505URI to the default thumbnail image. This is presented when the
1506runtime production of a thumbnail image fails.
1507
1508=item default_thumbnail_width
1509
1510=item default_thumbnail_height
1511
1512Dimensions of the default thumbnail image.
1513
1514=item default_thumbnail_alt
1515
1516Alt text for the default thumbnail image.
1517
1761af79
TC
1518=item check_modified
1519
1520If this is true then BSE will check the value of the lastModified
1521parameter passed against the value in the article. If these don't
1522match the article isn't saved and is redisplayed with an error
1523message. This provides simple protection against one user saving
1524changes over those made by another.
1525
ab2cd916
TC
1526=back
1527
1528=head2 [thumbnails]
1529
1530=over
1531
1532=item max_width
1533
1534=item max_height
1535
1536=item max_pixels
1537
1538Default values for the thumbimage tag.
1539
1540=back
1541
829c9ed9
TC
1542=head2 [includes]
1543
1544Each value is used as the relative or absolute name of a file or
1545directory to load more configuration data from.
1546
1547The keywords must remain unique.
1548
1549Only the [includes] section from bse.cfg itself is used to locate more
1550configuration data.
1551
1552If the value references a directory, all files with an extension of
1553C<.cfg> are read for configuration data.
1554
1555The order the files are read (which later files overriding older
1556files) is:
1557
1558=over
1559
1560=item 1.
1561
1562bse.cfg is read
1563
1564=item 2.
1565
1566the entries in [includes] are sorted alphabetically (or rather
1567asciily), so an entry with key "A" is read before one with key "B",
1568one with key "01" is read before "02", but key "10" would be read
1569I<before> key "2".
1570
a9634cc9 1571=item 3.
829c9ed9
TC
1572
1573if an entry is a file then that is read and the values merged.
1574
a9634cc9 1575=item 4.
829c9ed9
TC
1576
1577if an entry is a directory, then that is scanned and the files found
1578read alphabetically as above.
1579
1580=back
1581
6a8a6ac5
TC
1582=head2 [error_img]
1583
1584This is used to configure the error icon displayed next to fields that
1585fail validation.
1586
1587=over
1588
1589=item image
1590
1591URI to the image file.
1592
1593=item width
1594
1595=item height
1596
1597The width and height of the error icon image.
1598
1599=back
1600
fdc2b7a2
TC
1601=head2 [site user flags]
1602
1603Flags that can be set for site users.
1604
1605All flag Ids are single letters or digits. Uppercase letters are
1606reserved for use by BSE internally, leaving lower-case letters and
1607digits for your own use.
1608
1609Use the id of the flag as the key, and a description of the flag as
1610it's value.
1611
deae2a52
TC
1612=head2 [article defaults]
1613
1614=head2 [catalog defaults]
1615
1616=head2 [product defaults]
1617
1618These sections contain defaults values for the corresponding article
1619types.
1620
1621Each key is the name of a column for the article type.
1622
1623If an entry is not found in [catalog defaults] then [article defaults]
1624is also checked.
1625
1626If an entry is not found in [product defaults] then [article defaults]
1627is also checked.
1628
1629These sections are checked B<after> the C<[children of >I<id>C<]> and
1630C<[level >I<level>C<]> sections.
1631
1632These defaults are used when creating an article where no value is
1633supplied, they can also be accessed via the <:default I<name>:> tag.
1634
1c3e5303
TC
1635=head2 [newsletter filters]
1636
1637Contains C<criteria>I<index> entries starting from C<criteria1>, then
1638C<criteria2>, etc.
1639
1640Each entry consists of a filter class name, followed by a ; followed
1641by data passed to that filter.
1642
1643 ; user the original SQL based filter, configured from
1644 ; section [foo]
1645 criteria1=BSE::NLFilter::SQL;foo
1646
1647See the documentation for each filter to configure the filters.
1648
c2096d67
TC
1649=head2 [Query Groups]
1650
1651The key of each entry is the numeric identifier of a query group, the
1652values are the name of the query group. For example:
1653
1654 [query groups]
1655 1=some name
1656
1657 [query group some name]
1658 sql=select id from site_users where id = ? and name1 like '%some%'
1659
1660Each entry also has a corresponding [Query Group I<name>] section.
1661
1662=head2 [query group I<name>]
1663
1664This section corresponds to an entry in [Query Groups].
1665
1666=over
1667
1668=item sql
1669
1670This is an SQL statement. One placeholder is required and is passed
1671the siteuser id (primary key) of the user to be checked. If this
1672query returns I<any> rows then the user is considered part of the
1673group.
1674
1675=back
1676
16901a2a
TC
1677=head2 [template types]
1678
1679Each key is a template name, the value is the content type to be used
1680when displaying the template dynamically.
1681
fea96500
TC
1682=head2 [template descriptions]
1683
1684Each key is a template name, the value is a description used in the
1685template dropdown for that template.
1686
8f84f3f1
TC
1687=head2 [body class]
1688
1689This section defines CSS class names for BSE's body text link tags.
1690The key is the tag name, the value is the CSS class to be used.
1691
1692By default the class used is the same as the name of the tag, but you
1693can switch this off by adding an entry setting the class to the empty
1694string, for example:
1695
1696 ; no class attribute for any of the links
1697 [body class]
1698 link=
1699 poplink=
1700 doclink=
1701 popdoclink=
1702
1703You can set p here too to set the class for paragraphs generated as
1704body text. By default no class is set.
1705
def1a923
TC
1706=head2 [popimage]
1707
1708Controls the behaviour of the window displayed by the popimage[] body
1709text tag. If the Javascript for this has been customized then this
1710may not apply.
1711
1712=over
1713
1714=item extrawidth
1715
1716=item extraheight
1717
1718Extra width and height for the window beyond the size of the image.
1719Default: no extra width or height.
1720
1721=item popmiddle
1722
1723If set to non-zero popimage[] will attempt to centre the popup within
1724the current window. Default: 0.
1725
1726=back
1727
1728=over
1729
1730=back
1731
41e7c841
TC
1732=head2 [inpho]
1733
1734This is used to configure the DevHelp::Payments::Inpho module.
1735
1736=over
1737
1738=item test
1739
1740If this is set then the test parameters are used instead of the
1741product values.
1742
1743=item url
1744
1745The URL to process requests through.
1746
1747Default: https://extranet.inpho.com.au/cc_ssl/process
1748
1749=item user
1750
1751Inpho supplied user name.
1752
1753=item password
1754
1755Inpho supplied password.
1756
1757=item test_url
1758
1759The URL to process test requests through.
1760
1761=item test_user
1762
1763The user to supply to test requests.
1764
1765=item test_password
1766
1767The password to supply to test requests.
1768
1769=back
1770
f2bf0d11
TC
1771=head2 [custom]
1772
1773This section controls whether some custom class methods are called:
1774
1775=over
1776
1777=item saveopts
1778
1779If this is non-zero then siteuser_saveopts is called.
1780
1781=back
1782
0a66f55c
AO
1783=head2 [levelI<level> menus]
1784
1785Where I<level> is the article level at which the defined menu options will be available.
1786Configure each menu value and description as I<key> and I<value>.
1787
1788=over
1789
1790For example:
1791
1792 [level1 menus]
1793 0=Default
1794 1=Sidebar
1795 2=Footer
1796
1797To create a menus using such values, use the "allkids_of" iterator "filter" option.
1798
1799For example:
1800
1801 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1802
1803=back
1804
37726cc9
AO
1805=head2 [title alias]
1806
1807Enable the "titleAlias" article field and set which level it will be available.
1808
1809=over
1810
1811=item levelI<level>
1812
1813Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1814set the value to non-zero.
1815
1816For example:
1817
1818 [title alias]
1819 level1=1
1820
1821The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1822for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1823in place of the article "title" when appropriate.
1824
1825=back
1826
195977cd
TC
1827=head2 [thumb geometries]
1828
1829Each key represents a geometry identifier for use by the thumbimage[],
1830gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
b864cc90 1831...:>, <:dthumbimage ...:> template tags.
195977cd
TC
1832
1833The key is the geometry identifier, the value is the geometry string
1834as follows.
1835
1836The geometry string consists of:
1837
1838=over
1839
1840=item *
1841
1842dimensions
1843
1844=item *
1845
1846crop flag - if present
1847
1848=item *
1849
1850optional fill
1851
1852=back
1853
1854The dimensions can be in any of the following forms:
1855
1856=over
1857
1858=item *
1859
1860<width>x<height> - the desired maximum width and height. eg 200x150
1861
1862=item *
1863
1864<width>x - the desired width, with the height calculated
1865proportionally based on the source image size
1866
1867=item *
1868
1869x<height> - the designed height, with the width calculated
1870proportionally based on the source image size.
1871
1872=item *
1873
1874<size> - the desired maximum size in both directions. so "200" is
1875equivalent to "200x200"
1876
1877=back
1878
1879The crop flag is a single letter "c", if present then the image should
1880be scaled so the smaller dimension matches the requested size, and the
1881longer dimension will be cropped to fit.
1882
1883The fill if present is: fill(color) where color is a color recognized
1884by the underlying graphics implementation. This should be at least
1885hex web colors without the #, eg fill(FF0000) will fill with red.
1886
b864cc90
TC
1887=head2 [thumb classes]
1888
1889Each key represents a geometry identifier for use by the thumbimage[],
1890gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1891...:>, <:dthumbimage ...:> template tags.
1892
1893The value is used as the class for the generated img tag.
1894
510a9ee7
TC
1895=head2 [targets]
1896
1897Each value represents a handler or script name for the <:dyntarget
1898I<script> I<target> ...:> tag.
1899
1900Each key has a TARGET version and a no-TARGET version, with the key
1901suffixed with C<_n>.
1902
1903The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1904default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1905
1906For other targets the default is
1907C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1908C</cgi-bin/>I<script>C<.pl>.
1909
1910The string C<TARGET> is replaced with the target specified in the
1911dyntarget tag.
1912
1913This, along with dyntarget is intended to allow a more "Web 2.0" type
1914of access to BSE. eg. you might set:
1915
1916 [targets]
1917 shop=/xshop/TARGET
1918 shop_x=/xshop/
1919
1920and have a rewrite rule:
1921
1922 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
1923
8a153d74
TC
1924=head2 [popimage class I<classname>]
1925
1926This defines the settings for a class of images generated by the
1927popimage[] and gpopimage[] body text markup tags. For example, the
1928settings for C<popimage[imageid|foo]> can be found in section
1929C<[popimage class foo]>.
1930
1931=over
1932
1933=item html
1934
1935The html generated for this class. Tags of the form
1936C<{>I<identifier>C<}> are replaced, where I<identifier> can be
1937C<inline_> or C<outline_> followed by an image field name, for example
1938C<inline_src> is the URL to the inline image.
1939
1940Default: <a href="{outline_src}" rel="lightbox[id]" target="_blank"><img src="{inline_src}" alt="{inline_alt}" width="{inline_width}" height="{inline_height}" border="0" /></a>
1941
1942The default may be tuned as needed.
1943
1944=item inline
1945
1946The inline image geometry. Default: editor (the value used for
1947thumbnails on the admin side)
1948
1949=item outline
1950
1951The outline image geometry. If no value is supplied then the original
1952image values are used.
1953
1954=back
1955
0c2e7f7a
TC
1956=head2 [mail resources]
1957
1958Each key is the identifier of a file that can be attached to
1959BSE::ComposeMail emails. The value is comma separated filename,
1960content type, inline status.
1961
1962The files are searched for through the template search mechanism, so
1963the filename can be relative to either the master or local templates
1964directories.
1965
1966If the content type is not supplied, if the filename end in gif, png
1967or jpg the appropriate content type is used, otherwise
1968application/octet-stream.
1969
1970If the inline status is not supplied then images are considered
1971inline, and other files arent.
1972
a53374d2
TC
1973=head2 [shop registration]
1974
1975Each key represents a message id from attempts to checkout. Except
1976the all key which covers all cases.
1977
1978If the C<all> key or the message id key is non-zero then the checkout
1979page will redirect to registration instead of login if the cart or
1980configuration requires that the user be logged in.
1981
3f36e485
TC
1982=head2 [template I<template-name>]
1983
1984Settings for articles based on a particular template.
1985
1986=over
1987
1988=item no_cache_dynamic
1989
1990Controls whether a cache-control: no-cache header will be produced.
1991Can be overridden with the A and B article flags. If not set the
1992value of [article].no_cache_dynamic is used.
1993
1994=back
1995
1996=head2 [article]
1997
1998Global settings for articles.
1999
2000=over
2001
2002=item no_cache_dynamic
2003
2004Controls whether a cache-control: no-cache header will be produced.
2005Can be overridden with the A and B article flags or [template
2006I<template-name>].no_cache_dynamic. If not set the value of
2007[basic].no_cache_dynamic is used.
2008
2009=back
2010
c6fc339f
TC
2011=head2 [recaptcha]
2012
2013For the <:recaptcha:> tag currently only used for fmail.pl.
2014
2015=over
2016
2017=item api_public_key
2018
2019=item api_private_key
2020
2021The public and private key you receive when you register with reCAPTCHA.
2022
2023=item error_I<error_code>
2024
2025Replace the error message for the given I<error_code> where
2026I<error_code> is the reCAPTCHA error code
2027(eg. "incorrect-captcha-sol") with dash replaced by underscore.
2028
2029eg.
2030
2031 error_incorrect_captch_sol=VERY BAD INPUT
2032
2033=back
2034
36e373a9
TC
2035=head2 [global file metadata]
2036
2037Each key represents an item of metadata for files attached to
2038articles.
2039
2040The values are ignored.
2041
2042For each key, extra information is defined in the [file metadata
2043I<name>] section.
2044
2045=head2 [file metadata I<name>]
2046
2047Definition for the file metadata item I<name>.
2048
2049=over
2050
2051=item *
2052
2053title - descriptive name of the metadata. Defaults to I<name>.
2054
2055=item *
2056
2057rules - validation rules, separated by ;. Custom rules can be defined
2058in [file metadata validation].
2059
2060=item *
2061
2062ro - if non-zero the metadata cannot be modified directly by the admin
2063(applications can still generate it). Default: writable.
2064
2065=item *
2066
2067type - the data type of the metadata, any of string, text, enum,
2068integer, real, image. If this is enum values must be defined and
2069labels should be. Default: string.
2070
2071The types are:
2072
2073=over
2074
2075=item *
2076
2077string - single line of text
2078
2079=item *
2080
2081text - one or more lines of text
2082
2083=item *
2084
2085integer - whole number
2086
2087=item *
2088
2089real - number with decimal points
2090
2091=item *
2092
2093enum - select from a list of possible values.
2094
2095=item *
2096
2097image - image file.
2098
2099=back
2100
2101=item *
2102
2103values - semi-colon separated list of values for this metadata.
2104
2105=item *
2106
2107labels - semi-colon separated list of labels for the values
2108
2109=item *
2110
2111help - help html to display for the metadata
2112
2113=item *
2114
2115data_name - (images only) the key to use to store the image data.
2116Default: I<name>_data.
2117
2118=item *
2119
2120width_name - (images only) the key to use to store the image width.
2121Default: I<name>_width.
2122
2123=item *
2124
2125height_name - (images only) the key to use to store the image height.
2126Default: I<name>_height.
2127
2128=item *
2129
2130cond - a perl expression indicating whether the metadata should be
2131prompted for, for this file. $file is the file object. Default: 1.
2132
2133=item *
2134
2135unit - text displayed after the entry box for the metadata. Default:
2136empty. Useful for including a unit ("pixels") or format help
2137("hh:mm").
2138
2139=back
2140
bede67d9
TC
2141=head2 [session cleanup]
2142
2143Controls the processing of the bse_session_clean.pl script.
2144
2145=over
2146
2147=item *
2148
2149days - the minimum age in days of sessions to be removed. Default: 30.
2150
2151=item *
2152
2153per - the number of records to remove per SQL delete request.
2154Default: 1000.
2155
2156=item *
2157
2158count - the number of SQL delete requests to perform, maximum.
2159Default: 1000.
2160
2161=item *
2162
2163optimize - whether to perform a table optimization after deleting
2164records. Default: 1 (set to 0 to skip optimization)
2165
2166=back
2167
2168=head2 [nightly work]
2169
2170Controls the bse_nightly.pl script.
2171
2172=over
2173
2174=item *
2175
2176jobs - a comma separated list of BSE background processes to run when
2177bse_nightly.pl is run. Default: bse_session_clean
2178
b249abcb
TC
2179=item *
2180
2181I<other keys> - each key is a sort key, and the value is a single
2182background task name. This allows add-ons to setup extra tasks
2183without overwriting each other. The sugessted key format is:
2184
2185 99 - two digit priority - 00 is executed first, 99 last
2186 package-name - name of package the task is for
2187 unique - extra text to make the key unique, if necessary
2188
bede67d9
TC
2189=back
2190
4cf6a60c
TC
2191=head2 [cache]
2192
2193Parameters controlling where cached information - eg. file upload
2194progress is stored.
2195
2196=over
2197
2198=item *
2199
2200class - the BSE::Cache compatible cache class. See the documentation
2201of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
2202
2203=back
2204
a9634cc9
TC
2205=head2 [db]
2206
2207Database connection parameters. These override the settings in
2208Constants.pm which are deprecated.
2209
2210=over
2211
2212=item *
2213
2214dsn - the DBI dsn used to connect to the database. Default:
2215$Constants::DSN.
2216
2217=item *
2218
2219user - the logon to the database. Default: $Constants::UN
2220
2221=item *
2222
2223password - the password for the user. Default: $Constants::PW.
2224
2225=item *
2226
2227dbopts - a perl expression that should evaluate to a hash reference.
2228Default: $Constants::DBOPTs, or an empty hashref.
2229
2230=item *
2231
2232class - the database wrapper class to use. Default: BSE::DB::Mysql.
2233No other values are currently supported.
2234
2235=back
2236
fea96500
TC
2237=head2 [extra a_config]
2238
2239Defines extra configuration to be returned from the BSE system
2240configuration.
2241
2242Each key is the keyword in the returned JSON object. If the key
2243already exists it is not overwritten.
2244
2245Each value is the name of a section in the BSE configuration. The
2246strings "{level}", "{generator}", "{parentid}", "{template}" are
2247replaced with their values from the article that config is being
2248requested for.
2249
2250So:
2251
2252 [extra a_config]
2253 menu=level{level} menu
2254
2255 [level1 menu]
2256 alpha=One
2257 beta=Two
2258
2259will include:
2260
2261 menu: { alpha: "One", beta: "Two" }
2262
2263in the returned configuration
2264
dbe8a12a
TC
2265=head2 [cookie names]
2266
2267This section maps BSE's default cookie names to alternate names. This
2268can be useful if you have two BSE sites under the same domain and need
2269to ensure they use different cookies.
2270
2271eg.
2272
2273 [cookie names]
2274 userid=altuserid
2275
5abe2da5 2276=head2 [siteuser updates]
f0483c00
TC
2277
2278Each key identifies an update specification for userupdate.pl, the
2279value is a description of the specification.
2280
2281See L<<[siteuser update I<specid>]>> for the rest of the import
2282specification.
2283
5abe2da5 2284
f0483c00
TC
2285=head2 [siteuser update I<specid>]
2286
2287Currently contains only a single key:
2288
2289=over
2290
2291=item *
2292
2293fields - a semi-colon separated list of fields to import. Must
2294contain one of C<id> or C<userId> which is used as a key to identify
2295the user to update. An C<x> entry is a field to ignore. Some fields,
2296such as C<confirmed> may not appear in this list.
2297
2298=back
dbe8a12a 2299
40cc2f24
TC
2300=head2 [paypal]
2301
2302Configuration for BSE's PayPal integration.
2303
2304It shouldn't be necessary to change any of the URLs.
2305
2306=over
2307
2308=item *
2309
2310test - if true, then the PayPal sandbox is used, and the configuration
2311entries starting in C<test_> are used. If false, PayPal is live, and
2312configuration entries starting in C<live_> are used. Default: 1.
2313
2314=item *
2315
2316test_api_username, test_api_password, test_api_signature - API
2317credentials for test mode. Required in test mode.
2318
2319=item *
2320
2321live_api_username, live_api_password, live_api_signature - API
2322credentials for live mode. Required for live mode.
2323
2324=item *
2325
2326test_ws_url - URL to make NVP requests through in test mode. Default:
2327https://api-3t.sandbox.paypal.com/nvp
2328
2329=item *
2330
2331test_refresh_url - PayPal URL to refresh to in test mode. Default:
2332https://www.sandbox.paypal.com/webscr
2333
2334=item *
2335
2336live_ws_url - URL to make NVP requests through in live mode. Default:
2337https://api-3t.paypal.com/nvp
2338
2339=item *
2340
2341live_refresh_url - PayPal URL to refresh to in live mode. Default:
2342https://www.paypal.com/cgibin/webscr
2343
2344=back
2345
2346=head2 [paypal custom]
2347
2348Extra parameters supplied to the SetExpressCheckout API. See the
2349Express Checkout Advanced Features Guide (from PayPal) for details.
2350
2351Some settings that may be useful:
2352
2353=over
2354
2355=item *
2356
2357PAGESTYLE - the style of payment page to use from those listed in your
2358account profile.
2359
2360=item *
2361
2362HDRIMG - https URL to an image to use in the payment page header.
2363
2364=item *
2365
2366HDRBACKCOLOR - a 6 hex digit color to use as the background of the
2367payment page header.
2368
2369=item *
2370
2371HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
2372payment page header.
2373
2374=back
2375
86972656
TC
2376=head2 [audit log]
2377
2378=over
2379
2380=item *
2381
2382mail - if non-zero any emails sent through BSE::ComposeMail are logged
2383in the audit log. Default: 0.
2384
2385=item *
2386
2387mail_max_dump - if non-zero this is the size limit of the dump stored
2388in the audit log when [audit log].mail is enabled.
2389
2390=back
2391
ea69cb09
TC
2392=head2 [audit log I<facility>]
2393
2394Most commonly C<[audit log bse]>. Controls whether given events or
2395families of events are logged.
2396
2397The key is one of:
2398
2399=over
2400
2401=item I<component>
2402
2403=item I<component>C<:>I<module>
2404
2405=item I<component>C<:>I<module>C<:>I<function>
2406
2407=back
2408
2409with the longer keys overriding the shorter keys, and defaulting to
2410all actions being logged.
2411
b374e526
TC
2412=head2 [mail audit log]
2413
2414This enables sent when an event is logged in the audit log. Warning:
2415for common events this will result in large amounts of email.
2416
2417=over
2418
2419=item *
2420
2421to - the email address to send the email to
2422
2423=item *
2424
2425emerg, alert, crit, error, warning, notice, info, debug - if present
2426and true then events at these levels result in an email. If the value
2427contains an C<@> then the value is used as the recipient address.
2428
2429=item *
2430
2431I<facility>-I<component>
2432
2433=item *
2434
2435I<facility>-I<component>-I<module>
2436
2437=item *
2438
2439I<facility>-I<component>-I<module>-I<function>
2440
2441Controls sending an email for specific events or families of events.
2442If the value is true, send an email for that event. If the value
2443contains an C<@> then the value is used as the recipient address.
2444
8a3b8db8
TC
2445=back
2446
2447with the longer keys overriding the shorter keys, and defaulting to
2448all actions being logged.
2449
2450=head2 [html tidy]
2451
2452Contains options to pass to HTML::Tidy. Anything not listed below is
2453passed directly to HTML::Tidy->new.
2454
2455=over
2456
2457=item *
2458
2459ignore_types - types of message to ignore separated by commas, any,
2460all or none of info, warning, error.
2461
2462=item *
2463
2464ignore_text_I<key> - messages to ignore, I<key> is not used, just the
2465value.
2466
2467
b374e526
TC
2468=back
2469
a9cee650
TC
2470=head2 [email I<token>]
2471
07301b75 2472Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
a9cee650
TC
2473
2474=over
2475
2476=item *
2477
2478template - plain text template
2479
2480=item *
2481
2482html_template - HTML template (defaults to the value of I<template>
2483followed by C<_html>
2484
2485=item *
2486
2487subject - subject of the email, can be overridden with the
2488C<set_subject> tag.
2489
2490=item *
2491
2492from - from email address, defaults to the shop from address
2493
2494=item *
2495
2496from_name - from name
2497
2498=item *
2499
2500allow_html - controls whether HTML is allowed. By default this is
2501based on the user's settings.
2502
2503=back
2504
61551101
TC
2505=head1 AUTHOR
2506
2507Tony Cook <tony@develop-help.com>
2508
2509=cut