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