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