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.
67 Contains various file system paths.
73 This is where the files uploads with the file wizard are stored. It
74 must be writable by the web server user.
78 Directory containing administrative templates. Note: this is not
79 completely implemented for now, so assume the default. Default: admin
80 directory under $TMPLDIR.
84 Directory base for most templates. This can contain references like
85 $(section/key) to other configuration entries. Split on the systems
86 PATH separators (run: perl -V:path_sep)
90 Local Directory base for templates. This is searched before the
91 templates directory. This can contain references like $(section/key)
92 to other configuration entries. Split on the system's PATH separator.
96 Web server document root. Static pages are generated under this
97 directory. Default: $CONTENTBASE.
101 Where uploaded images are stored. This is not yet completely
102 implemented. Default: $IMAGEDIR.
106 Local search path for BSE::Custom, or the class configured by
107 C<custom_class> in [basic].
109 =item siteuser_images
111 Where uploaded siteuser images are stored. This must be set in the
112 config file. The default bse.cfg include an entry to use the current
113 values of [paths].downloads
117 Pregenerated dynamic article pages are stored here. This must be
118 defined if you site contains any dynamicly generated pages.
122 The directory where cached versions of scaled thumbnails are stored.
123 Defaults to image_dir/scaled. This must be in the document tree. If
124 you set this you should also set scalecacheurl.
128 The URL to the directory represented by scalecache. Defaults to
135 This section is used by the file wizard to map uploaded file
136 extensions to MIME content types. This can be used to extend
137 BSE::FileEditor's internal extension map. It cannot override that
140 The key for each entry is the extension, without the leading '.'.
144 xls = application/msexcel
148 Used for translating symbolic template names into full names under the
151 In each case the default is the name with a C<.tmpl> extension.
161 user registration page
165 =head2 [admin templates]
167 Used for translating the names of administration templates into filenames.
169 In each case the default is the name with a C<.tmpl> extension.
179 Catalog editor page. Default admin/edit_catalog.tmpl
191 Article edit pages. Default admin/edit_<number>.tmpl
195 Step child/parent management page. Default admin/edit_steps.tmpl
207 The value of the charset keyword when outputting HTML from a script.
208 Set to the empty string to suppress the charset keyword. Default:
213 If this is a non-zero number, then all but mailto links are redirected
214 to C<nuser.pl/redirect> so you can display a diclaimer. If this
215 contained alphabetics it's treated as a comma separated list of url
216 schemes that should be handled via C<nuser.pl/redirect>. If 0 or not
217 present, no redirection is done.
219 The redirect URL includes a hash of the url, title and the redirect
220 salt to prevent using this mechanism by external sites for cookie
225 The salt used in generating the has for redirect_links. Default: an
230 If non-zero then any HTML output is validated with HTML::Tidy.
231 Validation errors and warnings are sent to the audit log. See [html
240 =item cookie_lifetime
242 The expiry time for cookies. This should be in the form supported by
243 CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
244 number, and a time character (s - seconds, m - minutes, h - hours, d -
245 days, M - months). Default: +3h
249 This overrides the domain value set for cookies. This is useful if
250 you allow the site to run under both example.com and www.example.com,
251 if you set cookie_domain to example.com then a user visiting
252 www.example.com will still have their cookies when they visit
257 This overrides the cookie name used to store the session id. Default:
258 sessionid. This is useful when you have 2 sites under the same
259 top-level domain, and helps disambiguate the cookie returned by the
264 Minimum password length in characters. Default: 4.
268 Device to read random data from. This device should not block when it
273 If this is true then the encrypted messages containing the customer's
274 credit card number are sent to the shop owner signed. To avoid
275 keeping a passphrase and signing key on the server you can set this to
276 false (0). This has the effect that anyone could send you an unsigned
277 message encrypted with your public key, though this may not be a
278 security threat. Default: True.
282 If this is true then the links to your articles within BSE will be
283 followed by a / and then by a simplified version of the article title.
284 The aim is to include at least some title information in the URL
285 without modifying the name of the HTML file. Default: False.
289 If this is true then the user/group/permissions database is used to
290 control access to the system. Default: False.
292 =item access_filter_steps
294 If this is true, then the drop-down lists of possible stepparents and
295 stepchildren on the article edit pages are filtered for access control.
298 =item access_filter_parents
300 If this is true, then the drop-down lists of possible parents on the
301 newsletter edit pages are filtered for access control.
306 Set this to non-zero to enable authentication via server
307 authentication (usually Basic Authentication.) You should normally
308 set this if you set htusers below. Default: 0 (disabled)
312 This should be the path to a file to be updated with the list of users
313 and crypt() versions of their passwords. If this is set then the
314 security system will check for a user set by the browser before
315 attempting a form based logon. Default: None.
319 The name of the custom class for your site. This is currently only
320 used for article editing customizations. This class should derive
321 from BSE::CustomBase. Default: BSE::Custom.
323 =item jit_dynamic_pregen
325 If this is true, then pre-generation for dynamic pages will be delayed
326 until the page is displayed to a user. Default: off.
330 If true, the ifAjax and ajax tags will be active for static pages.
332 =item cache_thumbnails
334 If set to zero the results of the thumbimage/gthumbimage body/template
335 tags will not be cached. Default: 1 (caching is enabled).
337 =item static_thumbnails
339 If true and cache_thumbnails is true then thumbnails for the thumbnail
340 cache will be generated when a static page is regenerated, and the
341 link from the page will link to the image in the cache rather than to
342 C<thumb.pl>. Default: 1 (static thumbnails enabled).
346 The prefix applied to articles that use a linkAlias url. This should
351 If this is non-zero then an article with linkAlias set will use an
352 alias url instead of the "real" url. You will need to configure a
353 RewriteRule or ErrorDocument to page.pl to direct the user to the
354 correct URL. Default: 1.
358 If this is non-zero then the title is cleaned up (all but
359 alphanumerics removed) and appended to the alias URL generated.
361 =item default_popupimage
363 This is the default popup image class for the popimage[] and
364 gpopimage[] tags. Default: popup.
368 Some obsolete tags will warn to stderr if this is non-zero. Default:
371 =item no_cache_dynamic
373 If non-zero, the default, dynamic responses will include a
374 C<Cache-Control: no-cache> header. This can be overridden for
375 articles via , article flags, C<[template >
376 I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
381 If true then page.pl will 301 redirect (Moved Permanently) requests
382 for an article by its id to the generated link if the article has a
383 link alias. Default: false. Must only be used with use_alias true.
387 If this is non-zero, and a cache is configured (see [cache]), file
388 uploads are tracked in entries in the cache.
390 The fileprogress.pl script can be called by Ajax to display file
391 upload progress information to the user. The upload state is updated
392 a maximum of once a second.
394 =item http_only_session
396 If this is non-zero, the default, the session cookie sent to the
397 browser has the C<HttpOnly> attribute set. This can prevent session
398 cookie hijacking. Default: 1.
402 If this is non-zero then the session cookie sent to the browser has
403 the C<Secure> attribute set. This means that the cookie will only be
404 visible over https. This is only useful when the only URL the site is
405 visited over is a https URL. Default: 0.
407 =item make_userid_cookie
409 If this is non-zero, the default, then when the site member logs in, a
410 javascript visible cookie, C<userid> will be set that contains the
411 login name of the user. BSE's back-end doesn't use this cookie, its
412 only use is for Javascript to enable/disable user interface elements.
419 This section controls how BSE sends email.
425 The host or IP address of your mail server. If this is not set
426 C<sendmail> will be used instead. If this is set you must also set
431 The name that BSE uses to identify itself when sending mail via SMTP.
432 Required if I<smtp_server> is set.
436 The path to the C<sendmail> binary. Default: /usr/lib/sendmail
440 The options supplied to sendmail. Default: -t -oi
442 You may want to add the -odq option to this if you want mail queued
443 rather than sent immediately.
445 =item set_errors_to_from
447 If true, we add an Errors-To header set to the same as the From
448 header. Default: true.
450 =item html_system_email
452 If non-zero then emails sent via the compose mail system that aren't
453 being sent to a member record, will be sent as HTML, if the HTML
454 template is available.
458 If this is C<style> (the default) then use CSS::Inliner to attempt to
459 inline CSS in mail if the text "<style" is found in the generated
462 If this is C<force> then we always attempt to inline CSS.
464 If this is any other value then don't inline CSS.
466 =item inline_css_flags
468 A comma separated list of flags to supply to CSS::Inliner->new().
469 Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
470 attributes, and C<leave_style> to leave the HTML style block in place.
474 =item inline_css_report
476 If this is true and CSS inlining fails, log an error to the audit
477 log. This is intended for use in debugging and should be disabled in
478 production. Default: false (disabled)
482 =head2 [children of I<id>]
484 Where I<id> is the identifier for an article.
490 the name of the default template for children of the given parent
494 a comma-separated list of extra directories under $TMPLDIR to search
495 for templates that can be used for children of the given parent article.
499 =head2 [article I<id>]
501 Where I<id> is the identifier of an article.
507 A comma-separated list of extra directories under $TMPLDIR to search
508 for templates that can be used for children of the given parent
511 =item extra_templates
513 A comma-separated list of extra templates under $TMPLDIR that can be
514 used for the given article.
518 =head2 [level I<level>]
524 The default template for this level of article, assuming it hasn't
525 been set in the [children of I<article id>] section.
529 A comma-separated list of extra directories under $TMPLDIR to search
530 for templates that can be used for articles at the given I<level>.
540 The default template for catalogs.
550 The default template for products.
552 =item extra_templates
554 A comma separated list of extra templates that can be used for
561 This can be used to control translation of error messages. Each key
562 has a prefix identifying the module that uses the error, followed by
563 '/' followed by a specific identifier for the message.
565 Message parameters, expressed as $I<digit>, are replaced with the
566 parameters passed to the message. C<$$> is replaced with C<$>.
568 Each message identifier below is documented with the id, when it
569 occurs, the default message, and any parameters.
575 the user attempted to logon without entering a logon name. Default:
576 "Please enter a logon name". No parameters.
580 the user attempted to logon without entering a password. Default:
581 "Please enter your password." No parameters.
583 =item user/baduserpass
585 the user's logon name or password was not found or did not match.
586 Default: "Invalid user or password". No parameters.
588 =item user/notloggedon
590 the user attempted to logoff while not logged on. Default: "You
591 aren't logged on". No parameters.
593 =item user/optsoldpass
595 the user entered a new password on the options page without entering
596 their old password. Default: "You need to enter your old password to
597 change your password". No parameters.
599 =item shop/logonrequired
601 Displayed if the user attempts to checkout when [shop].require_logon
612 if non-zero, the order must be marked as paid for before the file can
617 if non-zero the order must be marked as filled before the files can be
622 if non-zero the user must be registered/logged on to download I<any>
627 if non-zero, downloads of userfiles will be logged. Default: 0
629 =item log_downufile_maxage
631 the maximum age of entries in the user file download log, in days.
636 =head2 [confirmations]
638 Control over confirmation emails.
644 The subject of email confirmation emails. Default: Subcription
649 The from field for the email. Default: $SHOP_FROM
653 =head2 [subscriptions]
655 Control over subscription messages.
661 The from field for the email. Default: $SHOP_FROM.
665 Default for the "Test Name" field for sending test subscription
670 Default for the "Test Email" field for sending test subscription
675 Set to 1 if you want the "Test Text Only" box checked by default for
676 sending test subscription messages.
680 Set to 0 to disable display of the test subscription messages portions
681 of the subscriptions send form.
683 =item text_link_inline
685 Set to format links as they appear in the text version of emails.
686 C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
687 the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>
691 Set to format links as they appear at the footer of the body text. If
692 this is set to the empty string then no list appears. C<$1>, C<$2>,
693 C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
694 replaced with newline. Default: C<[$3] $2>
696 =item text_link_list_prefix
698 A line of text produced above the list of URLs if there is one.
699 Default: C<----->. $n in this is replaced with newlines.
703 For example, if the configuration is:
705 text_link_inline="$1" ($3)
706 text_link_list_prefix=$n$n-------
707 text_link_list=($3) "$1"$n => $2
709 and the body text is:
712 link[http://www.example.com/|Example]
722 => http://www.yoursite.com/shop/index.html
724 => http://www.example.com/
730 =item highlight_partial
732 If this is true then partial matches will be highlight in search
733 result excerpts. Default: True
735 =item keep_inaccessible
737 If this is true then resulting articles that can't be accessed by the
738 user are listed in the search results. Default: false.
742 The default regular expression used to match words in text during
743 indexing. Default: \w+
745 =item wordre_I<fieldname>
747 The field specific word match regular expression for the built-in
748 search indexer. Default: the value of C<wordre>.
752 Module used to build the search index. Default: BSE::Index::BSE.
756 For C<BSE::Index::BSE>, the optimization priority. The default of
757 C<speed> builds the index in memory and is very fast, but can consume
758 a lot of memory. Otherwise, set this to C<memory> to reduce memory
761 C<memory> priority index building requires that the DBM::Deep module
766 =head2 [search highlight]
768 Sets the prefix and suffix used for highlighting matches for different
771 These are used by the highlight_result, excerpt, pageTitle, author,
772 keywords and matchFile tags.
774 Each field has a prefix and suffix entry. The key is
775 I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
776 file_I<fieldname>_prefix and file_I<fieldname>_suffix.
778 The default prefix is <b>. The default suffix is </b>.
780 For example you can do:
783 body_prefix=<span class="searchfound">
792 Used by some templates to check if the shop is enabled. Set this to 1
793 to enable the shop, or 0 to disable it.
795 =item secureurl_articles
797 If this is false then shop articles will not use the secureurl as their
798 baseurl. Default: True
800 =item register_if_files
802 If true the customer is required to register before checkout if there
803 are any for sale files attached to products in the cart. Default: True
807 If true the customer is required to be logged on before checkout,
808 whether or not for sale files are attached to products in the cart.
813 A comma-separated list of acceptable payment types. Default: 0
815 The possible payment types are:
821 0 - the user enters a credit card number, name and expiry date
825 1 - the customer will send a cheque
829 2 - contact customer for details
833 4 - paypal - see L<paypal.pod>
837 Other types can be added by adding entries to the [payment type names]
838 and [payment type descs] sections.
846 These are used by various shop templates to present an address that a
847 cheque payment should be sent to.
851 From email address for emails sent by the shop. Overides $SHOP_FROM
856 To name for emailed orders sent by the shop. Overrides $SHOP_TO_NAME
861 To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
866 BCC email address for order confirmation emails sent to the customer.
871 If this is true then orders sent to you by the shop will not be
872 encrypted. Enabling this disabled acceptance of credit card orders,
873 and the default for C<payment_types> will become C<1> instead or C<0>.
875 Please realize that other potentially commercially sensitive
876 information is being sent in the clear to a central location,
881 If true, then the order is email to to_email, possibly with credit
882 card information included. Default: $SHOP_EMAIL_ORDER.
884 =item display_I<field>
886 Used to translate the stored order field name into a presentation name
887 suitable for error messages.
891 The name of a class to load to process credit card transactions online.
893 Currently this can be either DevHelp::Payments::Test or
894 DevHelp::Payments::Inpho.
898 Name of the encryption module to use. Default: $SHOP_CRYPTO.
900 =item crypt_signing_id
902 Id of the key to sign the order email with. If this is non-empty then
903 the email is signed even if [basic].sign is false. Default:
908 Path to the GnuPG program. Default: $SHOP_GPG
910 =item crypt_passphrase
912 Passphrase of the key used to sign the email. Default:
917 If true, request the card type when requesting credit card
918 information. Default: False.
920 =item cart_entry_limit
922 Maximum number of entries in the cart. This limits the number of
923 distinct products (with options) in the cart, not the total
924 quantities. Default: Unlimited.
928 The shop currency as a 3-letter currency code. Default: AUD.
929 Currencies other than "AUD" aren't supported by most of the system.
933 Set to non-zero if you're using country codes in the order country
934 field. If this is set then the delivCountry is supplied as is to
935 various parts of the system, otherwise it is translated from a country
936 name to a country code. Default: 0.
946 A space-separated list of modules under Courier::, e.g. "Fastway::Road
947 AustraliaPost::Air". These will be made available as shipping methods
948 on the checkout page.
952 The post code from which products are shipped.
954 =item fastwayfranchisee
956 The name of the Fastway franchisee used to ship products from the
959 =item fastwayfranchiseecode
961 The Fastway franchisee code for the customer, if any.
965 =head2 [Shop Order Validation]
967 This section can contain extra order validation information, including
968 specifying required fields, display names and extra validation rules.
976 The maximum length of the article title field. Default: 255. Should
977 not be set higher than this unless you change the database schema.
983 Controls the interest.pl script.
989 Email address that is notified of the interest. Defaults to $SHOP_FROM.
1001 When a user logs on, and the site url is different to the secure url
1002 BSE attempts to refresh to the other "side" of the site to set the
1005 BSE does some simple comparisons to attempt to determine whether the
1006 logon form was triggered on the secure side of the site (possibly from
1007 the shop) or on the insecure side. Since CGI doesn't necessarily give
1008 us all the information required, it's possible it will guess wrong.
1010 Setting this option to 1 will enable debugging information sent to
1011 standard error, which will be sent to the error log on Apache. This
1012 probably isn't useful on IIS.
1016 Reports errors to STDERR (hence to the error log on Apache) if there
1017 is a problem deleting the actual file when an attached file is
1020 =item mail_encryption
1022 Reports debugging information to standard error while encrypting your
1027 Reports cookies received from the browser and sent to the browser to
1028 STDERR (hence to the error log on Apache.)
1032 If nonzero the session hash is dumped to STDERR after it is retrived
1035 =item subscription_expiry
1037 If non-zero then subscription expiry date calculations are dumped to
1040 =item jit_dynamic_regen
1042 If non-zero then information about jit_dynamic_regen is sent to
1047 If non-zero then the ifUserCan tag will output some trace information
1054 Contains various URIs.
1056 This is underused, so don't rely on it yet.
1062 The URI to the CGI directory. Default: /cgi-bin
1066 The URI where images are kept. Default: /images
1076 This will provide translations from symbolic names to article ids.
1078 Currently this is used for converting article ids in the access
1079 control code, and for looking up the id of the shop.
1081 =head2 [printable type]
1083 If the user supplies a template name to printable.pl then you can use
1084 a different content type by adding an entry to this section. The key
1085 is the template name, and the value is the full content type.
1087 =head2 [search index scores]
1089 This section is used when generating the search index to override the
1090 default scores for each field in the articles.
1092 The default scores are:
1102 description 0 Products only
1103 product_code 0 Products only
1104 file_displayName 2 displayName for files
1105 file_description 2 description for files
1106 file_notes 1 notes for files
1108 =head2 [article flags]
1110 =head2 [product flags]
1112 =head2 [catalog flags]
1114 Flags that can be set for articles, products and catalogs
1115 respectively. Note that flags for articles are also visible in
1116 products and catalogs.
1118 All flag Ids are single letters or digits. Uppercase letters are
1119 reserved for use by BSE internally, leaving lower-case letters and
1120 digits for your own use.
1122 Use the id of the flag as the key, and a description of the flag as
1125 =head2 [article uris]
1127 Each key is an article id, the values are base URIs to store the HTML
1128 form of those articles and their children under.
1130 =head2 [protect link]
1132 The keys are ids of articles that shouldn't have their link field
1133 overwritten. The value should be a true value, but is otherwise
1142 The recipient for the data dump email sent by datadump.pl. Default:
1147 the From for the data dump email sent by datadump.pl. Default:
1154 Configuration for site users.
1160 If this is set to true then no passwords are required during
1161 registration, a confirmation email is sent immediately upon
1162 registration and that confirmation email contains a link the user can
1163 use to manage their details.
1165 This option has some security concerns since it can leave links to the
1166 user's information in the browser history. This option is not
1169 You cannot use this to control access to the shop.
1175 =item require_address
1181 =item require_postcode
1183 =item require_telephone
1185 =item require_facsimile
1187 =item require_country
1191 =item require_organization
1193 Set these to true to require the corresponding field during
1194 registration, and to keep it required after modification. Default:
1197 If you enable any of these, you should enable C<info_on_register> as
1198 well, or modify the registration template to include the given fields.
1200 =item display_I<field name>
1202 Controls how the given field is displayed in error messages. If you
1203 change the field names on the registration and/or options forms you
1204 should probably change them here too. Default: internal field name
1205 with the first character converted to upper-case.
1207 =item info_on_register
1209 If this is set then the user info is prompted for during user
1210 registration. The information still isn't required unless the
1211 appropriate require_I<field> option is set. Default: false.
1213 =item register_refresh
1215 The default URL to refresh to on completing registration if no r
1216 parameter is supplied.
1220 If this is set then the subcription checkboxes are all checked on
1221 registration by default. Default: false.
1223 The user will only receive the subscriptions if they leave them checked
1224 and follow the link in the confirmation email.
1226 =item subscribe_I<id>
1228 Where I<id> is the number identifying a subscription. If this is set
1229 then the subscription checkbox for that subscription will be checked
1230 by default on the registration form. Default: false.
1232 The user will only receive the subscriptions if they leave it checked
1233 and follow the link in the confirmation email.
1235 You can get the I<id> of a subcription by looking at the Edit link on the
1236 subscriptions management page, the number after "id=" is the id.
1238 =item billing_on_main_opts
1240 If set to zero then user billing options will be managed on a separate
1241 page. This is controlled by the user/options_base.tmpl template.
1245 If set to zero then users cannot register themselves. Default: true,
1246 allowing users to register themselves.
1248 =item notify_register
1250 If true then an email is sent when a new user registers on your site.
1251 The email address sent to is the first set of [site
1252 users].notify_register_email, [shop].from or $SHOP_FROM from
1255 No email is sent if a new user is created from the administration user
1258 See also: notify_register_email, notify_register_subject.
1260 =item notify_register_email
1262 The email to sent the registration notification too. See
1263 notify_register above.
1265 =item notify_register_subject
1267 The subject of the notification email sent when a new user registers.
1268 Any {I<field>} is replaced with the given field from the registered
1269 user. See notify_register above.
1271 Default: New user {userId} registered
1273 =item notify_register_customer
1275 If non-zero then email id C<notify_register_customer> will be sent to
1276 new user on registration. By default this uses template
1277 user/email_register, subject "Thank you for registering" which can be
1278 overridden in [email notify_register_customer] or via the
1281 =item notify_register_customer_admin
1283 If non-zero then the behaviour described for
1284 C<notify_register_customer> will take place when a new member is added
1285 by an administrator. Defaults to the value of
1286 C<notify_register_customer>.
1290 =head2 [payment type names]
1292 This section and [payment type descs] are used to configure new
1295 The key is the integer representing the payment type. The value is
1296 the name used in tags for checking the payment type.
1298 You can also add a description (currently unused) to [payment type
1301 You should use numbers starting from 10 to avoid conflicts with future
1304 =head2 [payment type descs]
1306 See [payment type names].
1308 =head2 [payment type required]
1310 Set the key given by the payment type id to a value of a
1311 comma-separated list of fields required for that payment type.
1313 =head2 [help style I<style-name>]
1315 This type of configuration section is used to set values for a style
1316 of help icon. Only the C<template> and C<prefix> values are used
1317 directly by the code, the others are used by the default helpicon
1324 The URI to the help files for this style. Default: /help/ in style
1325 "user", /admin/help/ in style "admin".
1329 The template used to produce the icon. Default: helpicon in style
1330 user, admin/helpicon in style "admin".
1334 URI to the help icon image. Default: /images/admin/help.gif
1338 The width of the help icon image. Default: 16
1342 The height of the help icon image. Default: 16
1346 If you just want to change the help icon image for user help icons you
1350 icon=/images/help.gif
1356 =item allowed_referer
1358 A semi-colon (;) separated list of referer domains that are allowed to
1359 link to the C<a_set> target of L<affiliate.pl>.
1361 If the user's browser supplies a referer header then it will be
1362 checked against this list.
1364 =item require_referer
1366 If this is set then the C<a_set> target of L<affiliate.pl> will
1367 require that the user's browser supply a Referer header.
1369 =item default_refresh
1371 If no C<r> parameter is supplied to the C<a_set> target of
1372 L<affiliate.pl> then this is used as the default refresh.
1374 Default: the site base url.
1376 =item subscription_required
1378 This is either the numeric or text of a subscription for which the
1379 affiliate must have an active subscription.
1383 A single letter flag which the site administrator must set for the
1384 affiliate page to be displayed for the given member.
1388 If this is set then affiliate.pl will set the named cookie to the
1393 This is a comma-separated list of other cookies that should be set by
1394 the a_set target. The values for the cookies should be passed to the
1395 a_set target. For example with:
1398 other_cookies=alpha,beta
1402 http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3
1404 is accessed, then the cookie alpha is set to "1", beta is set to "2".
1405 The cookie gamma will not be set since it's not listed.
1409 Used as the link base URL for the afflink.tmpl side bar template when
1410 an affiliate id is set. Default: example.com
1414 Used at the text of the link for the afflink.tmpl side bar template
1415 when an affiliate id is set. Default: Your Site.
1419 Used as the link URL for the afflink.tmpl side bar template when an
1420 affiliate id is not set. Default: example.com
1424 Used as the text of the link for the afflink.tmpl side bar template
1425 when an affiliate id is not set. Default: Our site
1429 =head2 [BSE Siteuser Images]
1431 Each key is the id of a member image, with a corresponding [BSE
1432 Siteuser Image I<image_id>] section. The values are ignored.
1434 =head2 [BSE Siteuser Image I<image_id>]
1436 Provides information about a single member image "template".
1442 Short description on the image, like "Logo". Used in error messages.
1446 Longer description of the image. Accessible with the member_image tag.
1456 The minimum and maximum dimensions of the image.
1458 =item widthsmallerror
1460 =item heightsmallerror
1462 =item widthlargeerror
1464 =item heightlargeerror
1466 Error messages displayed in the when the image is outside the
1467 configured dimensions.
1473 Default error messages for the above.
1477 Maximum storage the image can use in bytes. Default: 1000000.
1481 Error message displayed if the image uses too much storage.
1487 Various editor settings.
1493 If this is non-zero the system will attempt to load the configured
1494 thumbnail class, and put thumbnail images on the image manager page
1495 rather than full-size images. Default: off
1499 The name of a perl class that implement's BSE's thumbnail API. At
1500 this point the only class that implements that is BSE::Thumb::Imager,
1501 supplied with BSE. Default: None
1503 =item default_thumbnail
1505 URI to the default thumbnail image. This is presented when the
1506 runtime production of a thumbnail image fails.
1508 =item default_thumbnail_width
1510 =item default_thumbnail_height
1512 Dimensions of the default thumbnail image.
1514 =item default_thumbnail_alt
1516 Alt text for the default thumbnail image.
1518 =item check_modified
1520 If this is true then BSE will check the value of the lastModified
1521 parameter passed against the value in the article. If these don't
1522 match the article isn't saved and is redisplayed with an error
1523 message. This provides simple protection against one user saving
1524 changes over those made by another.
1538 Default values for the thumbimage tag.
1544 Each value is used as the relative or absolute name of a file or
1545 directory to load more configuration data from.
1547 The keywords must remain unique.
1549 Only the [includes] section from bse.cfg itself is used to locate more
1552 If the value references a directory, all files with an extension of
1553 C<.cfg> are read for configuration data.
1555 The order the files are read (which later files overriding older
1566 the entries in [includes] are sorted alphabetically (or rather
1567 asciily), so an entry with key "A" is read before one with key "B",
1568 one with key "01" is read before "02", but key "10" would be read
1573 if an entry is a file then that is read and the values merged.
1577 if an entry is a directory, then that is scanned and the files found
1578 read alphabetically as above.
1584 This is used to configure the error icon displayed next to fields that
1591 URI to the image file.
1597 The width and height of the error icon image.
1601 =head2 [site user flags]
1603 Flags that can be set for site users.
1605 All flag Ids are single letters or digits. Uppercase letters are
1606 reserved for use by BSE internally, leaving lower-case letters and
1607 digits for your own use.
1609 Use the id of the flag as the key, and a description of the flag as
1612 =head2 [article defaults]
1614 =head2 [catalog defaults]
1616 =head2 [product defaults]
1618 These sections contain defaults values for the corresponding article
1621 Each key is the name of a column for the article type.
1623 If an entry is not found in [catalog defaults] then [article defaults]
1626 If an entry is not found in [product defaults] then [article defaults]
1629 These sections are checked B<after> the C<[children of >I<id>C<]> and
1630 C<[level >I<level>C<]> sections.
1632 These defaults are used when creating an article where no value is
1633 supplied, they can also be accessed via the <:default I<name>:> tag.
1635 =head2 [newsletter filters]
1637 Contains C<criteria>I<index> entries starting from C<criteria1>, then
1640 Each entry consists of a filter class name, followed by a ; followed
1641 by data passed to that filter.
1643 ; user the original SQL based filter, configured from
1645 criteria1=BSE::NLFilter::SQL;foo
1647 See the documentation for each filter to configure the filters.
1649 =head2 [Query Groups]
1651 The key of each entry is the numeric identifier of a query group, the
1652 values are the name of the query group. For example:
1657 [query group some name]
1658 sql=select id from site_users where id = ? and name1 like '%some%'
1660 Each entry also has a corresponding [Query Group I<name>] section.
1662 =head2 [query group I<name>]
1664 This section corresponds to an entry in [Query Groups].
1670 This is an SQL statement. One placeholder is required and is passed
1671 the siteuser id (primary key) of the user to be checked. If this
1672 query returns I<any> rows then the user is considered part of the
1677 =head2 [template types]
1679 Each key is a template name, the value is the content type to be used
1680 when displaying the template dynamically.
1682 =head2 [template descriptions]
1684 Each key is a template name, the value is a description used in the
1685 template dropdown for that template.
1689 This section defines CSS class names for BSE's body text link tags.
1690 The key is the tag name, the value is the CSS class to be used.
1692 By default the class used is the same as the name of the tag, but you
1693 can switch this off by adding an entry setting the class to the empty
1694 string, for example:
1696 ; no class attribute for any of the links
1703 You can set p here too to set the class for paragraphs generated as
1704 body text. By default no class is set.
1708 Controls the behaviour of the window displayed by the popimage[] body
1709 text tag. If the Javascript for this has been customized then this
1718 Extra width and height for the window beyond the size of the image.
1719 Default: no extra width or height.
1723 If set to non-zero popimage[] will attempt to centre the popup within
1724 the current window. Default: 0.
1734 This is used to configure the DevHelp::Payments::Inpho module.
1740 If this is set then the test parameters are used instead of the
1745 The URL to process requests through.
1747 Default: https://extranet.inpho.com.au/cc_ssl/process
1751 Inpho supplied user name.
1755 Inpho supplied password.
1759 The URL to process test requests through.
1763 The user to supply to test requests.
1767 The password to supply to test requests.
1773 This section controls whether some custom class methods are called:
1779 If this is non-zero then siteuser_saveopts is called.
1783 =head2 [levelI<level> menus]
1785 Where I<level> is the article level at which the defined menu options will be available.
1786 Configure each menu value and description as I<key> and I<value>.
1797 To create a menus using such values, use the "allkids_of" iterator "filter" option.
1801 <:iterator begin allkids_of -1 filter: [menu] == 2 :>
1805 =head2 [title alias]
1807 Enable the "titleAlias" article field and set which level it will be available.
1813 Where I<level> is the article "level" for which the "titleAlias" field should be enabled. To enable
1814 set the value to non-zero.
1821 The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
1822 for space critical iterated menus. A template conditional can be used to display the "titleAlias"
1823 in place of the article "title" when appropriate.
1827 =head2 [thumb geometries]
1829 Each key represents a geometry identifier for use by the thumbimage[],
1830 gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1831 ...:>, <:dthumbimage ...:> template tags.
1833 The key is the geometry identifier, the value is the geometry string
1836 The geometry string consists of:
1846 crop flag - if present
1854 The dimensions can be in any of the following forms:
1860 <width>x<height> - the desired maximum width and height. eg 200x150
1864 <width>x - the desired width, with the height calculated
1865 proportionally based on the source image size
1869 x<height> - the designed height, with the width calculated
1870 proportionally based on the source image size.
1874 <size> - the desired maximum size in both directions. so "200" is
1875 equivalent to "200x200"
1879 The crop flag is a single letter "c", if present then the image should
1880 be scaled so the smaller dimension matches the requested size, and the
1881 longer dimension will be cropped to fit.
1883 The fill if present is: fill(color) where color is a color recognized
1884 by the underlying graphics implementation. This should be at least
1885 hex web colors without the #, eg fill(FF0000) will fill with red.
1887 =head2 [thumb classes]
1889 Each key represents a geometry identifier for use by the thumbimage[],
1890 gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
1891 ...:>, <:dthumbimage ...:> template tags.
1893 The value is used as the class for the generated img tag.
1897 Each value represents a handler or script name for the <:dyntarget
1898 I<script> I<target> ...:> tag.
1900 Each key has a TARGET version and a no-TARGET version, with the key
1901 suffixed with C<_n>.
1903 The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
1904 default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
1906 For other targets the default is
1907 C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
1908 C</cgi-bin/>I<script>C<.pl>.
1910 The string C<TARGET> is replaced with the target specified in the
1913 This, along with dyntarget is intended to allow a more "Web 2.0" type
1914 of access to BSE. eg. you might set:
1920 and have a rewrite rule:
1922 RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
1924 =head2 [popimage class I<classname>]
1926 This defines the settings for a class of images generated by the
1927 popimage[] and gpopimage[] body text markup tags. For example, the
1928 settings for C<popimage[imageid|foo]> can be found in section
1929 C<[popimage class foo]>.
1935 The html generated for this class. Tags of the form
1936 C<{>I<identifier>C<}> are replaced, where I<identifier> can be
1937 C<inline_> or C<outline_> followed by an image field name, for example
1938 C<inline_src> is the URL to the inline image.
1940 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>
1942 The default may be tuned as needed.
1946 The inline image geometry. Default: editor (the value used for
1947 thumbnails on the admin side)
1951 The outline image geometry. If no value is supplied then the original
1952 image values are used.
1956 =head2 [mail resources]
1958 Each key is the identifier of a file that can be attached to
1959 BSE::ComposeMail emails. The value is comma separated filename,
1960 content type, inline status.
1962 The files are searched for through the template search mechanism, so
1963 the filename can be relative to either the master or local templates
1966 If the content type is not supplied, if the filename end in gif, png
1967 or jpg the appropriate content type is used, otherwise
1968 application/octet-stream.
1970 If the inline status is not supplied then images are considered
1971 inline, and other files arent.
1973 =head2 [shop registration]
1975 Each key represents a message id from attempts to checkout. Except
1976 the all key which covers all cases.
1978 If the C<all> key or the message id key is non-zero then the checkout
1979 page will redirect to registration instead of login if the cart or
1980 configuration requires that the user be logged in.
1982 =head2 [template I<template-name>]
1984 Settings for articles based on a particular template.
1988 =item no_cache_dynamic
1990 Controls whether a cache-control: no-cache header will be produced.
1991 Can be overridden with the A and B article flags. If not set the
1992 value of [article].no_cache_dynamic is used.
1998 Global settings for articles.
2002 =item no_cache_dynamic
2004 Controls whether a cache-control: no-cache header will be produced.
2005 Can be overridden with the A and B article flags or [template
2006 I<template-name>].no_cache_dynamic. If not set the value of
2007 [basic].no_cache_dynamic is used.
2013 For the <:recaptcha:> tag currently only used for fmail.pl.
2017 =item api_public_key
2019 =item api_private_key
2021 The public and private key you receive when you register with reCAPTCHA.
2023 =item error_I<error_code>
2025 Replace the error message for the given I<error_code> where
2026 I<error_code> is the reCAPTCHA error code
2027 (eg. "incorrect-captcha-sol") with dash replaced by underscore.
2031 error_incorrect_captch_sol=VERY BAD INPUT
2035 =head2 [global file metadata]
2037 Each key represents an item of metadata for files attached to
2040 The values are ignored.
2042 For each key, extra information is defined in the [file metadata
2045 =head2 [file metadata I<name>]
2047 Definition for the file metadata item I<name>.
2053 title - descriptive name of the metadata. Defaults to I<name>.
2057 rules - validation rules, separated by ;. Custom rules can be defined
2058 in [file metadata validation].
2062 ro - if non-zero the metadata cannot be modified directly by the admin
2063 (applications can still generate it). Default: writable.
2067 type - the data type of the metadata, any of string, text, enum,
2068 integer, real, image. If this is enum values must be defined and
2069 labels should be. Default: string.
2077 string - single line of text
2081 text - one or more lines of text
2085 integer - whole number
2089 real - number with decimal points
2093 enum - select from a list of possible values.
2103 values - semi-colon separated list of values for this metadata.
2107 labels - semi-colon separated list of labels for the values
2111 help - help html to display for the metadata
2115 data_name - (images only) the key to use to store the image data.
2116 Default: I<name>_data.
2120 width_name - (images only) the key to use to store the image width.
2121 Default: I<name>_width.
2125 height_name - (images only) the key to use to store the image height.
2126 Default: I<name>_height.
2130 cond - a perl expression indicating whether the metadata should be
2131 prompted for, for this file. $file is the file object. Default: 1.
2135 unit - text displayed after the entry box for the metadata. Default:
2136 empty. Useful for including a unit ("pixels") or format help
2141 =head2 [session cleanup]
2143 Controls the processing of the bse_session_clean.pl script.
2149 days - the minimum age in days of sessions to be removed. Default: 30.
2153 per - the number of records to remove per SQL delete request.
2158 count - the number of SQL delete requests to perform, maximum.
2163 optimize - whether to perform a table optimization after deleting
2164 records. Default: 1 (set to 0 to skip optimization)
2168 =head2 [nightly work]
2170 Controls the bse_nightly.pl script.
2176 jobs - a comma separated list of BSE background processes to run when
2177 bse_nightly.pl is run. Default: bse_session_clean
2181 I<other keys> - each key is a sort key, and the value is a single
2182 background task name. This allows add-ons to setup extra tasks
2183 without overwriting each other. The sugessted key format is:
2185 99 - two digit priority - 00 is executed first, 99 last
2186 package-name - name of package the task is for
2187 unique - extra text to make the key unique, if necessary
2193 Parameters controlling where cached information - eg. file upload
2200 class - the BSE::Cache compatible cache class. See the documentation
2201 of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
2207 Database connection parameters. These override the settings in
2208 Constants.pm which are deprecated.
2214 dsn - the DBI dsn used to connect to the database. Default:
2219 user - the logon to the database. Default: $Constants::UN
2223 password - the password for the user. Default: $Constants::PW.
2227 dbopts - a perl expression that should evaluate to a hash reference.
2228 Default: $Constants::DBOPTs, or an empty hashref.
2232 class - the database wrapper class to use. Default: BSE::DB::Mysql.
2233 No other values are currently supported.
2237 =head2 [extra a_config]
2239 Defines extra configuration to be returned from the BSE system
2242 Each key is the keyword in the returned JSON object. If the key
2243 already exists it is not overwritten.
2245 Each value is the name of a section in the BSE configuration. The
2246 strings "{level}", "{generator}", "{parentid}", "{template}" are
2247 replaced with their values from the article that config is being
2253 menu=level{level} menu
2261 menu: { alpha: "One", beta: "Two" }
2263 in the returned configuration
2265 =head2 [cookie names]
2267 This section maps BSE's default cookie names to alternate names. This
2268 can be useful if you have two BSE sites under the same domain and need
2269 to ensure they use different cookies.
2276 =head2 [siteuser updates]
2278 Each key identifies an update specification for userupdate.pl, the
2279 value is a description of the specification.
2281 See L<<[siteuser update I<specid>]>> for the rest of the import
2285 =head2 [siteuser update I<specid>]
2287 Currently contains only a single key:
2293 fields - a semi-colon separated list of fields to import. Must
2294 contain one of C<id> or C<userId> which is used as a key to identify
2295 the user to update. An C<x> entry is a field to ignore. Some fields,
2296 such as C<confirmed> may not appear in this list.
2302 Configuration for BSE's PayPal integration.
2304 It shouldn't be necessary to change any of the URLs.
2310 test - if true, then the PayPal sandbox is used, and the configuration
2311 entries starting in C<test_> are used. If false, PayPal is live, and
2312 configuration entries starting in C<live_> are used. Default: 1.
2316 test_api_username, test_api_password, test_api_signature - API
2317 credentials for test mode. Required in test mode.
2321 live_api_username, live_api_password, live_api_signature - API
2322 credentials for live mode. Required for live mode.
2326 test_ws_url - URL to make NVP requests through in test mode. Default:
2327 https://api-3t.sandbox.paypal.com/nvp
2331 test_refresh_url - PayPal URL to refresh to in test mode. Default:
2332 https://www.sandbox.paypal.com/webscr
2336 live_ws_url - URL to make NVP requests through in live mode. Default:
2337 https://api-3t.paypal.com/nvp
2341 live_refresh_url - PayPal URL to refresh to in live mode. Default:
2342 https://www.paypal.com/cgibin/webscr
2346 =head2 [paypal custom]
2348 Extra parameters supplied to the SetExpressCheckout API. See the
2349 Express Checkout Advanced Features Guide (from PayPal) for details.
2351 Some settings that may be useful:
2357 PAGESTYLE - the style of payment page to use from those listed in your
2362 HDRIMG - https URL to an image to use in the payment page header.
2366 HDRBACKCOLOR - a 6 hex digit color to use as the background of the
2367 payment page header.
2371 HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
2372 payment page header.
2382 mail - if non-zero any emails sent through BSE::ComposeMail are logged
2383 in the audit log. Default: 0.
2387 mail_max_dump - if non-zero this is the size limit of the dump stored
2388 in the audit log when [audit log].mail is enabled.
2392 =head2 [audit log I<facility>]
2394 Most commonly C<[audit log bse]>. Controls whether given events or
2395 families of events are logged.
2403 =item I<component>C<:>I<module>
2405 =item I<component>C<:>I<module>C<:>I<function>
2409 with the longer keys overriding the shorter keys, and defaulting to
2410 all actions being logged.
2412 =head2 [mail audit log]
2414 This enables sent when an event is logged in the audit log. Warning:
2415 for common events this will result in large amounts of email.
2421 to - the email address to send the email to
2425 emerg, alert, crit, error, warning, notice, info, debug - if present
2426 and true then events at these levels result in an email. If the value
2427 contains an C<@> then the value is used as the recipient address.
2431 I<facility>-I<component>
2435 I<facility>-I<component>-I<module>
2439 I<facility>-I<component>-I<module>-I<function>
2441 Controls sending an email for specific events or families of events.
2442 If the value is true, send an email for that event. If the value
2443 contains an C<@> then the value is used as the recipient address.
2447 with the longer keys overriding the shorter keys, and defaulting to
2448 all actions being logged.
2452 Contains options to pass to HTML::Tidy. Anything not listed below is
2453 passed directly to HTML::Tidy->new.
2459 ignore_types - types of message to ignore separated by commas, any,
2460 all or none of info, warning, error.
2464 ignore_text_I<key> - messages to ignore, I<key> is not used, just the
2470 =head2 [email I<token>]
2472 Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
2478 template - plain text template
2482 html_template - HTML template (defaults to the value of I<template>
2483 followed by C<_html>
2487 subject - subject of the email, can be overridden with the
2492 from - from email address, defaults to the shop from address
2496 from_name - from name
2500 allow_html - controls whether HTML is allowed. By default this is
2501 based on the user's settings.
2507 Tony Cook <tony@develop-help.com>