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