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