just a synopsis so far
[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
13a986ee
TC
780=item *
781
7823 - paypal - see L<paypal.pod>
783
08123550
TC
784=back
785
81f3292d
TC
786Other types can be added by adding entries to the [payment type names]
787and [payment type descs] sections.
788
08123550
TC
789=item address1
790
791=item address2
792
793=item address3
794
795These are used by various shop templates to present an address that a
796cheque payment should be sent to.
797
331fd099
TC
798=item from
799
800From email address for emails sent by the shop. Overides $SHOP_FROM
801in Constants.pm
802
803=item to_name
804
805To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
806in Constants.pm
807
808=item to_email
809
810To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
811in Constants.pm
812
d09682dd
TC
813=item noencrypt
814
815If this is true then orders sent to you by the shop will not be
816encrypted. Enabling this disabled acceptance of credit card orders,
817and the default for C<payment_types> will become C<1> instead or C<0>.
818
819Please realize that other potentially commercially sensitive
820information is being sent in the clear to a central location,
821unencrypted.
822
823=item email_order
824
825If true, then the order is email to to_email, possibly with credit
826card information included. Default: $SHOP_EMAIL_ORDER.
827
d49f56a6
TC
828=item display_I<field>
829
830Used to translate the stored order field name into a presentation name
831suitable for error messages.
832
41e7c841
TC
833=item cardprocessor
834
835The name of a class to load to process credit card transactions online.
836
837Currently this can be either DevHelp::Payments::Test or
838DevHelp::Payments::Inpho.
839
26c634af
TC
840=item crypt_module
841
842Name of the encryption module to use. Default: $SHOP_CRYPTO.
843
844=item crypt_signing_id
845
846Id of the key to sign the order email with. If this is non-empty then
847the email is signed even if [basic].sign is false. Default:
848$SHOP_SIGNING_ID.
849
850=item crypt_gpg
851
852Path to the GnuPG program. Default: $SHOP_GPG
853
745a6c13 854=item crypt_passphrase
26c634af
TC
855
856Passphrase of the key used to sign the email. Default:
857$SHOP_PASSPHRASE.
858
745a6c13
TC
859=item show_card_type
860
861If true, request the card type when requesting credit card
862information. Default: False.
863
56f87a80
TC
864=item cart_entry_limit
865
866Maximum number of entries in the cart. This limits the number of
867distinct products (with options) in the cart, not the total
868quantities. Default: Unlimited.
869
d99ed4c4 870=item currency_code
13a986ee
TC
871
872The shop currency as a 3-letter currency code. Default: AUD.
873Currencies other than "AUD" aren't supported by most of the system.
874
6e3d2da5
TC
875=back
876
bd3a048c
AMS
877=head2 [shipping]
878
879=over
880
881=item couriers
882
883A space-separated list of modules under Courier::, e.g. "Fastway::Road
884AustraliaPost::Air". These will be made available as shipping methods
885on the checkout page.
886
887=item sourcepostcode
888
889The post code from which products are shipped.
890
891=item fastwayfranchisee
892
893The name of the Fastway franchisee used to ship products from the
894sourcepostcode.
895
896=item fastwayfranchiseecode
897
898The Fastway franchisee code for the customer, if any.
899
900=back
901
41e7c841
TC
902=head2 [Shop Order Validation]
903
904This section can contain extra order validation information, including
905specifying required fields, display names and extra validation rules.
906
6e3d2da5
TC
907=head2 [fields]
908
909=over
910
911=item title_size
912
913The maximum length of the article title field. Default: 255. Should
914not be set higher than this unless you change the database schema.
915
916=back
917
ee6577c3
TC
918=head2 [interest]
919
920Controls the interest.pl script.
921
922=over
923
924=item notify
925
926Email address that is notified of the interest. Defaults to $SHOP_FROM.
927
ca9aa2bf 928=back
ee6577c3 929
6e3d2da5
TC
930=head2 [debug]
931
932Used for debugging.
933
934=over
935
936=item logon_cookies
937
938When a user logs on, and the site url is different to the secure url
939BSE attempts to refresh to the other "side" of the site to set the
940same cookie.
941
942BSE does some simple comparisons to attempt to determine whether the
943logon form was triggered on the secure side of the site (possibly from
944the shop) or on the insecure side. Since CGI doesn't necessarily give
945us all the information required, it's possible it will guess wrong.
946
d2730773
TC
947Setting this option to 1 will enable debugging information sent to
948standard error, which will be sent to the error log on Apache. This
949probably isn't useful on IIS.
950
951=item file_unlink
952
953Reports errors to STDERR (hence to the error log on Apache) if there
954is a problem deleting the actual file when an attached file is
955removed.
956
957=item mail_encryption
958
959Reports debugging information to standard error while encrypting your
960mail.
6e3d2da5 961
2d873eb6
TC
962=item cookies
963
964Reports cookies received from the browser and sent to the browser to
965STDERR (hence to the error log on Apache.)
966
4175638b
TC
967=item dump_session
968
969If nonzero the session hash is dumped to STDERR after it is retrived
970from the database.
971
af74f0b4
TC
972=item subscription_expiry
973
974If non-zero then subscription expiry date calculations are dumped to
975STDERR.
976
efcc5a30
TC
977=item jit_dynamic_regen
978
979If non-zero then information about jit_dynamic_regen is sent to
980STDERR.
981
db7d73a7
TC
982=item ifUserCan
983
984If non-zero then the ifUserCan tag will output some trace information
985to STDERR.
986
ca9aa2bf
TC
987=back
988
989=head2 [uri]
990
991Contains various URIs.
992
993This is underused, so don't rely on it yet.
994
995=over
996
997=item cgi
998
999The URI to the CGI directory. Default: /cgi-bin
1000
1001=item images
1002
1003The URI where images are kept. Default: /images
1004
1005=item shop
1006
1007=item articles
1008
9168c88c 1009=back
ca9aa2bf 1010
9168c88c 1011=head2 [articles]
ca9aa2bf 1012
9168c88c
TC
1013This will provide translations from symbolic names to article ids.
1014
1015Currently this is used for converting article ids in the access
1016control code, and for looking up the id of the shop.
6e3d2da5 1017
0b406a07
TC
1018=head2 [printable type]
1019
1020If the user supplies a template name to printable.pl then you can use
1021a different content type by adding an entry to this section. The key
1022is the template name, and the value is the full content type.
1023
918735d1
TC
1024=head2 [search index scores]
1025
1026This section is used when generating the search index to override the
1027default scores for each field in the articles.
1028
1029The default scores are:
1030
74b21f6d
TC
1031 Field Score Notes
1032 ----- ----- -----
1033 title 5
1034 body 3
1035 keyword 4
1036 pageTitle 5
1037 author 4
1038 summary 0
1039 description 0 Products only
1040 product_code 0 Products only
1041 file_displayName 2 displayName for files
1042 file_description 2 description for files
1043 file_notes 1 notes for files
918735d1
TC
1044
1045=head2 [article flags]
1046
1047=head2 [product flags]
1048
1049=head2 [catalog flags]
1050
1051Flags that can be set for articles, products and catalogs
1052respectively. Note that flags for articles are also visible in
1053products and catalogs.
1054
1055All flag Ids are single letters or digits. Uppercase letters are
1056reserved for use by BSE internally, leaving lower-case letters and
1057digits for your own use.
1058
1059Use the id of the flag as the key, and a description of the flag as
1060it's value.
1061
95989433
TC
1062=head2 [article uris]
1063
1064Each key is an article id, the values are base URIs to store the HTML
1065form of those articles and their children under.
1066
1067=head2 [protect link]
1068
1069The keys are ids of articles that shouldn't have their link field
1070overwritten. The value should be a true value, but is otherwise
1071ignored.
1072
d09682dd
TC
1073=head2 [datadump]
1074
1075=over
1076
1077=item to
1078
1079The recipient for the data dump email sent by datadump.pl. Default:
1080$DATA_EMAIL.
1081
1082=item from
1083
1084the From for the data dump email sent by datadump.pl. Default:
1085$SHOP_FROM.
1086
1087=back
1088
2a295ea9
TC
1089=head2 [site users]
1090
1091Configuration for site users.
1092
1093=over
1094
1095=item nopassword
1096
1097If this is set to true then no passwords are required during
1098registration, a confirmation email is sent immediately upon
1099registration and that confirmation email contains a link the user can
1100use to manage their details.
1101
1102This option has some security concerns since it can leave links to the
1103user's information in the browser history. This option is not
1104recommended.
1105
1106You cannot use this to control access to the shop.
1107
1108=item require_name1
1109
1110=item require_name2
1111
1112=item require_address
1113
1114=item require_city
1115
1116=item require_state
1117
1118=item require_postcode
1119
1120=item require_telephone
1121
1122=item require_facsimile
1123
1124=item require_country
1125
1126=item require_title
1127
1128=item require_organization
1129
1130Set these to true to require the corresponding field during
1131registration, and to keep it required after modification. Default:
1132false.
1133
1134If you enable any of these, you should enable C<info_on_register> as
1135well, or modify the registration template to include the given fields.
1136
1137=item display_I<field name>
1138
1139Controls how the given field is displayed in error messages. If you
1140change the field names on the registration and/or options forms you
1141should probably change them here too. Default: internal field name
1142with the first character converted to upper-case.
1143
1144=item info_on_register
1145
1146If this is set then the user info is prompted for during user
1147registration. The information still isn't required unless the
1148appropriate require_I<field> option is set. Default: false.
1149
1150=item register_refresh
1151
1152The default URL to refresh to on completing registration if no r
1153parameter is supplied.
1154
1155=item subscribe_all
1156
1157If this is set then the subcription checkboxes are all checked on
1158registration by default. Default: false.
1159
1160The user will only receive the subscriptions if they leave them checked
1161and follow the link in the confirmation email.
1162
1163=item subscribe_I<id>
1164
1165Where I<id> is the number identifying a subscription. If this is set
1166then the subscription checkbox for that subscription will be checked
1167by default on the registration form. Default: false.
1168
1169The user will only receive the subscriptions if they leave it checked
1170and follow the link in the confirmation email.
1171
1172You can get the I<id> of a subcription by looking at the Edit link on the
1173subscriptions management page, the number after "id=" is the id.
1174
9063386f
TC
1175=item billing_on_main_opts
1176
1177If set to zero then user billing options will be managed on a separate
1178page. This is controlled by the user/options_base.tmpl template.
1179
1180=item user_register
1181
1182If set to zero then users cannot register themselves. Default: true,
1183allowing users to register themselves.
1184
cf9f9cbc
TC
1185=item notify_register
1186
1187If true then an email is sent when a new user registers on your site.
1188The email address sent to is the first set of [site
1189users].notify_register_email, [shop].from or $SHOP_FROM from
1190Constants.pm
1191
1192No email is sent if a new user is created from the administration user
1193interface.
1194
1195See also: notify_register_email, notify_register_subject.
1196
1197=item notify_register_email
1198
1199The email to sent the registration notification too. See
1200notify_register above.
1201
1202=item notify_register_subject
1203
1204The subject of the notification email sent when a new user registers.
1205Any {I<field>} is replaced with the given field from the registered
1206user. See notify_register above.
1207
1208Default: New user {userId} registered
1209
6c83a514
TC
1210=item notify_register_customer
1211
1212If non-zero then email id C<notify_register_customer> will be sent to
1213new user on registration. By default this uses template
1214user/email_register, subject "Thank you for registering" which can be
1215overridden in [email notify_register_customer]
1216
2a295ea9
TC
1217=back
1218
81f3292d
TC
1219=head2 [payment type names]
1220
1221This section and [payment type descs] are used to configure new
1222paymeny type ids.
1223
1224The key is the integer representing the payment type. The value is
1225the name used in tags for checking the payment type.
1226
1227You can also add a description (currently unused) to [payment type
1228descs].
1229
1230You should use numbers starting from 10 to avoid conflicts with future
1231BSE payment types.
1232
1233=head2 [payment type descs]
1234
1235See [payment type names].
1236
1237=head2 [payment type required]
1238
1239Set the key given by the payment type id to a value of a
1240comma-separated list of fields required for that payment type.
1241
3ae524f3
TC
1242=head2 [help style I<style-name>]
1243
1244This type of configuration section is used to set values for a style
1245of help icon. Only the C<template> and C<prefix> values are used
1246directly by the code, the others are used by the default helpicon
1247templates.
1248
1249=over
1250
1251=item prefix
1252
1253The URI to the help files for this style. Default: /help/ in style
1254"user", /admin/help/ in style "admin".
1255
1256=item template
1257
1258The template used to produce the icon. Default: helpicon in style
1259user, admin/helpicon in style "admin".
1260
1261=item icon
1262
1263URI to the help icon image. Default: /images/admin/help.gif
1264
1265=item iconwidth
1266
1267The width of the help icon image. Default: 16
1268
1269=item iconheight
1270
1271The height of the help icon image. Default: 16
1272
1273=back
1274
1275If you just want to change the help icon image for user help icons you
1276might do:
1277
1278 [help style user]
1279 icon=/images/help.gif
1280
4175638b
TC
1281=head2 [affiliate]
1282
1283=over
1284
1285=item allowed_referer
1286
1287A semi-colon (;) separated list of referer domains that are allowed to
1288link to the C<a_set> target of L<affiliate.pl>.
1289
1290If the user's browser supplies a referer header then it will be
1291checked against this list.
1292
1293=item require_referer
1294
1295If this is set then the C<a_set> target of L<affiliate.pl> will
1296require that the user's browser supply a Referer header.
1297
1298=item default_refresh
1299
1300If no C<r> parameter is supplied to the C<a_set> target of
1301L<affiliate.pl> then this is used as the default refresh.
1302
1303Default: the site base url.
1304
829c9ed9
TC
1305=item subscription_required
1306
1307This is either the numeric or text of a subscription for which the
1308affiliate must have an active subscription.
1309
fdc2b7a2
TC
1310=item flag_required
1311
1312A single letter flag which the site administrator must set for the
1313affiliate page to be displayed for the given member.
1314
ea646070
TC
1315=item set_cookie
1316
1317If this is set then affiliate.pl will set the named cookie to the
1318affiliate id.
1319
1b5a718f
TC
1320=item other_cookies
1321
1322This is a comma-separated list of other cookies that should be set by
1323the a_set target. The values for the cookies should be passed to the
1324a_set target. For example with:
1325
1326 [affiliate]
1327 other_cookies=alpha,beta
1328
1329if the url:
1330
1331 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1332
1333is accessed, then the cookie alpha is set to "1", beta is set to "2".
1334The cookie gamma will not be set since it's not listed.
1335
ea646070
TC
1336=item linkbaseurl
1337
1338Used as the link base URL for the afflink.tmpl side bar template when
1339an affiliate id is set. Default: example.com
1340
1341=item linkbasedesc
1342
1343Used at the text of the link for the afflink.tmpl side bar template
1344when an affiliate id is set. Default: Your Site.
1345
1346=item linkdefurl
1347
1348Used as the link URL for the afflink.tmpl side bar template when an
1349affiliate id is not set. Default: example.com
1350
1351=item linkdefdesc
1352
1353Used as the text of the link for the afflink.tmpl side bar template
1354when an affiliate id is not set. Default: Our site
1355
4175638b
TC
1356=back
1357
3c32512d
TC
1358=head2 [BSE Siteuser Images]
1359
1360Each key is the id of a member image, with a corresponding [BSE
1361Siteuser Image I<image_id>] section. The values are ignored.
1362
1363=head2 [BSE Siteuser Image I<image_id>]
1364
1365Provides information about a single member image "template".
1366
1367=over
1368
1369=item description
1370
1371Short description on the image, like "Logo". Used in error messages.
1372
1373=item help
1374
1375Longer description of the image. Accessible with the member_image tag.
1376
1377=item minwidth
1378
1379=item minheight
1380
1381=item maxwidth
1382
1383=item maxheight
1384
1385The minimum and maximum dimensions of the image.
1386
1387=item widthsmallerror
1388
1389=item heightsmallerror
1390
1391=item widthlargeerror
1392
1393=item heightlargeerror
1394
1395Error messages displayed in the when the image is outside the
1396configured dimensions.
1397
1398=item largeerror
1399
1400=item smallerror
1401
1402Default error messages for the above.
1403
1404=item maxspace
1405
1406Maximum storage the image can use in bytes. Default: 1000000.
1407
1408=item spaceerror
1409
1410Error message displayed if the image uses too much storage.
1411
1412=back
1413
ab2cd916
TC
1414=head2 [editor]
1415
1416Various editor settings.
1417
1418=over
1419
1420=item allow_thumb
1421
1422If this is non-zero the system will attempt to load the configured
1423thumbnail class, and put thumbnail images on the image manager page
1424rather than full-size images. Default: off
1425
1426=item thumbs_class
1427
1428The name of a perl class that implement's BSE's thumbnail API. At
1429this point the only class that implements that is BSE::Thumb::Imager,
1430supplied with BSE. Default: None
1431
1432=item default_thumbnail
1433
1434URI to the default thumbnail image. This is presented when the
1435runtime production of a thumbnail image fails.
1436
1437=item default_thumbnail_width
1438
1439=item default_thumbnail_height
1440
1441Dimensions of the default thumbnail image.
1442
1443=item default_thumbnail_alt
1444
1445Alt text for the default thumbnail image.
1446
1761af79
TC
1447=item check_modified
1448
1449If this is true then BSE will check the value of the lastModified
1450parameter passed against the value in the article. If these don't
1451match the article isn't saved and is redisplayed with an error
1452message. This provides simple protection against one user saving
1453changes over those made by another.
1454
ab2cd916
TC
1455=back
1456
1457=head2 [thumbnails]
1458
1459=over
1460
1461=item max_width
1462
1463=item max_height
1464
1465=item max_pixels
1466
1467Default values for the thumbimage tag.
1468
1469=back
1470
829c9ed9
TC
1471=head2 [includes]
1472
1473Each value is used as the relative or absolute name of a file or
1474directory to load more configuration data from.
1475
1476The keywords must remain unique.
1477
1478Only the [includes] section from bse.cfg itself is used to locate more
1479configuration data.
1480
1481If the value references a directory, all files with an extension of
1482C<.cfg> are read for configuration data.
1483
1484The order the files are read (which later files overriding older
1485files) is:
1486
1487=over
1488
1489=item 1.
1490
1491bse.cfg is read
1492
1493=item 2.
1494
1495the entries in [includes] are sorted alphabetically (or rather
1496asciily), so an entry with key "A" is read before one with key "B",
1497one with key "01" is read before "02", but key "10" would be read
1498I<before> key "2".
1499
a9634cc9 1500=item 3.
829c9ed9
TC
1501
1502if an entry is a file then that is read and the values merged.
1503
a9634cc9 1504=item 4.
829c9ed9
TC
1505
1506if an entry is a directory, then that is scanned and the files found
1507read alphabetically as above.
1508
1509=back
1510
6a8a6ac5
TC
1511=head2 [error_img]
1512
1513This is used to configure the error icon displayed next to fields that
1514fail validation.
1515
1516=over
1517
1518=item image
1519
1520URI to the image file.
1521
1522=item width
1523
1524=item height
1525
1526The width and height of the error icon image.
1527
1528=back
1529
fdc2b7a2
TC
1530=head2 [site user flags]
1531
1532Flags that can be set for site users.
1533
1534All flag Ids are single letters or digits. Uppercase letters are
1535reserved for use by BSE internally, leaving lower-case letters and
1536digits for your own use.
1537
1538Use the id of the flag as the key, and a description of the flag as
1539it's value.
1540
deae2a52
TC
1541=head2 [article defaults]
1542
1543=head2 [catalog defaults]
1544
1545=head2 [product defaults]
1546
1547These sections contain defaults values for the corresponding article
1548types.
1549
1550Each key is the name of a column for the article type.
1551
1552If an entry is not found in [catalog defaults] then [article defaults]
1553is also checked.
1554
1555If an entry is not found in [product defaults] then [article defaults]
1556is also checked.
1557
1558These sections are checked B<after> the C<[children of >I<id>C<]> and
1559C<[level >I<level>C<]> sections.
1560
1561These defaults are used when creating an article where no value is
1562supplied, they can also be accessed via the <:default I<name>:> tag.
1563
1c3e5303
TC
1564=head2 [newsletter filters]
1565
1566Contains C<criteria>I<index> entries starting from C<criteria1>, then
1567C<criteria2>, etc.
1568
1569Each entry consists of a filter class name, followed by a ; followed
1570by data passed to that filter.
1571
1572 ; user the original SQL based filter, configured from
1573 ; section [foo]
1574 criteria1=BSE::NLFilter::SQL;foo
1575
1576See the documentation for each filter to configure the filters.
1577
c2096d67
TC
1578=head2 [Query Groups]
1579
1580The key of each entry is the numeric identifier of a query group, the
1581values are the name of the query group. For example:
1582
1583 [query groups]
1584 1=some name
1585
1586 [query group some name]
1587 sql=select id from site_users where id = ? and name1 like '%some%'
1588
1589Each entry also has a corresponding [Query Group I<name>] section.
1590
1591=head2 [query group I<name>]
1592
1593This section corresponds to an entry in [Query Groups].
1594
1595=over
1596
1597=item sql
1598
1599This is an SQL statement. One placeholder is required and is passed
1600the siteuser id (primary key) of the user to be checked. If this
1601query returns I<any> rows then the user is considered part of the
1602group.
1603
1604=back
1605
16901a2a
TC
1606=head2 [template types]
1607
1608Each key is a template name, the value is the content type to be used
1609when displaying the template dynamically.
1610
fea96500
TC
1611=head2 [template descriptions]
1612
1613Each key is a template name, the value is a description used in the
1614template dropdown for that template.
1615
8f84f3f1
TC
1616=head2 [body class]
1617
1618This section defines CSS class names for BSE's body text link tags.
1619The key is the tag name, the value is the CSS class to be used.
1620
1621By default the class used is the same as the name of the tag, but you
1622can switch this off by adding an entry setting the class to the empty
1623string, for example:
1624
1625 ; no class attribute for any of the links
1626 [body class]
1627 link=
1628 poplink=
1629 doclink=
1630 popdoclink=
1631
1632You can set p here too to set the class for paragraphs generated as
1633body text. By default no class is set.
1634
def1a923
TC
1635=head2 [popimage]
1636
1637Controls the behaviour of the window displayed by the popimage[] body
1638text tag. If the Javascript for this has been customized then this
1639may not apply.
1640
1641=over
1642
1643=item extrawidth
1644
1645=item extraheight
1646
1647Extra width and height for the window beyond the size of the image.
1648Default: no extra width or height.
1649
1650=item popmiddle
1651
1652If set to non-zero popimage[] will attempt to centre the popup within
1653the current window. Default: 0.
1654
1655=back
1656
1657=over
1658
1659=back
1660
41e7c841
TC
1661=head2 [inpho]
1662
1663This is used to configure the DevHelp::Payments::Inpho module.
1664
1665=over
1666
1667=item test
1668
1669If this is set then the test parameters are used instead of the
1670product values.
1671
1672=item url
1673
1674The URL to process requests through.
1675
1676Default: https://extranet.inpho.com.au/cc_ssl/process
1677
1678=item user
1679
1680Inpho supplied user name.
1681
1682=item password
1683
1684Inpho supplied password.
1685
1686=item test_url
1687
1688The URL to process test requests through.
1689
1690=item test_user
1691
1692The user to supply to test requests.
1693
1694=item test_password
1695
1696The password to supply to test requests.
1697
1698=back
1699
f2bf0d11
TC
1700=head2 [custom]
1701
1702This section controls whether some custom class methods are called:
1703
1704=over
1705
1706=item saveopts
1707
1708If this is non-zero then siteuser_saveopts is called.
1709
1710=back
1711
0a66f55c
AO
1712=head2 [levelI<level> menus]
1713
1714Where I<level> is the article level at which the defined menu options will be available.
1715Configure each menu value and description as I<key> and I<value>.
1716
1717=over
1718
1719For example:
1720
1721 [level1 menus]
1722 0=Default
1723 1=Sidebar
1724 2=Footer
1725
1726To create a menus using such values, use the "allkids_of" iterator "filter" option.
1727
1728For example:
1729
1730 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1731
1732=back
1733
37726cc9
AO
1734=head2 [title alias]
1735
1736Enable the "titleAlias" article field and set which level it will be available.
1737
1738=over
1739
1740=item levelI<level>
1741
1742Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1743set the value to non-zero.
1744
1745For example:
1746
1747 [title alias]
1748 level1=1
1749
1750The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1751for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1752in place of the article "title" when appropriate.
1753
1754=back
1755
195977cd
TC
1756=head2 [thumb geometries]
1757
1758Each key represents a geometry identifier for use by the thumbimage[],
1759gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
b864cc90 1760...:>, <:dthumbimage ...:> template tags.
195977cd
TC
1761
1762The key is the geometry identifier, the value is the geometry string
1763as follows.
1764
1765The geometry string consists of:
1766
1767=over
1768
1769=item *
1770
1771dimensions
1772
1773=item *
1774
1775crop flag - if present
1776
1777=item *
1778
1779optional fill
1780
1781=back
1782
1783The dimensions can be in any of the following forms:
1784
1785=over
1786
1787=item *
1788
1789<width>x<height> - the desired maximum width and height. eg 200x150
1790
1791=item *
1792
1793<width>x - the desired width, with the height calculated
1794proportionally based on the source image size
1795
1796=item *
1797
1798x<height> - the designed height, with the width calculated
1799proportionally based on the source image size.
1800
1801=item *
1802
1803<size> - the desired maximum size in both directions. so "200" is
1804equivalent to "200x200"
1805
1806=back
1807
1808The crop flag is a single letter "c", if present then the image should
1809be scaled so the smaller dimension matches the requested size, and the
1810longer dimension will be cropped to fit.
1811
1812The fill if present is: fill(color) where color is a color recognized
1813by the underlying graphics implementation. This should be at least
1814hex web colors without the #, eg fill(FF0000) will fill with red.
1815
b864cc90
TC
1816=head2 [thumb classes]
1817
1818Each key represents a geometry identifier for use by the thumbimage[],
1819gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1820...:>, <:dthumbimage ...:> template tags.
1821
1822The value is used as the class for the generated img tag.
1823
510a9ee7
TC
1824=head2 [targets]
1825
1826Each value represents a handler or script name for the <:dyntarget
1827I<script> I<target> ...:> tag.
1828
1829Each key has a TARGET version and a no-TARGET version, with the key
1830suffixed with C<_n>.
1831
1832The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1833default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1834
1835For other targets the default is
1836C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1837C</cgi-bin/>I<script>C<.pl>.
1838
1839The string C<TARGET> is replaced with the target specified in the
1840dyntarget tag.
1841
1842This, along with dyntarget is intended to allow a more "Web 2.0" type
1843of access to BSE. eg. you might set:
1844
1845 [targets]
1846 shop=/xshop/TARGET
1847 shop_x=/xshop/
1848
1849and have a rewrite rule:
1850
1851 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
1852
8a153d74
TC
1853=head2 [popimage class I<classname>]
1854
1855This defines the settings for a class of images generated by the
1856popimage[] and gpopimage[] body text markup tags. For example, the
1857settings for C<popimage[imageid|foo]> can be found in section
1858C<[popimage class foo]>.
1859
1860=over
1861
1862=item html
1863
1864The html generated for this class. Tags of the form
1865C<{>I<identifier>C<}> are replaced, where I<identifier> can be
1866C<inline_> or C<outline_> followed by an image field name, for example
1867C<inline_src> is the URL to the inline image.
1868
1869Default: <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>
1870
1871The default may be tuned as needed.
1872
1873=item inline
1874
1875The inline image geometry. Default: editor (the value used for
1876thumbnails on the admin side)
1877
1878=item outline
1879
1880The outline image geometry. If no value is supplied then the original
1881image values are used.
1882
1883=back
1884
0c2e7f7a
TC
1885=head2 [mail resources]
1886
1887Each key is the identifier of a file that can be attached to
1888BSE::ComposeMail emails. The value is comma separated filename,
1889content type, inline status.
1890
1891The files are searched for through the template search mechanism, so
1892the filename can be relative to either the master or local templates
1893directories.
1894
1895If the content type is not supplied, if the filename end in gif, png
1896or jpg the appropriate content type is used, otherwise
1897application/octet-stream.
1898
1899If the inline status is not supplied then images are considered
1900inline, and other files arent.
1901
a53374d2
TC
1902=head2 [shop registration]
1903
1904Each key represents a message id from attempts to checkout. Except
1905the all key which covers all cases.
1906
1907If the C<all> key or the message id key is non-zero then the checkout
1908page will redirect to registration instead of login if the cart or
1909configuration requires that the user be logged in.
1910
3f36e485
TC
1911=head2 [template I<template-name>]
1912
1913Settings for articles based on a particular template.
1914
1915=over
1916
1917=item no_cache_dynamic
1918
1919Controls whether a cache-control: no-cache header will be produced.
1920Can be overridden with the A and B article flags. If not set the
1921value of [article].no_cache_dynamic is used.
1922
1923=back
1924
1925=head2 [article]
1926
1927Global settings for articles.
1928
1929=over
1930
1931=item no_cache_dynamic
1932
1933Controls whether a cache-control: no-cache header will be produced.
1934Can be overridden with the A and B article flags or [template
1935I<template-name>].no_cache_dynamic. If not set the value of
1936[basic].no_cache_dynamic is used.
1937
1938=back
1939
c6fc339f
TC
1940=head2 [recaptcha]
1941
1942For the <:recaptcha:> tag currently only used for fmail.pl.
1943
1944=over
1945
1946=item api_public_key
1947
1948=item api_private_key
1949
1950The public and private key you receive when you register with reCAPTCHA.
1951
1952=item error_I<error_code>
1953
1954Replace the error message for the given I<error_code> where
1955I<error_code> is the reCAPTCHA error code
1956(eg. "incorrect-captcha-sol") with dash replaced by underscore.
1957
1958eg.
1959
1960 error_incorrect_captch_sol=VERY BAD INPUT
1961
1962=back
1963
36e373a9
TC
1964=head2 [global file metadata]
1965
1966Each key represents an item of metadata for files attached to
1967articles.
1968
1969The values are ignored.
1970
1971For each key, extra information is defined in the [file metadata
1972I<name>] section.
1973
1974=head2 [file metadata I<name>]
1975
1976Definition for the file metadata item I<name>.
1977
1978=over
1979
1980=item *
1981
1982title - descriptive name of the metadata. Defaults to I<name>.
1983
1984=item *
1985
1986rules - validation rules, separated by ;. Custom rules can be defined
1987in [file metadata validation].
1988
1989=item *
1990
1991ro - if non-zero the metadata cannot be modified directly by the admin
1992(applications can still generate it). Default: writable.
1993
1994=item *
1995
1996type - the data type of the metadata, any of string, text, enum,
1997integer, real, image. If this is enum values must be defined and
1998labels should be. Default: string.
1999
2000The types are:
2001
2002=over
2003
2004=item *
2005
2006string - single line of text
2007
2008=item *
2009
2010text - one or more lines of text
2011
2012=item *
2013
2014integer - whole number
2015
2016=item *
2017
2018real - number with decimal points
2019
2020=item *
2021
2022enum - select from a list of possible values.
2023
2024=item *
2025
2026image - image file.
2027
2028=back
2029
2030=item *
2031
2032values - semi-colon separated list of values for this metadata.
2033
2034=item *
2035
2036labels - semi-colon separated list of labels for the values
2037
2038=item *
2039
2040help - help html to display for the metadata
2041
2042=item *
2043
2044data_name - (images only) the key to use to store the image data.
2045Default: I<name>_data.
2046
2047=item *
2048
2049width_name - (images only) the key to use to store the image width.
2050Default: I<name>_width.
2051
2052=item *
2053
2054height_name - (images only) the key to use to store the image height.
2055Default: I<name>_height.
2056
2057=item *
2058
2059cond - a perl expression indicating whether the metadata should be
2060prompted for, for this file. $file is the file object. Default: 1.
2061
2062=item *
2063
2064unit - text displayed after the entry box for the metadata. Default:
2065empty. Useful for including a unit ("pixels") or format help
2066("hh:mm").
2067
2068=back
2069
bede67d9
TC
2070=head2 [session cleanup]
2071
2072Controls the processing of the bse_session_clean.pl script.
2073
2074=over
2075
2076=item *
2077
2078days - the minimum age in days of sessions to be removed. Default: 30.
2079
2080=item *
2081
2082per - the number of records to remove per SQL delete request.
2083Default: 1000.
2084
2085=item *
2086
2087count - the number of SQL delete requests to perform, maximum.
2088Default: 1000.
2089
2090=item *
2091
2092optimize - whether to perform a table optimization after deleting
2093records. Default: 1 (set to 0 to skip optimization)
2094
2095=back
2096
2097=head2 [nightly work]
2098
2099Controls the bse_nightly.pl script.
2100
2101=over
2102
2103=item *
2104
2105jobs - a comma separated list of BSE background processes to run when
2106bse_nightly.pl is run. Default: bse_session_clean
2107
b249abcb
TC
2108=item *
2109
2110I<other keys> - each key is a sort key, and the value is a single
2111background task name. This allows add-ons to setup extra tasks
2112without overwriting each other. The sugessted key format is:
2113
2114 99 - two digit priority - 00 is executed first, 99 last
2115 package-name - name of package the task is for
2116 unique - extra text to make the key unique, if necessary
2117
bede67d9
TC
2118=back
2119
4cf6a60c
TC
2120=head2 [cache]
2121
2122Parameters controlling where cached information - eg. file upload
2123progress is stored.
2124
2125=over
2126
2127=item *
2128
2129class - the BSE::Cache compatible cache class. See the documentation
2130of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
2131
2132=back
2133
a9634cc9
TC
2134=head2 [db]
2135
2136Database connection parameters. These override the settings in
2137Constants.pm which are deprecated.
2138
2139=over
2140
2141=item *
2142
2143dsn - the DBI dsn used to connect to the database. Default:
2144$Constants::DSN.
2145
2146=item *
2147
2148user - the logon to the database. Default: $Constants::UN
2149
2150=item *
2151
2152password - the password for the user. Default: $Constants::PW.
2153
2154=item *
2155
2156dbopts - a perl expression that should evaluate to a hash reference.
2157Default: $Constants::DBOPTs, or an empty hashref.
2158
2159=item *
2160
2161class - the database wrapper class to use. Default: BSE::DB::Mysql.
2162No other values are currently supported.
2163
2164=back
2165
fea96500
TC
2166=head2 [extra a_config]
2167
2168Defines extra configuration to be returned from the BSE system
2169configuration.
2170
2171Each key is the keyword in the returned JSON object. If the key
2172already exists it is not overwritten.
2173
2174Each value is the name of a section in the BSE configuration. The
2175strings "{level}", "{generator}", "{parentid}", "{template}" are
2176replaced with their values from the article that config is being
2177requested for.
2178
2179So:
2180
2181 [extra a_config]
2182 menu=level{level} menu
2183
2184 [level1 menu]
2185 alpha=One
2186 beta=Two
2187
2188will include:
2189
2190 menu: { alpha: "One", beta: "Two" }
2191
2192in the returned configuration
2193
dbe8a12a
TC
2194=head2 [cookie names]
2195
2196This section maps BSE's default cookie names to alternate names. This
2197can be useful if you have two BSE sites under the same domain and need
2198to ensure they use different cookies.
2199
2200eg.
2201
2202 [cookie names]
2203 userid=altuserid
2204
f0483c00
TC
2205=item [siteuser updates]
2206
2207Each key identifies an update specification for userupdate.pl, the
2208value is a description of the specification.
2209
2210See L<<[siteuser update I<specid>]>> for the rest of the import
2211specification.
2212
2213=head2 [siteuser update I<specid>]
2214
2215Currently contains only a single key:
2216
2217=over
2218
2219=item *
2220
2221fields - a semi-colon separated list of fields to import. Must
2222contain one of C<id> or C<userId> which is used as a key to identify
2223the user to update. An C<x> entry is a field to ignore. Some fields,
2224such as C<confirmed> may not appear in this list.
2225
2226=back
dbe8a12a 2227
61551101
TC
2228=head1 AUTHOR
2229
2230Tony Cook <tony@develop-help.com>
2231
2232=cut