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