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