3 config.pod - documents BSE configuration file options
7 BSE historically used Constants.pm to keep most configuration
8 information. The plan is to make sure any new configuration is kept
9 in bse.cfg, and to slowly move most configuration information into
12 Keeping configuration information in Constants.pm makes it difficult
13 to perform upgrades and makes it impossible to use tools such as
14 mod_perl, at least if you want more than one site on the machine.
16 F<bse.cfg> is read as a utf-8 encoded file.
18 =head1 CONFIGURATION ENTRIES
22 Contains URL configuration for the site.
28 The normal URL for the non-secure parts of the site.
32 The secure URL for the shop, products and other portions of the site
33 that should use SSL. This isn't checked to make sure it is https.
37 Used as the site "name" in a few places.
41 If set, this is used as the base URL for accessing the administrative
42 functions of your site.
46 Ignored if C<adminurl> is set.
48 If this is true then C<secureurl> is used as the base URL for
49 accessing the administrative functions of your site, otherwise C<url>
50 is used as the base URL. Default: false (C<url>'s value is used)
54 Configure the IP address of one or more front-end proxies. This can
55 be a regular expression except that C<.> is translated to C<\.> and
56 C<*> is tranlated to C<.*> to give more glob() like matching.
58 If the reqesting host matches then admin site URL matching is done
59 against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
61 Default: no front-end server configured.
65 A secret used (currently) for hashing cookie values passed between the
66 secure and non-secure parts of the site. This must be set. A
67 suitable value can be created with:
69 openssl rand -base64 32
75 Contains various file system paths.
81 This is where the files uploads with the file wizard are stored. It
82 must be writable by the web server user.
86 Directory containing administrative templates. Note: this is not
87 completely implemented for now, so assume the default. Default: admin
88 directory under $TMPLDIR.
92 Directory base for most templates. This can contain references like
93 $(section/key) to other configuration entries. Split on the systems
94 PATH separators (run: perl -V:path_sep)
98 Local Directory base for templates. This is searched before the
99 templates directory. This can contain references like $(section/key)
100 to other configuration entries. Split on the system's PATH separator.
104 Web server document root. Static pages are generated under this
105 directory. Default: $CONTENTBASE.
109 Where uploaded images are stored. This is not yet completely
110 implemented. Default: $IMAGEDIR.
114 Local search path for BSE::Custom, or the class configured by
115 C<custom_class> in [basic].
119 The directory where cached versions of scaled thumbnails are stored.
120 Defaults to I<[paths].images>F</scaled>. This must be in the document tree. If
121 you set this you should also set I<[uri].scalecache>.
123 =item siteuser_images
125 Where uploaded siteuser images are stored. This must be set in the
126 config file. The default bse.cfg include an entry to use the current
127 values of [paths].downloads
131 Pregenerated dynamic article pages are stored here. This must be
132 defined if you site contains any dynamicly generated pages.
136 The directory to store public BSE::TB::File content in (currently used
137 for application specific files.)
143 This section is used by the file wizard to map uploaded file
144 extensions to MIME content types. This can be used to extend
145 BSE::FileEditor's internal extension map. It cannot override that
148 The key for each entry is the extension, without the leading '.'.
152 xls = application/msexcel
156 Used for translating symbolic template names into full names under the
159 In each case the default is the name with a C<.tmpl> extension.
169 user registration page
173 =head2 [admin templates]
175 Used for translating the names of administration templates into filenames.
177 In each case the default is the name with a C<.tmpl> extension.
187 Catalog editor page. Default admin/edit_catalog.tmpl
199 Article edit pages. Default admin/edit_<number>.tmpl
203 Step child/parent management page. Default admin/edit_steps.tmpl
215 The value of the charset keyword when outputting HTML from a script.
216 Set to the empty string to suppress the charset keyword. Default:
221 If this is a non-zero number, then all but mailto links are redirected
222 to C<nuser.pl/redirect> so you can display a diclaimer. If this
223 contained alphabetics it's treated as a comma separated list of url
224 schemes that should be handled via C<nuser.pl/redirect>. If 0 or not
225 present, no redirection is done.
227 The redirect URL includes a hash of the url, title and the redirect
228 salt to prevent using this mechanism by external sites for cookie
233 The salt used in generating the has for redirect_links. Default: an
238 If non-zero then any HTML output is validated with HTML::Tidy.
239 Validation errors and warnings are sent to the audit log. See [html
244 The default tag formatting to use for C<< <:= ... :> >> tags.
247 =item formatter_image_class
249 The default class to use for image[...] tags in body text. Default:
260 If this is true then the user/group/permissions database is used to
261 control access to the system. Default: False.
263 =item access_filter_parents
265 If this is true, then the drop-down lists of possible parents on the
266 newsletter edit pages are filtered for access control.
269 =item access_filter_steps
271 If this is true, then the drop-down lists of possible stepparents and
272 stepchildren on the article edit pages are filtered for access control.
277 The prefix applied to articles that use a linkAlias url. This should
280 =item alias_recursive
282 If this is non-zero then the link is formed by the C<alias_prefix>,
283 followed by slash (C</>) separated aliases from the ancestors starting
284 from the section, followed by the C<alias_suffix>. You may need to
285 change your redirect handling if you enable this. Default: Off.
289 If this is non-zero then the title is cleaned up (all but
290 alphanumerics removed) and appended to the alias URL generated.
294 If true then all articles are treated as dynamic. Default: false.
298 By default, if the author doesn't use any image tags, BSE will insert
299 any unnamed article images into the body text of an article. You can
300 disable this on a per-article basis in the image tool, or disable it
301 globally by setting C<auto_images> to 0.
303 An alternative is to set C<imagePos> in C<[article defaults]> to
304 C<xx> which will default articles to not auto-inserting images.
306 =item cache_templates
308 If true, BSE will cache compiled templates using the configured BSE
309 cache, if any. Depending on the configured cache this may slow things
310 down. Default: disabled.
312 =item cache_templates_locally
314 If true, BSE will cache compiled templates in memory. This may
315 significantly improve performance but may increase memory use.
318 =item cache_thumbnails
320 If set to zero the results of the thumbimage/gthumbimage body/template
321 tags will not be cached. Default: 1 (caching is enabled).
325 This overrides the domain value set for cookies. This is useful if
326 you allow the site to run under both example.com and www.example.com,
327 if you set cookie_domain to example.com then a user visiting
328 www.example.com will still have their cookies when they visit
331 =item cookie_lifetime
333 The expiry time for cookies. This should be in the form supported by
334 CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
335 number, and a time character (s - seconds, m - minutes, h - hours, d -
336 days, M - months). Set to an empty string for session cookies.
341 This overrides the cookie name used to store the session id. Default:
342 sessionid. This is useful when you have 2 sites under the same
343 top-level domain, and helps disambiguate the cookie returned by the
348 The name of the custom class for your site. This is currently only
349 used for article editing customizations. This class should derive
350 from BSE::CustomBase. Default: BSE::Custom.
352 =item default_popupimage
354 This is the default popup image class for the popimage[] and
355 gpopimage[] tags. Default: popup.
357 =item dynamic_access_filter
359 If set to 0, dynamic article iterators will no access control filter
360 their results. Default: 1.
362 =item error_not_defined
364 If non-zero, during dynamic page generation, inserts a message
365 explaining which variable is not set, instead of just leaving the tag
366 unreplaced. Default: 1.
368 =item http_only_session
370 If this is non-zero, the default, the session cookie sent to the
371 browser has the C<HttpOnly> attribute set. This can prevent session
372 cookie hijacking. Default: 1.
376 This should be the path to a file to be updated with the list of users
377 and crypt() versions of their passwords. If this is set then the
378 security system will check for a user set by the browser before
379 attempting a form based logon. Default: None.
383 The name of the file to generate for static articles when the link is
384 terminated by "/". Default: C<index.html>.
386 =item jit_dynamic_pregen
388 If this is true, then pre-generation for dynamic pages will be delayed
389 until the page is displayed to a user. Default: off.
393 If this is true then the links to your articles within BSE will be
394 followed by a / and then by a simplified version of the article title.
395 The aim is to include at least some title information in the URL
396 without modifying the name of the HTML file. Default: False.
398 =item make_userid_cookie
400 If this is non-zero, the default, then when the site member logs in, a
401 javascript visible cookie, C<userid> will be set that contains the
402 login name of the user. BSE's back-end doesn't use this cookie, its
403 only use is for Javascript to enable/disable user interface elements.
408 Previously the minimum length of site user passwords in characters.
409 You must now set C<length> in C<[siteuser passwords]>.
411 =item no_cache_dynamic
413 If non-zero, the default, dynamic responses will include a
414 C<Cache-Control: no-cache> header. This can be overridden for
415 articles via , article flags, C<[template >
416 I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
419 =item preload_template
421 Preload the named template, searching the template search part. Any
422 text that would normally be produced by the preloaded template is
423 ignored. This can be useful for common definitions and variables for
424 use in many templates. Default: none.
428 Device to read random data from. This device should not block when it
433 If true then page.pl will 301 redirect (Moved Permanently) requests
434 for an article by its id to the generated link if the article has a
435 link alias. Default: false. Must only be used with use_alias true.
439 If this is non-zero then the session cookie sent to the browser has
440 the C<Secure> attribute set. This means that the cookie will only be
441 visible over https. This is only useful when the only URL the site is
442 visited over is a https URL. Default: 0.
446 Set this to non-zero to enable authentication via server
447 authentication (usually Basic Authentication.) You should normally
448 set this if you set htusers below. Default: 0 (disabled)
452 If this is true then the encrypted messages containing the customer's
453 credit card number are sent to the shop owner signed. To avoid
454 keeping a passphrase and signing key on the server you can set this to
455 false (0). This has the effect that anyone could send you an unsigned
456 message encrypted with your public key, though this may not be a
457 security threat. Default: True.
461 If true, the ifAjax and ajax tags will be active for static pages.
463 =item static_thumbnails
465 If true and cache_thumbnails is true then thumbnails for the thumbnail
466 cache will be generated when a static page is regenerated, and the
467 link from the page will link to the image in the cache rather than to
468 C<thumb.pl>. Default: 1 (static thumbnails enabled).
472 If this is non-zero, and a cache is configured (see [cache]), file
473 uploads are tracked in entries in the cache.
475 The fileprogress.pl script can be called by Ajax to display file
476 upload progress information to the user. The upload state is updated
477 a maximum of once a second.
481 If this is non-zero then an article with linkAlias set will use an
482 alias url instead of the "real" url. You will need to configure a
483 RewriteRule or ErrorDocument to page.pl to direct the user to the
484 correct URL. Default: 1.
488 Some obsolete tags will warn to stderr if this is non-zero. Default:
495 This section controls how BSE sends email.
501 The host or IP address of your mail server. If this is not set
502 C<sendmail> will be used instead. If this is set you must also set
507 The name that BSE uses to identify itself when sending mail via SMTP.
508 Required if I<smtp_server> is set.
512 The path to the C<sendmail> binary. Default: /usr/lib/sendmail
516 The options supplied to sendmail. Default: -t -oi
518 You may want to add the -odq option to this if you want mail queued
519 rather than sent immediately.
521 =item set_errors_to_from
523 If true, we add an Errors-To header set to the same as the From
524 header. Default: true.
526 =item html_system_email
528 If non-zero then emails sent via the compose mail system that aren't
529 being sent to a member record, will be sent as HTML, if the HTML
530 template is available.
534 If this is C<style> (the default) then use CSS::Inliner to attempt to
535 inline CSS in mail if the text "<style" is found in the generated
538 If this is C<force> then we always attempt to inline CSS.
540 If this is any other value then don't inline CSS.
542 =item inline_css_flags
544 A comma separated list of flags to supply to CSS::Inliner->new().
545 Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
546 attributes, and C<leave_style> to leave the HTML style block in place.
550 =item inline_css_report
552 If this is true and CSS inlining fails, log an error to the audit
553 log. This is intended for use in debugging and should be disabled in
554 production. Default: false (disabled)
558 =head2 [children of I<id>]
560 Where I<id> is the identifier for an article.
566 the name of the default template for children of the given parent
570 a comma-separated list of extra directories under $TMPLDIR to search
571 for templates that can be used for children of the given parent article.
575 =head2 [article I<id>]
577 Where I<id> is the identifier of an article.
583 A comma-separated list of extra directories under $TMPLDIR to search
584 for templates that can be used for children of the given parent
587 =item extra_templates
589 A comma-separated list of extra templates under $TMPLDIR that can be
590 used for the given article.
594 =head2 [level I<level>]
600 The default template for this level of article, assuming it hasn't
601 been set in the [children of I<article id>] section.
605 A comma-separated list of extra directories under $TMPLDIR to search
606 for templates that can be used for articles at the given I<level>.
616 The default template for catalogs.
626 The default template for products.
628 =item extra_templates
630 A comma separated list of extra templates that can be used for
637 This can be used to control translation of error messages. Each key
638 has a prefix identifying the module that uses the error, followed by
639 '/' followed by a specific identifier for the message.
641 Message parameters, expressed as $I<digit>, are replaced with the
642 parameters passed to the message. C<$$> is replaced with C<$>.
644 Each message identifier below is documented with the id, when it
645 occurs, the default message, and any parameters.
651 the user attempted to logon without entering a logon name. Default:
652 "Please enter a logon name". No parameters.
656 the user attempted to logon without entering a password. Default:
657 "Please enter your password." No parameters.
659 =item user/baduserpass
661 the user's logon name or password was not found or did not match.
662 Default: "Invalid user or password". No parameters.
664 =item user/notloggedon
666 the user attempted to logoff while not logged on. Default: "You
667 aren't logged on". No parameters.
669 =item user/optsoldpass
671 the user entered a new password on the options page without entering
672 their old password. Default: "You need to enter your old password to
673 change your password". No parameters.
675 =item shop/logonrequired
677 Displayed if the user attempts to checkout when [shop].require_logon
688 if non-zero, the order must be marked as paid for before the file can
693 if non-zero the order must be marked as filled before the files can be
698 if non-zero the user must be registered/logged on to download I<any>
703 if non-zero, downloads of userfiles will be logged. Default: 0
705 =item log_downufile_maxage
707 the maximum age of entries in the user file download log, in days.
712 =head2 [confirmations]
714 Control over confirmation emails.
720 The subject of email confirmation emails. Default: Subcription
725 The from field for the email. Default: $SHOP_FROM
729 =head2 [subscriptions]
731 Control over subscription messages.
737 The from field for the email. Default: $SHOP_FROM.
741 Default for the "Test Name" field for sending test subscription
746 Default for the "Test Email" field for sending test subscription
751 Set to 1 if you want the "Test Text Only" box checked by default for
752 sending test subscription messages.
756 Set to 0 to disable display of the test subscription messages portions
757 of the subscriptions send form.
759 =item text_link_inline
761 Set to format links as they appear in the text version of emails.
762 C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
763 the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
767 Set to format links as they appear at the footer of the body text. If
768 this is set to the empty string then no list appears. C<$1>, C<$2>,
769 C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
770 replaced with newline. Default: C<[$3] $2>
772 =item text_link_list_prefix
774 A line of text produced above the list of URLs if there is one.
775 Default: C<----->. $n in this is replaced with newlines.
779 For example, if the configuration is:
781 text_link_inline="$1" ($3)
782 text_link_list_prefix=$n$n-------
783 text_link_list=($3) "$1"$n => $2
785 and the body text is:
788 link[http://www.example.com/|Example]
798 => http://www.yoursite.com/shop/index.html
800 => http://www.example.com/
806 =item highlight_partial
808 If this is true then partial matches will be highlight in search
809 result excerpts. Default: True
811 =item keep_inaccessible
813 If this is true then resulting articles that can't be accessed by the
814 user are listed in the search results. Default: false.
818 The default regular expression used to match words in text during
819 indexing. Default: \w+
821 =item wordre_I<fieldname>
823 The field specific word match regular expression for the built-in
824 search indexer. Default: the value of C<wordre>.
828 Module used to build the search index. Default: BSE::Index::BSE.
832 For C<BSE::Index::BSE>, the optimization priority. The default of
833 C<speed> builds the index in memory and is very fast, but can consume
834 a lot of memory. Otherwise, set this to C<memory> to reduce memory
837 C<memory> priority index building requires that the C<DBM::Deep>
842 Articles with a higher level than this are indexed as their ancestor.
843 Default: C<$SEARCH_LEVEL> which defaults to 5.
847 Level of case-sensitivity in the search engine. This can be one of:
853 C<none> - no case-sensitive searches
857 C<context> - case-sensitive if there are any upper-case characters in
858 the search string, case-insensitive otherwise.
862 C<controlled> - case-sensitive via a query parameter. This is
863 currently not supported by the built-in search engie.
867 Renegerate your search indexes after changing this value. Default:
872 =head2 [search highlight]
874 Sets the prefix and suffix used for highlighting matches for different
877 These are used by the highlight_result, excerpt, pageTitle, author,
878 keywords and matchFile tags.
880 Each field has a prefix and suffix entry. The key is
881 I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
882 file_I<fieldname>_prefix and file_I<fieldname>_suffix.
884 The default prefix is <b>. The default suffix is </b>.
886 For example you can do:
889 body_prefix=<span class="searchfound">
892 The default prefix and suffix can also be redefined:
904 Used by some templates to check if the shop is enabled. Set this to 1
905 to enable the shop, or 0 to disable it.
907 =item secureurl_articles
909 If this is false then shop articles will not use the secureurl as their
910 baseurl. Default: True
912 =item register_if_files
914 If true the customer is required to register before checkout if there
915 are any for sale files attached to products in the cart. Default: True
919 If true the customer is required to be logged on before checkout,
920 whether or not for sale files are attached to products in the cart.
925 A comma-separated list of acceptable payment types. Default: 0
927 The possible payment types are:
933 0 - the user enters a credit card number, name and expiry date
937 1 - the customer will send a cheque
941 2 - contact customer for details
945 4 - paypal - see L<paypal.pod>
949 Other types can be added by adding entries to the [payment type names]
950 and [payment type descs] sections.
958 These are used by various shop templates to present an address that a
959 cheque payment should be sent to.
963 From email address for emails sent by the shop. Overides $SHOP_FROM
968 To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
973 To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
978 BCC email address for order confirmation emails sent to the customer.
983 If this is true then orders sent to you by the shop will not be
984 encrypted. Enabling this disabled acceptance of credit card orders,
985 and the default for C<payment_types> will become C<1> instead or C<0>.
987 Please realize that other potentially commercially sensitive
988 information is being sent in the clear to a central location,
993 If true, then the order is email to to_email, possibly with credit
994 card information included. Default: $SHOP_EMAIL_ORDER.
996 =item display_I<field>
998 Used to translate the stored order field name into a presentation name
999 suitable for error messages.
1003 The name of a class to load to process credit card transactions online.
1005 Currently this can be either DevHelp::Payments::Test or
1006 DevHelp::Payments::Inpho.
1010 Name of the encryption module to use. Default: $SHOP_CRYPTO.
1012 =item crypt_signing_id
1014 Id of the key to sign the order email with. If this is non-empty then
1015 the email is signed even if [basic].sign is false. Default:
1020 Path to the GnuPG program. Default: $SHOP_GPG
1022 =item crypt_passphrase
1024 Passphrase of the key used to sign the email. Default:
1027 =item show_card_type
1029 If true, request the card type when requesting credit card
1030 information. Default: False.
1032 =item cart_entry_limit
1034 Maximum number of entries in the cart. This limits the number of
1035 distinct products (with options) in the cart, not the total
1036 quantities. Default: Unlimited.
1040 The shop currency as a 3-letter currency code. Default: AUD.
1041 Currencies other than "AUD" aren't supported by most of the system.
1045 Set to non-zero if you're using country codes in the order country
1046 field. If this is set then the delivCountry is supplied as is to
1047 various parts of the system, otherwise it is translated from a country
1048 name to a country code. Default: 0.
1050 =item require_fields
1052 A comma separated list of extra fields to require during checkout.
1053 This is in addition to the usual fields required during checkout.
1056 =item require_delivery
1058 If true, and the C<need_delivery> CGI parameter is true, treat the
1059 following delivery fields as required during checkout: delivFirstName,
1060 delivLastName, delivStreet, delivSuburb, delivPostCode and delivCountry.
1063 =item require_delivery_fields
1065 If C<require_delivery> is true, and the C<need_delivery> CGI parameter
1066 is true, add the comma separated fields listed here to the required
1067 checkout fields list. Default: none.
1069 =item allow_missing_options
1071 If true, products with missing options can be added to the cart and
1072 purchased. Default: false.
1082 A space-separated list of modules under Courier::, e.g. "Fastway::Road
1083 AustraliaPost::Air". These will be made available as shipping methods
1084 on the checkout page.
1088 If true then a default "Quote shipping charges later" shipping method
1089 will be added to the shipping methods list.
1091 =item sourcepostcode
1093 The post code from which products are shipped.
1095 =item fastwayfranchisee
1097 The name of the Fastway franchisee used to ship products from the
1100 =item fastwayfranchiseecode
1102 The Fastway franchisee code for the customer, if any.
1106 =head2 [Shop Order Validation]
1108 This section can contain extra order validation information, including
1109 specifying required fields, display names and extra validation rules.
1117 The maximum length of the article title field. Default: 255. Should
1118 not be set higher than this unless you change the database schema.
1124 Controls the interest.pl script.
1130 Email address that is notified of the interest. Defaults to $SHOP_FROM.
1142 When a user logs on, and the site url is different to the secure url
1143 BSE attempts to refresh to the other "side" of the site to set the
1146 BSE does some simple comparisons to attempt to determine whether the
1147 logon form was triggered on the secure side of the site (possibly from
1148 the shop) or on the insecure side. Since CGI doesn't necessarily give
1149 us all the information required, it's possible it will guess wrong.
1151 Setting this option to 1 will enable debugging information sent to
1152 standard error, which will be sent to the error log on Apache. This
1153 probably isn't useful on IIS.
1157 Reports errors to STDERR (hence to the error log on Apache) if there
1158 is a problem deleting the actual file when an attached file is
1161 =item mail_encryption
1163 Reports debugging information to standard error while encrypting your
1168 Reports cookies received from the browser and sent to the browser to
1169 STDERR (hence to the error log on Apache.)
1173 If nonzero the session hash is dumped to STDERR after it is retrived
1176 =item subscription_expiry
1178 If non-zero then subscription expiry date calculations are dumped to
1181 =item jit_dynamic_regen
1183 If non-zero then information about jit_dynamic_regen is sent to
1188 If non-zero then the ifUserCan tag will output some trace information
1193 Enables some trace messages from tags that return an ENOIMPL
1194 exception. This can be useful for tracking down why a tag isn't being
1195 replaced. This will produce a lot of output during page regeneration.
1201 Contains various URIs.
1203 This is underused, so don't rely on it yet.
1211 The URI to the CGI directory. Default: /cgi-bin
1215 The URI where images included with BSE can be found.
1217 This includes images such as F<trans_pixel.gif> and C<admin/error.gif>.
1223 The URI where managed images are kept which should correspond to
1224 C<images> in C<[paths]>.
1226 Default: C</images> (from C<$Constants::IMAGES_URI>)
1230 The URL to the directory represented by scalecache. Defaults to
1231 I<[uri].images>F</scaled>.
1235 The URL to the directory configured as I<[paths].public_files>.
1243 This will provide translations from symbolic names to article ids.
1245 Currently this is used for converting article ids in the access
1246 control code, and for looking up the id of the shop.
1248 =head2 [printable type]
1250 If the user supplies a template name to printable.pl then you can use
1251 a different content type by adding an entry to this section. The key
1252 is the template name, and the value is the full content type.
1254 =head2 [search index scores]
1256 This section is used when generating the search index to override the
1257 default scores for each field in the articles.
1259 The default scores are:
1269 description 0 Products only
1270 product_code 0 Products only
1271 file_displayName 2 displayName for files
1272 file_description 2 description for files
1273 file_notes 1 notes for files
1275 =head2 [article flags]
1277 =head2 [product flags]
1279 =head2 [catalog flags]
1281 Flags that can be set for articles, products and catalogs
1282 respectively. Note that flags for articles are also visible in
1283 products and catalogs.
1285 All flag Ids are single letters or digits. Uppercase letters are
1286 reserved for use by BSE internally, leaving lower-case letters and
1287 digits for your own use.
1289 Use the id of the flag as the key, and a description of the flag as
1292 =head2 [article uris]
1294 Each key is an article id, the values are base URIs to store the HTML
1295 form of those articles and their children under.
1297 =head2 [protect link]
1299 The keys are ids of articles that shouldn't have their link field
1300 overwritten. The value should be a true value, but is otherwise
1309 The recipient for the data dump email sent by datadump.pl. Default:
1314 the From for the data dump email sent by datadump.pl. Default:
1321 Configuration for site users.
1327 If this is set to true then no passwords are required during
1328 registration, a confirmation email is sent immediately upon
1329 registration and that confirmation email contains a link the user can
1330 use to manage their details.
1332 This option has some security concerns since it can leave links to the
1333 user's information in the browser history. This option is not
1336 You cannot use this to control access to the shop.
1342 =item require_street
1344 =item require_suburb
1348 =item require_postcode
1350 =item require_telephone
1352 =item require_facsimile
1354 =item require_country
1358 =item require_organization
1360 Set these to true to require the corresponding field during
1361 registration, and to keep it required after modification. Default:
1364 If you enable any of these, you should enable C<info_on_register> as
1365 well, or modify the registration template to include the given fields.
1367 =item display_I<field name>
1369 Controls how the given field is displayed in error messages. If you
1370 change the field names on the registration and/or options forms you
1371 should probably change them here too. Default: internal field name
1372 with the first character converted to upper-case.
1374 =item info_on_register
1376 If this is set then the user info is prompted for during user
1377 registration. The information still isn't required unless the
1378 appropriate require_I<field> option is set. Default: false.
1380 =item register_refresh
1382 The default URL to refresh to on completing registration if no r
1383 parameter is supplied.
1387 If this is set then the subcription checkboxes are all checked on
1388 registration by default. Default: false.
1390 The user will only receive the subscriptions if they leave them checked
1391 and follow the link in the confirmation email.
1393 =item subscribe_I<id>
1395 Where I<id> is the number identifying a subscription. If this is set
1396 then the subscription checkbox for that subscription will be checked
1397 by default on the registration form. Default: false.
1399 The user will only receive the subscriptions if they leave it checked
1400 and follow the link in the confirmation email.
1402 You can get the I<id> of a subcription by looking at the Edit link on the
1403 subscriptions management page, the number after "id=" is the id.
1405 =item billing_on_main_opts
1407 If set to zero then user billing options will be managed on a separate
1408 page. This is controlled by the user/options_base.tmpl template.
1412 If set to zero then users cannot register themselves. Default: true,
1413 allowing users to register themselves.
1415 =item notify_register
1417 If true then an email is sent when a new user registers on your site.
1418 The email address sent to is the first set of [site
1419 users].notify_register_email, [shop].from or $SHOP_FROM from
1422 No email is sent if a new user is created from the administration user
1425 See also: notify_register_email, notify_register_subject.
1427 =item notify_register_email
1429 The email to sent the registration notification too. See
1430 notify_register above.
1432 =item notify_register_subject
1434 The subject of the notification email sent when a new user registers.
1435 Any {I<field>} is replaced with the given field from the registered
1436 user. See notify_register above.
1438 Default: New user {userId} registered
1440 =item notify_register_customer
1442 If non-zero then email id C<notify_register_customer> will be sent to
1443 new user on registration. By default this uses template
1444 user/email_register, subject "Thank you for registering" which can be
1445 overridden in [email notify_register_customer] or via the
1448 =item notify_register_customer_admin
1450 If non-zero then the behaviour described for
1451 C<notify_register_customer> will take place when a new member is added
1452 by an administrator. Defaults to the value of
1453 C<notify_register_customer>.
1457 =head2 [payment type names]
1459 This section and [payment type descs] are used to configure new
1462 The key is the integer representing the payment type. The value is
1463 the name used in tags for checking the payment type.
1465 You can also add a description (currently unused) to [payment type
1468 You should use numbers starting from 10 to avoid conflicts with future
1471 =head2 [payment type descs]
1473 See [payment type names].
1475 =head2 [payment type required]
1477 Set the key given by the payment type id to a value of a
1478 comma-separated list of fields required for that payment type.
1480 =head2 [help style I<style-name>]
1482 This type of configuration section is used to set values for a style
1483 of help icon. Only the C<template> and C<prefix> values are used
1484 directly by the code, the others are used by the default helpicon
1491 The URI to the help files for this style. Default: /help/ in style
1492 "user", /admin/help/ in style "admin".
1496 The template used to produce the icon. Default: helpicon in style
1497 user, admin/helpicon in style "admin".
1501 URI to the help icon image. Default: /images/admin/help.gif
1505 The width of the help icon image. Default: 16
1509 The height of the help icon image. Default: 16
1513 If you just want to change the help icon image for user help icons you
1517 icon=/images/help.gif
1523 =item allowed_referer
1525 A semi-colon (;) separated list of referer domains that are allowed to
1526 link to the C<a_set> target of L<affiliate.pl>.
1528 If the user's browser supplies a referer header then it will be
1529 checked against this list.
1531 =item require_referer
1533 If this is set then the C<a_set> target of L<affiliate.pl> will
1534 require that the user's browser supply a Referer header.
1536 =item default_refresh
1538 If no C<r> parameter is supplied to the C<a_set> target of
1539 L<affiliate.pl> then this is used as the default refresh.
1541 Default: the site base url.
1543 =item subscription_required
1545 This is either the numeric or text of a subscription for which the
1546 affiliate must have an active subscription.
1550 A single letter flag which the site administrator must set for the
1551 affiliate page to be displayed for the given member.
1555 If this is set then affiliate.pl will set the named cookie to the
1560 This is a comma-separated list of other cookies that should be set by
1561 the a_set target. The values for the cookies should be passed to the
1562 a_set target. For example with:
1565 other_cookies=alpha,beta
1569 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1571 is accessed, then the cookie alpha is set to "1", beta is set to "2".
1572 The cookie gamma will not be set since it's not listed.
1576 Used as the link base URL for the afflink.tmpl side bar template when
1577 an affiliate id is set. Default: example.com
1581 Used at the text of the link for the afflink.tmpl side bar template
1582 when an affiliate id is set. Default: Your Site.
1586 Used as the link URL for the afflink.tmpl side bar template when an
1587 affiliate id is not set. Default: example.com
1591 Used as the text of the link for the afflink.tmpl side bar template
1592 when an affiliate id is not set. Default: Our site
1596 =head2 [BSE Siteuser Images]
1598 Each key is the id of a member image, with a corresponding [BSE
1599 Siteuser Image I<image_id>] section. The values are ignored.
1601 =head2 [BSE Siteuser Image I<image_id>]
1603 Provides information about a single member image "template".
1609 Short description on the image, like "Logo". Used in error messages.
1613 Longer description of the image. Accessible with the member_image tag.
1623 The minimum and maximum dimensions of the image.
1625 =item widthsmallerror
1627 =item heightsmallerror
1629 =item widthlargeerror
1631 =item heightlargeerror
1633 Error messages displayed in the when the image is outside the
1634 configured dimensions.
1640 Default error messages for the above.
1644 Maximum storage the image can use in bytes. Default: 1000000.
1648 Error message displayed if the image uses too much storage.
1654 Various editor settings.
1660 If this is non-zero the system will attempt to load the configured
1661 thumbnail class, and put thumbnail images on the image manager page
1662 rather than full-size images. Default: off
1666 The name of a perl class that implement's BSE's thumbnail API. At
1667 this point the only class that implements that is BSE::Thumb::Imager,
1668 supplied with BSE. Default: None
1670 =item default_thumbnail
1672 URI to the default thumbnail image. This is presented when the
1673 runtime production of a thumbnail image fails.
1675 =item default_thumbnail_width
1677 =item default_thumbnail_height
1679 Dimensions of the default thumbnail image.
1681 =item default_thumbnail_alt
1683 Alt text for the default thumbnail image.
1685 =item check_modified
1687 If this is true then BSE will check the value of the lastModified
1688 parameter passed against the value in the article. If these don't
1689 match the article isn't saved and is redisplayed with an error
1690 message. This provides simple protection against one user saving
1691 changes over those made by another.
1705 Default values for the thumbimage tag.
1711 Each value is used as the relative or absolute name of a file or
1712 directory to load more configuration data from.
1714 The keywords must remain unique.
1716 Only the [includes] section from bse.cfg itself is used to locate more
1719 If the value references a directory, all files with an extension of
1720 C<.cfg> are read for configuration data.
1722 The order the files are read (which later files overriding older
1733 the entries in [includes] are sorted alphabetically (or rather
1734 asciily), so an entry with key "A" is read before one with key "B",
1735 one with key "01" is read before "02", but key "10" would be read
1740 if an entry is a file then that is read and the values merged.
1744 if an entry is a directory, then that is scanned and the files found
1745 read alphabetically as above.
1751 This is used to configure the error icon displayed next to fields that
1758 URI to the image file.
1764 The width and height of the error icon image.
1768 =head2 [site user flags]
1770 Flags that can be set for site users.
1772 All flag Ids are single letters or digits. Uppercase letters are
1773 reserved for use by BSE internally, leaving lower-case letters and
1774 digits for your own use.
1776 Use the id of the flag as the key, and a description of the flag as
1779 =head2 [article defaults]
1781 =head2 [catalog defaults]
1783 =head2 [product defaults]
1785 These sections contain defaults values for the corresponding article
1788 Each key is the name of a column for the article type.
1790 If an entry is not found in [catalog defaults] then [article defaults]
1793 If an entry is not found in [product defaults] then [article defaults]
1796 These sections are checked B<after> the C<[children of >I<id>C<]> and
1797 C<[level >I<level>C<]> sections.
1799 These defaults are used when creating an article where no value is
1800 supplied, they can also be accessed via the <:default I<name>:> tag.
1802 =head2 [newsletter filters]
1804 Contains C<criteria>I<index> entries starting from C<criteria1>, then
1807 Each entry consists of a filter class name, followed by a ; followed
1808 by data passed to that filter.
1810 ; user the original SQL based filter, configured from
1812 criteria1=BSE::NLFilter::SQL;foo
1814 See the documentation for each filter to configure the filters.
1816 =head2 [Query Groups]
1818 The key of each entry is the numeric identifier of a query group, the
1819 values are the name of the query group. For example:
1824 [query group some name]
1825 sql=select id from bse_siteusers where id = ? and name1 like '%some%'
1827 Each entry also has a corresponding [Query Group I<name>] section.
1829 =head2 [query group I<name>]
1831 This section corresponds to an entry in [Query Groups].
1837 This is an SQL statement. One placeholder is required and is passed
1838 the siteuser id (primary key) of the user to be checked. If this
1839 query returns I<any> rows then the user is considered part of the
1844 =head2 [template types]
1846 Each key is a template name, the value is the content type to be used
1847 when displaying the template dynamically.
1849 =head2 [template descriptions]
1851 Each key is a template name, the value is a description used in the
1852 template dropdown for that template.
1856 This section defines CSS class names for BSE's body text link tags.
1857 The key is the tag name, the value is the CSS class to be used.
1859 By default the class used is the same as the name of the tag, but you
1860 can switch this off by adding an entry setting the class to the empty
1861 string, for example:
1863 ; no class attribute for any of the links
1870 You can set p here too to set the class for paragraphs generated as
1871 body text. By default no class is set.
1875 Controls the behaviour of the window displayed by the popimage[] body
1876 text tag. If the Javascript for this has been customized then this
1885 Extra width and height for the window beyond the size of the image.
1886 Default: no extra width or height.
1890 If set to non-zero popimage[] will attempt to centre the popup within
1891 the current window. Default: 0.
1897 This is used to configure the DevHelp::Payments::Inpho module.
1903 If this is set then the test parameters are used instead of the
1908 The URL to process requests through.
1910 Default: https://extranet.inpho.com.au/cc_ssl/process
1914 Inpho supplied user name.
1918 Inpho supplied password.
1922 The URL to process test requests through.
1926 The user to supply to test requests.
1930 The password to supply to test requests.
1936 This section controls whether some custom class methods are called:
1942 If this is non-zero then siteuser_saveopts is called.
1946 =head2 [levelI<level> menus]
1948 Where I<level> is the article level at which the defined menu options will be available.
1949 Configure each menu value and description as I<key> and I<value>.
1960 To create a menus using such values, use the "allkids_of" iterator "filter" option.
1964 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1968 =head2 [title alias]
1970 Enable the "titleAlias" article field and set which level it will be available.
1976 Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1977 set the value to non-zero.
1984 The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1985 for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1986 in place of the article "title" when appropriate.
1990 =head2 [thumb geometries]
1992 Each key represents a geometry identifier for use by the thumbimage[],
1993 gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1994 ...:>, <:dthumbimage ...:> template tags.
1996 The key is the geometry identifier, the value is the geometry string
1999 The geometry string consists of:
2009 crop flag - if present
2017 The dimensions can be in any of the following forms:
2023 <width>x<height> - the desired maximum width and height. eg 200x150
2027 <width>x - the desired width, with the height calculated
2028 proportionally based on the source image size
2032 x<height> - the designed height, with the width calculated
2033 proportionally based on the source image size.
2037 <size> - the desired maximum size in both directions. so "200" is
2038 equivalent to "200x200"
2042 The crop flag is a single letter "c", if present then the image should
2043 be scaled so the smaller dimension matches the requested size, and the
2044 longer dimension will be cropped to fit.
2046 The fill if present is: fill(color) where color is a color recognized
2047 by the underlying graphics implementation. This should be at least
2048 hex web colors without the #, eg fill(FF0000) will fill with red.
2050 =head2 [thumb classes]
2052 Each key represents a geometry identifier for use by the thumbimage[],
2053 gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
2054 ...:>, <:dthumbimage ...:> template tags.
2056 The value is used as the class for the generated img tag.
2060 Each value represents a handler or script name for the <:dyntarget
2061 I<script> I<target> ...:> tag.
2063 Each key has a TARGET version and a no-TARGET version, with the key
2064 suffixed with C<_n>.
2066 The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
2067 default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
2069 For other targets the default is
2070 C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
2071 C</cgi-bin/>I<script>C<.pl>.
2073 The string C<TARGET> is replaced with the target specified in the
2076 This, along with dyntarget is intended to allow a more "Web 2.0" type
2077 of access to BSE. eg. you might set:
2083 and have a rewrite rule:
2085 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
2087 =head2 [popimage class I<classname>]
2089 This defines the settings for a class of images generated by the
2090 popimage[] and gpopimage[] body text markup tags. For example, the
2091 settings for C<popimage[imageid|foo]> can be found in section
2092 C<[popimage class foo]>.
2098 The html generated for this class. Tags of the form
2099 C<{>I<identifier>C<}> are replaced, where I<identifier> can be
2100 C<inline_> or C<outline_> followed by an image field name, for example
2101 C<inline_src> is the URL to the inline image.
2103 Default: <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>
2105 The default may be tuned as needed.
2109 The inline image geometry. Default: editor (the value used for
2110 thumbnails on the admin side)
2114 The outline image geometry. If no value is supplied then the original
2115 image values are used.
2119 =head2 [mail resources]
2121 Each key is the identifier of a file that can be attached to
2122 BSE::ComposeMail emails. The value is comma separated filename,
2123 content type, inline status.
2125 The files are searched for through the template search mechanism, so
2126 the filename can be relative to either the master or local templates
2129 If the content type is not supplied, if the filename end in gif, png
2130 or jpg the appropriate content type is used, otherwise
2131 application/octet-stream.
2133 If the inline status is not supplied then images are considered
2134 inline, and other files arent.
2136 =head2 [shop registration]
2138 Each key represents a message id from attempts to checkout. Except
2139 the all key which covers all cases.
2141 If the C<all> key or the message id key is non-zero then the checkout
2142 page will redirect to registration instead of login if the cart or
2143 configuration requires that the user be logged in.
2145 =head2 [template I<template-name>]
2147 Settings for articles based on a particular template.
2151 =item no_cache_dynamic
2153 Controls whether a cache-control: no-cache header will be produced.
2154 Can be overridden with the A and B article flags. If not set the
2155 value of [article].no_cache_dynamic is used.
2161 Global settings for articles.
2165 =item no_cache_dynamic
2167 Controls whether a cache-control: no-cache header will be produced.
2168 Can be overridden with the A and B article flags or [template
2169 I<template-name>].no_cache_dynamic. If not set the value of
2170 [basic].no_cache_dynamic is used.
2176 For the <:recaptcha:> tag currently only used for fmail.pl.
2180 =item api_public_key
2182 =item api_private_key
2184 The public and private key you receive when you register with reCAPTCHA.
2186 =item error_I<error_code>
2188 Replace the error message for the given I<error_code> where
2189 I<error_code> is the reCAPTCHA error code
2190 (eg. "incorrect-captcha-sol") with dash replaced by underscore.
2194 error_incorrect_captch_sol=VERY BAD INPUT
2198 =head2 [global file metadata]
2200 Each key represents an item of metadata for files attached to
2203 The values are ignored.
2205 For each key, extra information is defined in the [file metadata
2208 =head2 [file metadata I<name>]
2210 Definition for the file metadata item I<name>.
2216 title - descriptive name of the metadata. Defaults to I<name>.
2220 rules - validation rules, separated by ;. Custom rules can be defined
2221 in [file metadata validation].
2225 ro - if non-zero the metadata cannot be modified directly by the admin
2226 (applications can still generate it). Default: writable.
2230 type - the data type of the metadata, any of string, text, enum,
2231 integer, real, image. If this is enum values must be defined and
2232 labels should be. Default: string.
2240 string - single line of text
2244 text - one or more lines of text
2248 integer - whole number
2252 real - number with decimal points
2256 enum - select from a list of possible values.
2266 values - semi-colon separated list of values for this metadata.
2270 labels - semi-colon separated list of labels for the values
2274 help - help html to display for the metadata
2278 data_name - (images only) the key to use to store the image data.
2279 Default: I<name>_data.
2283 width_name - (images only) the key to use to store the image width.
2284 Default: I<name>_width.
2288 height_name - (images only) the key to use to store the image height.
2289 Default: I<name>_height.
2293 cond - a perl expression indicating whether the metadata should be
2294 prompted for, for this file. $file is the file object. Default: 1.
2298 unit - text displayed after the entry box for the metadata. Default:
2299 empty. Useful for including a unit ("pixels") or format help
2304 =head2 [session cleanup]
2306 Controls the processing of the bse_session_clean.pl script.
2312 days - the minimum age in days of sessions to be removed. Default: 30.
2316 per - the number of records to remove per SQL delete request.
2321 count - the number of SQL delete requests to perform, maximum.
2326 optimize - whether to perform a table optimization after deleting
2327 records. Default: 1 (set to 0 to skip optimization)
2331 =head2 [nightly work]
2333 Controls the bse_nightly.pl script.
2339 jobs - a comma separated list of BSE background processes to run when
2340 bse_nightly.pl is run. Default: bse_session_clean
2344 I<other keys> - each key is a sort key, and the value is a single
2345 background task name. This allows add-ons to setup extra tasks
2346 without overwriting each other. The sugessted key format is:
2348 99 - two digit priority - 00 is executed first, 99 last
2349 package-name - name of package the task is for
2350 unique - extra text to make the key unique, if necessary
2356 Parameters controlling where cached information - eg. file upload
2363 class - the BSE::Cache compatible cache class. See the documentation
2364 of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
2370 Database connection parameters. These override the settings in
2371 Constants.pm which are deprecated.
2377 dsn - the DBI dsn used to connect to the database. Default:
2382 user - the logon to the database. Default: $Constants::UN
2386 password - the password for the user. Default: $Constants::PW.
2390 dbopts - a perl expression that should evaluate to a hash reference.
2391 Default: $Constants::DBOPTs, or an empty hashref.
2395 class - the database wrapper class to use. Default: BSE::DB::Mysql.
2396 No other values are currently supported.
2400 =head2 [extra a_config]
2402 Defines extra configuration to be returned from the BSE system
2405 Each key is the keyword in the returned JSON object. If the key
2406 already exists it is not overwritten.
2408 Each value is the name of a section in the BSE configuration. The
2409 strings "{level}", "{generator}", "{parentid}", "{template}" are
2410 replaced with their values from the article that config is being
2416 menu=level{level} menu
2424 menu: { alpha: "One", beta: "Two" }
2426 in the returned configuration
2428 =head2 [cookie names]
2430 This section maps BSE's default cookie names to alternate names. This
2431 can be useful if you have two BSE sites under the same domain and need
2432 to ensure they use different cookies.
2439 =head2 [siteuser updates]
2441 Each key identifies an update specification for userupdate.pl, the
2442 value is a description of the specification.
2444 See L<< [siteuser update I<specid>] >> for the rest of the import
2448 =head2 [siteuser update I<specid>]
2450 Currently contains only a single key:
2456 fields - a semi-colon separated list of fields to import. Must
2457 contain one of C<id> or C<userId> which is used as a key to identify
2458 the user to update. An C<x> entry is a field to ignore. Some fields,
2459 such as C<confirmed> may not appear in this list.
2465 Configuration for BSE's PayPal integration.
2467 It shouldn't be necessary to change any of the URLs.
2473 test - if true, then the PayPal sandbox is used, and the configuration
2474 entries starting in C<test_> are used. If false, PayPal is live, and
2475 configuration entries starting in C<live_> are used. Default: 1.
2479 test_api_username, test_api_password, test_api_signature - API
2480 credentials for test mode. Required in test mode.
2484 live_api_username, live_api_password, live_api_signature - API
2485 credentials for live mode. Required for live mode.
2489 test_ws_url - URL to make NVP requests through in test mode. Default:
2490 https://api-3t.sandbox.paypal.com/nvp
2494 test_refresh_url - PayPal URL to refresh to in test mode. Default:
2495 https://www.sandbox.paypal.com/webscr
2499 live_ws_url - URL to make NVP requests through in live mode. Default:
2500 https://api-3t.paypal.com/nvp
2504 live_refresh_url - PayPal URL to refresh to in live mode. Default:
2505 https://www.paypal.com/cgibin/webscr
2509 =head2 [paypal custom]
2511 Extra parameters supplied to the SetExpressCheckout API. See the
2512 Express Checkout Advanced Features Guide (from PayPal) for details.
2514 Some settings that may be useful:
2520 PAGESTYLE - the style of payment page to use from those listed in your
2525 HDRIMG - https URL to an image to use in the payment page header.
2529 HDRBACKCOLOR - a 6 hex digit color to use as the background of the
2530 payment page header.
2534 HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
2535 payment page header.
2545 mail - if non-zero any emails sent through BSE::ComposeMail are logged
2546 in the audit log. Default: 0.
2550 mail_max_dump - if non-zero this is the size limit of the dump stored
2551 in the audit log when [audit log].mail is enabled. Default: 50000.
2555 =head2 [audit log I<facility>]
2557 Most commonly C<[audit log bse]>. Controls whether given events or
2558 families of events are logged.
2566 =item I<component>C<:>I<module>
2568 =item I<component>C<:>I<module>C<:>I<function>
2572 with the longer keys overriding the shorter keys, and defaulting to
2573 all actions being logged.
2575 =head2 [mail audit log]
2577 This enables sent when an event is logged in the audit log. Warning:
2578 for common events this will result in large amounts of email.
2584 to - the email address to send the email to
2588 emerg, alert, crit, error, warning, notice, info, debug - if present
2589 and true then events at these levels result in an email. If the value
2590 contains an C<@> then the value is used as the recipient address.
2594 I<facility>-I<component>
2598 I<facility>-I<component>-I<module>
2602 I<facility>-I<component>-I<module>-I<function>
2604 Controls sending an email for specific events or families of events.
2605 If the value is true, send an email for that event. If the value
2606 contains an C<@> then the value is used as the recipient address.
2610 with the longer keys overriding the shorter keys, and defaulting to
2611 all actions being logged.
2615 Contains options to pass to HTML::Tidy. Anything not listed below is
2616 passed directly to HTML::Tidy->new.
2622 ignore_types - types of message to ignore separated by commas, any,
2623 all or none of info, warning, error.
2627 ignore_text_I<key> - messages to ignore, I<key> is not used, just the
2633 =head2 [email I<token>]
2635 Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
2641 template - plain text template
2645 html_template - HTML template (defaults to the value of I<template>
2646 followed by C<_html>
2650 subject - subject of the email, can be overridden with the
2655 from - from email address, defaults to the shop from address
2659 from_name - from name
2663 allow_html - controls whether HTML is allowed. By default this is
2664 based on the user's settings.
2668 =head2 [lost password]
2674 daily_limit - the number of recovery attempts permitted per day.
2679 age_limit - the id included in the email is valid for this many days.
2684 =head2 [link replacement]
2686 For formatted text, this is a list of URL prefixes to replace.
2688 The key is a sort key, replacements are checked in alphabetical order.
2690 The value is the original prefix, followed by ";", followed by the
2693 Replacement is performed case-insenitively. Regexp metacharacters
2695 =head2 [article categories]
2701 ids - a comma separated list of category ids. There are (currently)
2702 no restrictions on the contents of these ids, but alphanumerics are
2703 recommended to simplify templates.
2707 I<id> - a description for a particular category id. Overridden by the
2708 C<name> key in C<< [article category I<id>] >>. Default: ucfirst of
2713 =head2 [article category I<id>]
2719 name - name of the article category.
2723 Other keys may be used as desired, eg. to make it simpler to configure
2724 article behaviour based on the category.
2726 =head2 [article menu]
2728 This section can be used to add new menu items to the menu displayed
2729 on article edit pages.
2731 The keys are used for sorting only.
2733 The value is comma-separated:
2743 target identifier, to be set to 1 on making a request to the script.
2747 the label for the item in the menu.
2753 sample,a_foo,Sample Item
2755 will generate a link like:
2757 <a href="/cgi-bin/admin/sample.pl?id=10&a_foo=1">Sample Item</a>
2759 where 10 is the id of the article being edited.
2761 Keys with a prefix of C<bse_> are reserved for BSE internal use.
2763 =head2 [undeletable articles]
2765 Keys are the ids of articles that may not be deleted.
2767 This applies if the value of the entry is a true perl value.
2769 [undeletable articles]
2772 ; article 3 is deletable
2775 =head2 [dummy shipping methods]
2777 Configures extra shipping methods only selectable from the order
2780 Entries are sorted by value.
2782 If the value contains a comma the text up to the comma is removed and
2783 the remains used as the label, otherwise the key is used as the label.
2785 =head2 [article custom fields]
2787 =head2 [product custom fields]
2789 =head2 [catalog custom fields]
2791 These can be used to define article, product and catalog custom fields
2792 respectively, in a similar manner to L<formmail>.
2794 The field names are predefined, C<customDate1>, C<customDate2>,
2795 C<customInt1>, C<customInt2>, C<customInt3>, C<customInt4>,
2796 C<customStr1> and C<customStr2>, but are only active if a description
2797 is defined for the field:
2799 [article custom fields]
2800 customInt1_description=Stock Level
2802 =head2 [siteuser passwords]
2804 Rules for validating (not verifying) site user passwords. Possible
2811 C<length> - the minimum length of passwords. This replaces
2812 C<minpassword> in C<[basic]>.
2816 C<entropy> - the minimum password entropy as measured by
2817 L<Data::Password::Entropy>.
2821 C<symbols> - if non-zero, the password must contain non-alphanumerics.
2825 C<digits> - if non-zero, the password must contain digits.
2829 C<mixedcase> - if non-zero, the password must contain both upper and
2834 C<categories> - the number of categories out of 5 required out of
2835 symbols, digits, upper case, lower case and extended ASCII/Unicode.
2836 This should typically never be 5.
2840 C<notuser> - the password and user name may not match each other
2845 C<notu5er> - the password may not match the user name
2846 case-insensitively, even with symbol replacement (e.g. "5" for "S".
2850 =head2 [admin user passwords]
2852 Rules for validating (not verifying) administrative user passwords.
2853 See L</[siteuser passwords]> on the keys that can be set.
2855 =head2 [site user lockouts]
2857 Controls when accounts and IP addresses are locked out due to repeated
2858 site user authentication failures.
2864 I<account maximum failures> - the maximum number of login failures for
2865 a given account in I<account time period>. A successful login of the
2866 account resets the count. Default: 3.
2870 C<account_time_period> - the number of minutes in which
2871 C<account_maximum_failures> login failures occurring will cause an
2872 account lock-out. Default: 10.
2876 C<account_lockout_time> - the number of minutes to lock out an account
2877 that fails too many logins. Default: 60.
2881 C<ip_maximum_failures> - the maximum number of login failures for a
2882 given IP address with-in C<ip_time_period>. A successful login of any
2883 account at the IP address resets the count. Default: 10.
2887 C<ip_time_period> - the number of minutes in which
2888 C<ip_maximum_failures> login failures occurring causes an IP address
2889 lock-out. Default: 30.
2893 C<ip_lockout_time> - the number of minutes to lock out an IP
2894 address that fails too many logins. Default: 120.
2898 C<ip_maximum_failures2> - the maximum number of login failures for a
2899 given IP address with-in C<ip_time_period>. A successful login of any
2900 account at the IP address I<does not reset> the count. Default: 50.
2904 C<ip_lockout_time2> - the number of minutes to lock out an IP address
2905 that fails too many logins against C<ip_maximum_failure2>. Default:
2910 Note: an administrator unlocking an account resets the account lock
2911 count but has no effect on the IP address lock count. An
2912 administrator unlocking an IP address resets both IP address lock
2913 counts, but has no effect on account lock counts.
2915 =head2 [admin user lockouts]
2917 Control account and IP address lockouts for admin user authentication.
2919 See L</[site user lockouts]> for details of the configuration
2922 =head2 [pregenerate]
2924 Defines templates to be generated as base templates.
2926 Each entry is of the form:
2930 I<output-template>=I<profile-name>,I<input-template>
2940 I<output-template> - the output template name, stored in the directory
2941 defined by [paths].templates
2945 I<profile-name> - used to select a section in the config file to load
2946 dummy article settings from, as C<< [I<profile-name> settings] >>.
2950 I<input-template> - the source template to generate from.
2954 =head2 [automatic data]
2956 This section defines article metadata to be used in fetching content
2959 The metadata definition for the URL field must be separately defined
2960 in C<[global article metadata]>.
2962 See L<bse_fetch.pl> for more details.
2968 C<< dataI<suffix> >> - defines the metadata entry to store the
2969 retrived content in. This is the only required configuration,
2973 C<< urlI<suffix> >> - defines the metadata entry to retrieve the URL
2974 or URL part from. Defaults to the value of C<< dataI<suffix> >>
2975 followed by C<_url>.
2979 C<< url_patternI<suffix> >> - defines a simple URL template. Any
2980 C<$s> in this string is replaced with the value retrieved from the
2981 metadata field defined by C<< urlI<suffix> >>. Default: C<$s>.
2985 C<< url_patternI<suffix> >> - set to true to URL escape the value
2986 retrieved from the metadata field defined by C<< urlI<suffix> >>.
2991 C<< url_patternI<suffix> >> - set to a perl regular expression to
2992 validate the content type of the data fetched. Default: a regular
2993 expression matching JSON content.
2997 C<< validateI<suffix> >> - how to validate the fetched content.
2998 Currently the only possible values are C<none>, which does no
2999 validation, and C<json> which validates the content as JSON. Default:
3004 C<< max_lengthI<suffix> >> - the maximum length in bytes of the
3005 retrieved content. Default: 1000000.
3009 C<< on_failI<suffix> >> - how to treat the currently stored content if
3010 the fetch fails. Possible values are C<delete> which deletes the
3011 content metadata, or C<keep> which doesn't. Default: C<delete>.
3015 C<< on_successI<suffix> >> - actions to take on successful fetch,
3016 which currently only has two possible values, either C<log> to log a
3017 success message to the audit log, or an empty string to not do so.
3018 Default: an empty string.
3022 =head2 [customizers] and [subscribers]
3023 X<configuration, [customizers]>X<configuration, [subscribers]>
3029 Tony Cook <tony@develop-help.com>