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