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