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