to perform upgrades and makes it impossible to use tools such as
mod_perl, at least if you want more than one site on the machine.
+F<bse.cfg> is read as a utf-8 encoded file.
+
=head1 CONFIGURATION ENTRIES
=head2 [site]
accessing the administrative functions of your site, otherwise C<url>
is used as the base URL. Default: false (C<url>'s value is used)
+=item forward_from
+
+Configure the IP address of one or more front-end proxies. This can
+be a regular expression except that C<.> is translated to C<\.> and
+C<*> is tranlated to C<.*> to give more glob() like matching.
+
+If the reqesting host matches then admin site URL matching is done
+against HTTP_X_FORWARDED_SERVER instead of SERVER_NAME.
+
+Default: no front-end server configured.
+
+=item secret
+
+A secret used (currently) for hashing cookie values passed between the
+secure and non-secure parts of the site. This must be set. A
+suitable value can be created with:
+
+ openssl rand -base64 32
+
=back
=head2 [paths]
=item templates
-Directory base for most templates.
+Directory base for most templates. This can contain references like
+$(section/key) to other configuration entries. Split on the systems
+PATH separators (run: perl -V:path_sep)
=item local_templates
Local Directory base for templates. This is searched before the
-templates directory.
+templates directory. This can contain references like $(section/key)
+to other configuration entries. Split on the system's PATH separator.
+
+=item public_html
+
+Web server document root. Static pages are generated under this
+directory. Default: $CONTENTBASE.
=item images
Local search path for BSE::Custom, or the class configured by
C<custom_class> in [basic].
+=item scalecache
+
+The directory where cached versions of scaled thumbnails are stored.
+Defaults to I<[paths].images>F</scaled>. This must be in the document tree. If
+you set this you should also set I<[uri].scalecache>.
+
=item siteuser_images
Where uploaded siteuser images are stored. This must be set in the
Pregenerated dynamic article pages are stored here. This must be
defined if you site contains any dynamicly generated pages.
-=item scalecache
-
-The directory where cached versions of scaled thumbnails are stored.
-Defaults to image_dir/scaled. This must be in the document tree. If
-you set this you should also set scalecacheurl.
-
-=item scalecacheurl
+=item public_files
-The URL to the directory represented by scalecache. Defaults to
-/images/scaled.
+The directory to store public BSE::TB::File content in (currently used
+for application specific files.)
=back
Catalog editor page. Default admin/edit_catalog.tmpl
-=item 1
+=item Z<>1
-=item 2
+=item Z<>2
-=item 3
+=item Z<>3
-=item 4
+=item Z<>4
-=item 5
+=item Z<>5
Article edit pages. Default admin/edit_<number>.tmpl
The salt used in generating the has for redirect_links. Default: an
empty string.
+=item validate
+
+If non-zero then any HTML output is validated with HTML::Tidy.
+Validation errors and warnings are sent to the audit log. See [html
+tidy].
+
+=item tagformat
+
+The default tag formatting to use for C<< <:= ... :> >> tags.
+Default: C<html>.
+
+=item formatter_image_class
+
+The default class to use for image[...] tags in body text. Default:
+C<bse_image_inline>.
+
=back
=head2 [basic]
=over
-=item cookie_lifetime
+=item access_control
-The expiry time for cookies. This should be in the form supported by
-CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
-number, and a time character (s - seconds, m - minutes, h - hours, d -
-days, M - months). Default: +3h
+If this is true then the user/group/permissions database is used to
+control access to the system. Default: False.
+
+=item access_filter_parents
+
+If this is true, then the drop-down lists of possible parents on the
+newsletter edit pages are filtered for access control.
+Default: False.
+
+=item access_filter_steps
+
+If this is true, then the drop-down lists of possible stepparents and
+stepchildren on the article edit pages are filtered for access control.
+Default: False.
+
+=item alias_prefix
+
+The prefix applied to articles that use a linkAlias url. This should
+start with a /.
+
+=item alias_recursive
+
+If this is non-zero then the link is formed by the C<alias_prefix>,
+followed by slash (C</>) separated aliases from the ancestors starting
+from the section, followed by the C<alias_suffix>. You may need to
+change your redirect handling if you enable this. Default: Off.
+
+=item alias_suffix
+
+If this is non-zero then the title is cleaned up (all but
+alphanumerics removed) and appended to the alias URL generated.
+
+=item all_dynamic
+
+If true then all articles are treated as dynamic. Default: false.
+
+=item auto_images
+
+By default, if the author doesn't use any image tags, BSE will insert
+any unnamed article images into the body text of an article. You can
+disable this on a per-article basis in the image tool, or disable it
+globally by setting C<auto_images> to 0.
+
+An alternative is to set C<imagePos> in C<[article defaults]> to
+C<xx> which will default articles to not auto-inserting images.
+
+=item cache_templates
+
+If true, BSE will cache compiled templates using the configured BSE
+cache, if any. Depending on the configured cache this may slow things
+down. Default: disabled.
+
+=item cache_templates_locally
+
+If true, BSE will cache compiled templates in memory. This may
+significantly improve performance but may increase memory use.
+Default: disabled.
+
+=item cache_thumbnails
+
+If set to zero the results of the thumbimage/gthumbimage body/template
+tags will not be cached. Default: 1 (caching is enabled).
=item cookie_domain
www.example.com will still have their cookies when they visit
example.com.
+=item cookie_lifetime
+
+The expiry time for cookies. This should be in the form supported by
+CGI.pm for the -expires parameter. Typically you want a plus ('+'), a
+number, and a time character (s - seconds, m - minutes, h - hours, d -
+days, M - months). Set to an empty string for session cookies.
+Default: +3h
+
=item cookie_name
This overrides the cookie name used to store the session id. Default:
top-level domain, and helps disambiguate the cookie returned by the
browser.
-=item minpassword
+=item custom_class
-Minimum password length in characters. Default: 4.
+The name of the custom class for your site. This is currently only
+used for article editing customizations. This class should derive
+from BSE::CustomBase. Default: BSE::Custom.
-=item randomdata
+=item default_popupimage
-Device to read random data from. This device should not block when it
-runs out of entropy.
+This is the default popup image class for the popimage[] and
+gpopimage[] tags. Default: popup.
-=item sign
+=item dynamic_access_filter
-If this is true then the encrypted messages containing the customer's
-credit card number are sent to the shop owner signed. To avoid
-keeping a passphrase and signing key on the server you can set this to
-false (0). This has the effect that anyone could send you an unsigned
-message encrypted with your public key, though this may not be a
-security threat. Default: True.
+If set to 0, dynamic article iterators will no access control filter
+their results. Default: 1.
+
+=item error_not_defined
+
+If non-zero, during dynamic page generation, inserts a message
+explaining which variable is not set, instead of just leaving the tag
+unreplaced. Default: 1.
+
+=item http_only_session
+
+If this is non-zero, the default, the session cookie sent to the
+browser has the C<HttpOnly> attribute set. This can prevent session
+cookie hijacking. Default: 1.
+
+=item htusers
+
+This should be the path to a file to be updated with the list of users
+and crypt() versions of their passwords. If this is set then the
+security system will check for a user set by the browser before
+attempting a form based logon. Default: None.
+
+=item index_file
+
+The name of the file to generate for static articles when the link is
+terminated by "/". Default: C<index.html>.
+
+=item jit_dynamic_pregen
+
+If this is true, then pre-generation for dynamic pages will be delayed
+until the page is displayed to a user. Default: off.
=item link_titles
The aim is to include at least some title information in the URL
without modifying the name of the HTML file. Default: False.
-=item access_control
+=item make_userid_cookie
-If this is true then the user/group/permissions database is used to
-control access to the system. Default: False.
+If this is non-zero, the default, then when the site member logs in, a
+javascript visible cookie, C<userid> will be set that contains the
+login name of the user. BSE's back-end doesn't use this cookie, its
+only use is for Javascript to enable/disable user interface elements.
+Default: 1.
-=item access_filter_steps
+=item minpassword
-If this is true, then the drop-down lists of possible stepparents and
-stepchildren on the article edit pages are filtered for access control.
-Default: False.
+Previously the minimum length of site user passwords in characters.
+You must now set C<length> in C<[siteuser passwords]>.
+
+=item no_cache_dynamic
+
+If non-zero, the default, dynamic responses will include a
+C<Cache-Control: no-cache> header. This can be overridden for
+articles via , article flags, C<[template >
+I<templatename>C<].no_cache_dynamic> and [article].no_cache_dynamic.
+Default: 1.
+
+=item preload_template
+
+Preload the named template, searching the template search part. Any
+text that would normally be produced by the preloaded template is
+ignored. This can be useful for common definitions and variables for
+use in many templates. Default: none.
+
+=item randomdata
+
+Device to read random data from. This device should not block when it
+runs out of entropy.
+
+=item redir_to_alias
+
+If true then page.pl will 301 redirect (Moved Permanently) requests
+for an article by its id to the generated link if the article has a
+link alias. Default: false. Must only be used with use_alias true.
+
+=item secure_session
+
+If this is non-zero then the session cookie sent to the browser has
+the C<Secure> attribute set. This means that the cookie will only be
+visible over https. This is only useful when the only URL the site is
+visited over is a https URL. Default: 0.
=item server_auth
authentication (usually Basic Authentication.) You should normally
set this if you set htusers below. Default: 0 (disabled)
-=item htusers
+=item sign
-This should be the path to a file to be updated with the list of users
-and crypt() versions of their passwords. If this is set then the
-security system will check for a user set by the browser before
-attempting a form based logon. Default: None.
+If this is true then the encrypted messages containing the customer's
+credit card number are sent to the shop owner signed. To avoid
+keeping a passphrase and signing key on the server you can set this to
+false (0). This has the effect that anyone could send you an unsigned
+message encrypted with your public key, though this may not be a
+security threat. Default: True.
-=item custom_class
+=item staticajax
-The name of the custom class for your site. This is currently only
-used for article editing customizations. This class should derive
-from BSE::CustomBase. Default: BSE::Custom.
+If true, the ifAjax and ajax tags will be active for static pages.
-=item jit_dynamic_pregen
+=item static_thumbnails
-If this is true, then pre-generation for dynamic pages will be delayed
-until the page is displayed to a user. Default: off.
+If true and cache_thumbnails is true then thumbnails for the thumbnail
+cache will be generated when a static page is regenerated, and the
+link from the page will link to the image in the cache rather than to
+C<thumb.pl>. Default: 1 (static thumbnails enabled).
-=item staticajax
+=item track_uploads
-If true, the ifAjax and ajax tags will be active for static pages.
+If this is non-zero, and a cache is configured (see [cache]), file
+uploads are tracked in entries in the cache.
-=item cache_thumbnails
+The fileprogress.pl script can be called by Ajax to display file
+upload progress information to the user. The upload state is updated
+a maximum of once a second.
-If set to zero the results of the thumbimage/gthumbimage body/template
-tags will not be cached. Default: 1 (caching is enabled).
+=item use_alias
+
+If this is non-zero then an article with linkAlias set will use an
+alias url instead of the "real" url. You will need to configure a
+RewriteRule or ErrorDocument to page.pl to direct the user to the
+correct URL. Default: 1.
+
+=item warn_obsolete
+
+Some obsolete tags will warn to stderr if this is non-zero. Default:
+don't warn.
=back
If true, we add an Errors-To header set to the same as the From
header. Default: true.
+=item html_system_email
+
+If non-zero then emails sent via the compose mail system that aren't
+being sent to a member record, will be sent as HTML, if the HTML
+template is available.
+
+=item inline_css
+
+If this is C<style> (the default) then use CSS::Inliner to attempt to
+inline CSS in mail if the text "<style" is found in the generated
+HTML.
+
+If this is C<force> then we always attempt to inline CSS.
+
+If this is any other value then don't inline CSS.
+
+=item inline_css_flags
+
+A comma separated list of flags to supply to CSS::Inliner->new().
+Reasonable flags are C<strip_attrs> to strip C<id> and C<class>
+attributes, and C<leave_style> to leave the HTML style block in place.
+
+Default: no flags.
+
+=item inline_css_report
+
+If this is true and CSS inlining fails, log an error to the audit
+log. This is intended for use in debugging and should be disabled in
+production. Default: false (disabled)
+
=back
=head2 [children of I<id>]
their old password. Default: "You need to enter your old password to
change your password". No parameters.
+=item shop/logonrequired
+
+Displayed if the user attempts to checkout when [shop].require_logon
+is true.
+
=back
=head2 [downloads]
if non-zero the user must be registered/logged on to download I<any>
file.
+=item log_downufile
+
+if non-zero, downloads of userfiles will be logged. Default: 0
+
+=item log_downufile_maxage
+
+the maximum age of entries in the user file download log, in days.
+Default: 30.
+
=back
=head2 [confirmations]
If this is true then resulting articles that can't be accessed by the
user are listed in the search results. Default: false.
+=item wordre
+
+The default regular expression used to match words in text during
+indexing. Default: \w+
+
+=item wordre_I<fieldname>
+
+The field specific word match regular expression for the built-in
+search indexer. Default: the value of C<wordre>.
+
+=item indexer
+
+Module used to build the search index. Default: BSE::Index::BSE.
+
+=item index_priority
+
+For C<BSE::Index::BSE>, the optimization priority. The default of
+C<speed> builds the index in memory and is very fast, but can consume
+a lot of memory. Otherwise, set this to C<memory> to reduce memory
+usage.
+
+C<memory> priority index building requires that the C<DBM::Deep>
+module be installed.
+
+=item level
+
+Articles with a higher level than this are indexed as their ancestor.
+Default: C<$SEARCH_LEVEL> which defaults to 5.
+
+=item case_sensitive
+
+Level of case-sensitivity in the search engine. This can be one of:
+
+=over
+
+=item *
+
+C<none> - no case-sensitive searches
+
+=item *
+
+C<context> - case-sensitive if there are any upper-case characters in
+the search string, case-insensitive otherwise.
+
+=item *
+
+C<controlled> - case-sensitive via a query parameter. This is
+currently not supported by the built-in search engie.
+
+=back
+
+Renegerate your search indexes after changing this value. Default:
+context.
+
=back
=head2 [search highlight]
Each field has a prefix and suffix entry. The key is
I<fieldname>_prefix or I<fieldname>_suffix. For file fields this is
-file_I<fieldname}_prefix and file_I<fieldname}_suffix.
+file_I<fieldname>_prefix and file_I<fieldname>_suffix.
The default prefix is <b>. The default suffix is </b>.
[search highlight]
body_prefix=<span class="searchfound">
body_suffix=</span>
+
+The default prefix and suffix can also be redefined:
+
+ [search highlight]
+ prefix=<mark>
+ suffix=</mark>
=head2 [shop]
2 - contact customer for details
+=item *
+
+4 - paypal - see L<paypal.pod>
+
=back
Other types can be added by adding entries to the [payment type names]
To email for emailed orders sent by the shop. Overrides $SHOP_TO_EMAIL
in Constants.pm
+=item bcc_email
+
+BCC email address for order confirmation emails sent to the customer.
+Default: No bcc.
+
=item noencrypt
If this is true then orders sent to you by the shop will not be
If true, request the card type when requesting credit card
information. Default: False.
+=item cart_entry_limit
+
+Maximum number of entries in the cart. This limits the number of
+distinct products (with options) in the cart, not the total
+quantities. Default: Unlimited.
+
+=item currency_code
+
+The shop currency as a 3-letter currency code. Default: AUD.
+Currencies other than "AUD" aren't supported by most of the system.
+
+=item country_code
+
+Set to non-zero if you're using country codes in the order country
+field. If this is set then the delivCountry is supplied as is to
+various parts of the system, otherwise it is translated from a country
+name to a country code. Default: 0.
+
+=item require_fields
+
+A comma separated list of extra fields to require during checkout.
+This is in addition to the usual fields required during checkout.
+Default: none.
+
+=item require_delivery
+
+If true, and the C<need_delivery> CGI parameter is true, treat the
+following delivery fields as required during checkout: delivFirstName,
+delivLastName, delivStreet, delivSuburb, delivPostCode and delivCountry.
+Default: true.
+
+=item require_delivery_fields
+
+If C<require_delivery> is true, and the C<need_delivery> CGI parameter
+is true, add the comma separated fields listed here to the required
+checkout fields list. Default: none.
+
+=back
+
+=head2 [shipping]
+
+=over
+
+=item couriers
+
+A space-separated list of modules under Courier::, e.g. "Fastway::Road
+AustraliaPost::Air". These will be made available as shipping methods
+on the checkout page.
+
+=item quoted
+
+If true then a default "Quote shipping charges later" shipping method
+will be added to the shipping methods list.
+
+=item sourcepostcode
+
+The post code from which products are shipped.
+
+=item fastwayfranchisee
+
+The name of the Fastway franchisee used to ship products from the
+sourcepostcode.
+
+=item fastwayfranchiseecode
+
+The Fastway franchisee code for the customer, if any.
+
=back
=head2 [Shop Order Validation]
If non-zero then the ifUserCan tag will output some trace information
to STDERR.
+=item trace_noimpl
+
+Enables some trace messages from tags that return an ENOIMPL
+exception. This can be useful for tracking down why a tag isn't being
+replaced. This will produce a lot of output during page regeneration.
+
=back
=head2 [uri]
=over
+=item articles
+
=item cgi
The URI to the CGI directory. Default: /cgi-bin
+=item dist_images
+
+The URI where images included with BSE can be found.
+
+This includes images such as F<trans_pixel.gif> and C<admin/error.gif>.
+
+Default: C</images>
+
=item images
-The URI where images are kept. Default: /images
+The URI where managed images are kept which should correspond to
+C<images> in C<[paths]>.
-=item shop
+Default: C</images> (from C<$Constants::IMAGES_URI>)
-=item articles
+=item scalecache
+
+The URL to the directory represented by scalecache. Defaults to
+I<[uri].images>F</scaled>.
+
+=item public_files
+
+The URL to the directory configured as I<[paths].public_files>.
+
+=item shop
=back
=item require_name2
-=item require_address
+=item require_street
-=item require_city
+=item require_suburb
=item require_state
Default: New user {userId} registered
+=item notify_register_customer
+
+If non-zero then email id C<notify_register_customer> will be sent to
+new user on registration. By default this uses template
+user/email_register, subject "Thank you for registering" which can be
+overridden in [email notify_register_customer] or via the
+C<set_subject> tag.
+
+=item notify_register_customer_admin
+
+If non-zero then the behaviour described for
+C<notify_register_customer> will take place when a new member is added
+by an administrator. Defaults to the value of
+C<notify_register_customer>.
+
=back
=head2 [payment type names]
one with key "01" is read before "02", but key "10" would be read
I<before> key "2".
-=item *
+=item 3.
if an entry is a file then that is read and the values merged.
-=item *
+=item 4.
if an entry is a directory, then that is scanned and the files found
read alphabetically as above.
1=some name
[query group some name]
- sql=select id from site_users where id = ? and name1 like '%some%'
+ sql=select id from bse_siteusers where id = ? and name1 like '%some%'
Each entry also has a corresponding [Query Group I<name>] section.
Each key is a template name, the value is the content type to be used
when displaying the template dynamically.
+=head2 [template descriptions]
+
+Each key is a template name, the value is a description used in the
+template dropdown for that template.
+
=head2 [body class]
This section defines CSS class names for BSE's body text link tags.
=back
-=over
-
-=back
-
-=head2 [inpho]
+=head2 [inpho]
This is used to configure the DevHelp::Payments::Inpho module.
The value is used as the class for the generated img tag.
+=head2 [targets]
+
+Each value represents a handler or script name for the <:dyntarget
+I<script> I<target> ...:> tag.
+
+Each key has a TARGET version and a no-TARGET version, with the key
+suffixed with C<_n>.
+
+The default C<nuser> target is C</cgi-bin/nuser.pl/user/TARGET>. The
+default no-target C<nuser> is C</cgi-bin/nuser.pl/user>.
+
+For other targets the default is
+C</cgi-bin/>I<script>C<.pl?a_TARGET=1> and
+C</cgi-bin/>I<script>C<.pl>.
+
+The string C<TARGET> is replaced with the target specified in the
+dyntarget tag.
+
+This, along with dyntarget is intended to allow a more "Web 2.0" type
+of access to BSE. eg. you might set:
+
+ [targets]
+ shop=/xshop/TARGET
+ shop_x=/xshop/
+
+and have a rewrite rule:
+
+ RewriteRule ^/xshop/(.*)$ /cgi-bin/nuser.pl/shop/$1 [PT]
+
+=head2 [popimage class I<classname>]
+
+This defines the settings for a class of images generated by the
+popimage[] and gpopimage[] body text markup tags. For example, the
+settings for C<popimage[imageid|foo]> can be found in section
+C<[popimage class foo]>.
+
+=over
+
+=item html
+
+The html generated for this class. Tags of the form
+C<{>I<identifier>C<}> are replaced, where I<identifier> can be
+C<inline_> or C<outline_> followed by an image field name, for example
+C<inline_src> is the URL to the inline image.
+
+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>
+
+The default may be tuned as needed.
+
+=item inline
+
+The inline image geometry. Default: editor (the value used for
+thumbnails on the admin side)
+
+=item outline
+
+The outline image geometry. If no value is supplied then the original
+image values are used.
+
+=back
+
+=head2 [mail resources]
+
+Each key is the identifier of a file that can be attached to
+BSE::ComposeMail emails. The value is comma separated filename,
+content type, inline status.
+
+The files are searched for through the template search mechanism, so
+the filename can be relative to either the master or local templates
+directories.
+
+If the content type is not supplied, if the filename end in gif, png
+or jpg the appropriate content type is used, otherwise
+application/octet-stream.
+
+If the inline status is not supplied then images are considered
+inline, and other files arent.
+
+=head2 [shop registration]
+
+Each key represents a message id from attempts to checkout. Except
+the all key which covers all cases.
+
+If the C<all> key or the message id key is non-zero then the checkout
+page will redirect to registration instead of login if the cart or
+configuration requires that the user be logged in.
+
+=head2 [template I<template-name>]
+
+Settings for articles based on a particular template.
+
+=over
+
+=item no_cache_dynamic
+
+Controls whether a cache-control: no-cache header will be produced.
+Can be overridden with the A and B article flags. If not set the
+value of [article].no_cache_dynamic is used.
+
+=back
+
+=head2 [article]
+
+Global settings for articles.
+
+=over
+
+=item no_cache_dynamic
+
+Controls whether a cache-control: no-cache header will be produced.
+Can be overridden with the A and B article flags or [template
+I<template-name>].no_cache_dynamic. If not set the value of
+[basic].no_cache_dynamic is used.
+
+=back
+
+=head2 [recaptcha]
+
+For the <:recaptcha:> tag currently only used for fmail.pl.
+
+=over
+
+=item api_public_key
+
+=item api_private_key
+
+The public and private key you receive when you register with reCAPTCHA.
+
+=item error_I<error_code>
+
+Replace the error message for the given I<error_code> where
+I<error_code> is the reCAPTCHA error code
+(eg. "incorrect-captcha-sol") with dash replaced by underscore.
+
+eg.
+
+ error_incorrect_captch_sol=VERY BAD INPUT
+
+=back
+
+=head2 [global file metadata]
+
+Each key represents an item of metadata for files attached to
+articles.
+
+The values are ignored.
+
+For each key, extra information is defined in the [file metadata
+I<name>] section.
+
+=head2 [file metadata I<name>]
+
+Definition for the file metadata item I<name>.
+
+=over
+
+=item *
+
+title - descriptive name of the metadata. Defaults to I<name>.
+
+=item *
+
+rules - validation rules, separated by ;. Custom rules can be defined
+in [file metadata validation].
+
+=item *
+
+ro - if non-zero the metadata cannot be modified directly by the admin
+(applications can still generate it). Default: writable.
+
+=item *
+
+type - the data type of the metadata, any of string, text, enum,
+integer, real, image. If this is enum values must be defined and
+labels should be. Default: string.
+
+The types are:
+
+=over
+
+=item *
+
+string - single line of text
+
+=item *
+
+text - one or more lines of text
+
+=item *
+
+integer - whole number
+
+=item *
+
+real - number with decimal points
+
+=item *
+
+enum - select from a list of possible values.
+
+=item *
+
+image - image file.
+
+=back
+
+=item *
+
+values - semi-colon separated list of values for this metadata.
+
+=item *
+
+labels - semi-colon separated list of labels for the values
+
+=item *
+
+help - help html to display for the metadata
+
+=item *
+
+data_name - (images only) the key to use to store the image data.
+Default: I<name>_data.
+
+=item *
+
+width_name - (images only) the key to use to store the image width.
+Default: I<name>_width.
+
+=item *
+
+height_name - (images only) the key to use to store the image height.
+Default: I<name>_height.
+
+=item *
+
+cond - a perl expression indicating whether the metadata should be
+prompted for, for this file. $file is the file object. Default: 1.
+
+=item *
+
+unit - text displayed after the entry box for the metadata. Default:
+empty. Useful for including a unit ("pixels") or format help
+("hh:mm").
+
+=back
+
+=head2 [session cleanup]
+
+Controls the processing of the bse_session_clean.pl script.
+
+=over
+
+=item *
+
+days - the minimum age in days of sessions to be removed. Default: 30.
+
+=item *
+
+per - the number of records to remove per SQL delete request.
+Default: 1000.
+
+=item *
+
+count - the number of SQL delete requests to perform, maximum.
+Default: 1000.
+
+=item *
+
+optimize - whether to perform a table optimization after deleting
+records. Default: 1 (set to 0 to skip optimization)
+
+=back
+
+=head2 [nightly work]
+
+Controls the bse_nightly.pl script.
+
+=over
+
+=item *
+
+jobs - a comma separated list of BSE background processes to run when
+bse_nightly.pl is run. Default: bse_session_clean
+
+=item *
+
+I<other keys> - each key is a sort key, and the value is a single
+background task name. This allows add-ons to setup extra tasks
+without overwriting each other. The sugessted key format is:
+
+ 99 - two digit priority - 00 is executed first, 99 last
+ package-name - name of package the task is for
+ unique - extra text to make the key unique, if necessary
+
+=back
+
+=head2 [cache]
+
+Parameters controlling where cached information - eg. file upload
+progress is stored.
+
+=over
+
+=item *
+
+class - the BSE::Cache compatible cache class. See the documentation
+of BSE::Cache::Cache, BSE::Cache::CHI or BSE::Cache::Memcached.
+
+=back
+
+=head2 [db]
+
+Database connection parameters. These override the settings in
+Constants.pm which are deprecated.
+
+=over
+
+=item *
+
+dsn - the DBI dsn used to connect to the database. Default:
+$Constants::DSN.
+
+=item *
+
+user - the logon to the database. Default: $Constants::UN
+
+=item *
+
+password - the password for the user. Default: $Constants::PW.
+
+=item *
+
+dbopts - a perl expression that should evaluate to a hash reference.
+Default: $Constants::DBOPTs, or an empty hashref.
+
+=item *
+
+class - the database wrapper class to use. Default: BSE::DB::Mysql.
+No other values are currently supported.
+
+=back
+
+=head2 [extra a_config]
+
+Defines extra configuration to be returned from the BSE system
+configuration.
+
+Each key is the keyword in the returned JSON object. If the key
+already exists it is not overwritten.
+
+Each value is the name of a section in the BSE configuration. The
+strings "{level}", "{generator}", "{parentid}", "{template}" are
+replaced with their values from the article that config is being
+requested for.
+
+So:
+
+ [extra a_config]
+ menu=level{level} menu
+
+ [level1 menu]
+ alpha=One
+ beta=Two
+
+will include:
+
+ menu: { alpha: "One", beta: "Two" }
+
+in the returned configuration
+
+=head2 [cookie names]
+
+This section maps BSE's default cookie names to alternate names. This
+can be useful if you have two BSE sites under the same domain and need
+to ensure they use different cookies.
+
+eg.
+
+ [cookie names]
+ userid=altuserid
+
+=head2 [siteuser updates]
+
+Each key identifies an update specification for userupdate.pl, the
+value is a description of the specification.
+
+See L<< [siteuser update I<specid>] >> for the rest of the import
+specification.
+
+
+=head2 [siteuser update I<specid>]
+
+Currently contains only a single key:
+
+=over
+
+=item *
+
+fields - a semi-colon separated list of fields to import. Must
+contain one of C<id> or C<userId> which is used as a key to identify
+the user to update. An C<x> entry is a field to ignore. Some fields,
+such as C<confirmed> may not appear in this list.
+
+=back
+
+=head2 [paypal]
+
+Configuration for BSE's PayPal integration.
+
+It shouldn't be necessary to change any of the URLs.
+
+=over
+
+=item *
+
+test - if true, then the PayPal sandbox is used, and the configuration
+entries starting in C<test_> are used. If false, PayPal is live, and
+configuration entries starting in C<live_> are used. Default: 1.
+
+=item *
+
+test_api_username, test_api_password, test_api_signature - API
+credentials for test mode. Required in test mode.
+
+=item *
+
+live_api_username, live_api_password, live_api_signature - API
+credentials for live mode. Required for live mode.
+
+=item *
+
+test_ws_url - URL to make NVP requests through in test mode. Default:
+https://api-3t.sandbox.paypal.com/nvp
+
+=item *
+
+test_refresh_url - PayPal URL to refresh to in test mode. Default:
+https://www.sandbox.paypal.com/webscr
+
+=item *
+
+live_ws_url - URL to make NVP requests through in live mode. Default:
+https://api-3t.paypal.com/nvp
+
+=item *
+
+live_refresh_url - PayPal URL to refresh to in live mode. Default:
+https://www.paypal.com/cgibin/webscr
+
+=back
+
+=head2 [paypal custom]
+
+Extra parameters supplied to the SetExpressCheckout API. See the
+Express Checkout Advanced Features Guide (from PayPal) for details.
+
+Some settings that may be useful:
+
+=over
+
+=item *
+
+PAGESTYLE - the style of payment page to use from those listed in your
+account profile.
+
+=item *
+
+HDRIMG - https URL to an image to use in the payment page header.
+
+=item *
+
+HDRBACKCOLOR - a 6 hex digit color to use as the background of the
+payment page header.
+
+=item *
+
+HDRBORDERCOLOR - a 6 hex digit color to use as the border of the
+payment page header.
+
+=back
+
+=head2 [audit log]
+
+=over
+
+=item *
+
+mail - if non-zero any emails sent through BSE::ComposeMail are logged
+in the audit log. Default: 0.
+
+=item *
+
+mail_max_dump - if non-zero this is the size limit of the dump stored
+in the audit log when [audit log].mail is enabled. Default: 50000.
+
+=back
+
+=head2 [audit log I<facility>]
+
+Most commonly C<[audit log bse]>. Controls whether given events or
+families of events are logged.
+
+The key is one of:
+
+=over
+
+=item I<component>
+
+=item I<component>C<:>I<module>
+
+=item I<component>C<:>I<module>C<:>I<function>
+
+=back
+
+with the longer keys overriding the shorter keys, and defaulting to
+all actions being logged.
+
+=head2 [mail audit log]
+
+This enables sent when an event is logged in the audit log. Warning:
+for common events this will result in large amounts of email.
+
+=over
+
+=item *
+
+to - the email address to send the email to
+
+=item *
+
+emerg, alert, crit, error, warning, notice, info, debug - if present
+and true then events at these levels result in an email. If the value
+contains an C<@> then the value is used as the recipient address.
+
+=item *
+
+I<facility>-I<component>
+
+=item *
+
+I<facility>-I<component>-I<module>
+
+=item *
+
+I<facility>-I<component>-I<module>-I<function>
+
+Controls sending an email for specific events or families of events.
+If the value is true, send an email for that event. If the value
+contains an C<@> then the value is used as the recipient address.
+
+=back
+
+with the longer keys overriding the shorter keys, and defaulting to
+all actions being logged.
+
+=head2 [html tidy]
+
+Contains options to pass to HTML::Tidy. Anything not listed below is
+passed directly to HTML::Tidy->new.
+
+=over
+
+=item *
+
+ignore_types - types of message to ignore separated by commas, any,
+all or none of info, warning, error.
+
+=item *
+
+ignore_text_I<key> - messages to ignore, I<key> is not used, just the
+value.
+
+
+=back
+
+=head2 [email I<token>]
+
+Controls emails sent via F<cgi-bin/admin/sendemail.pl>.
+
+=over
+
+=item *
+
+template - plain text template
+
+=item *
+
+html_template - HTML template (defaults to the value of I<template>
+followed by C<_html>
+
+=item *
+
+subject - subject of the email, can be overridden with the
+C<set_subject> tag.
+
+=item *
+
+from - from email address, defaults to the shop from address
+
+=item *
+
+from_name - from name
+
+=item *
+
+allow_html - controls whether HTML is allowed. By default this is
+based on the user's settings.
+
+=back
+
+=head2 [lost password]
+
+=over
+
+=item *
+
+daily_limit - the number of recovery attempts permitted per day.
+Default: 3.
+
+=item *
+
+age_limit - the id included in the email is valid for this many days.
+Default: 7.
+
+=back
+
+=head2 [link replacement]
+
+For formatted text, this is a list of URL prefixes to replace.
+
+The key is a sort key, replacements are checked in alphabetical order.
+
+The value is the original prefix, followed by ";", followed by the
+replacement.
+
+Replacement is performed case-insenitively. Regexp metacharacters
+
+=head2 [article categories]
+
+=over
+
+=item *
+
+ids - a comma separated list of category ids. There are (currently)
+no restrictions on the contents of these ids, but alphanumerics are
+recommended to simplify templates.
+
+=item *
+
+I<id> - a description for a particular category id. Overridden by the
+C<name> key in C<< [article category I<id>] >>. Default: ucfirst of
+the id.
+
+=back
+
+=head2 [article category I<id>]
+
+=over
+
+=item *
+
+name - name of the article category.
+
+=back
+
+Other keys may be used as desired, eg. to make it simpler to configure
+article behaviour based on the category.
+
+=head2 [article menu]
+
+This section can be used to add new menu items to the menu displayed
+on article edit pages.
+
+The keys are used for sorting only.
+
+The value is comma-separated:
+
+=over
+
+=item *
+
+target script name
+
+=item *
+
+target identifier, to be set to 1 on making a request to the script.
+
+=item *
+
+the label for the item in the menu.
+
+=back
+
+eg.
+
+ sample,a_foo,Sample Item
+
+will generate a link like:
+
+ <a href="/cgi-bin/admin/sample.pl?id=10&a_foo=1">Sample Item</a>
+
+where 10 is the id of the article being edited.
+
+Keys with a prefix of C<bse_> are reserved for BSE internal use.
+
+=head2 [undeletable articles]
+
+Keys are the ids of articles that may not be deleted.
+
+This applies if the value of the entry is a true perl value.
+
+ [undeletable articles]
+ 1=home page
+ 2=more home page
+ ; article 3 is deletable
+ 3=
+
+=head2 [dummy shipping methods]
+
+Configures extra shipping methods only selectable from the order
+detail page.
+
+Entries are sorted by value.
+
+If the value contains a comma the text up to the comma is removed and
+the remains used as the label, otherwise the key is used as the label.
+
+=head2 [article custom fields]
+
+=head2 [product custom fields]
+
+=head2 [catalog custom fields]
+
+These can be used to define article, product and catalog custom fields
+respectively, in a similar manner to L<formmail>.
+
+The field names are predefined, C<customDate1>, C<customDate2>,
+C<customInt1>, C<customInt2>, C<customInt3>, C<customInt4>,
+C<customStr1> and C<customStr2>, but are only active if a description
+is defined for the field:
+
+ [article custom fields]
+ customInt1_description=Stock Level
+
+=head2 [siteuser passwords]
+
+Rules for validating (not verifying) site user passwords. Possible
+keys are:
+
+=over
+
+=item *
+
+C<length> - the minimum length of passwords. This replaces
+C<minpassword> in C<[basic]>.
+
+=item *
+
+C<entropy> - the minimum password entropy as measured by
+L<Data::Password::Entropy>.
+
+=item *
+
+C<symbols> - if non-zero, the password must contain non-alphanumerics.
+
+=item *
+
+C<digits> - if non-zero, the password must contain digits.
+
+=item *
+
+C<mixedcase> - if non-zero, the password must contain both upper and
+lower case letters.
+
+=item *
+
+C<categories> - the number of categories out of 5 required out of
+symbols, digits, upper case, lower case and extended ASCII/Unicode.
+This should typically never be 5.
+
+=item *
+
+C<notuser> - the password and user name may not match each other
+case-insensitively.
+
+=item *
+
+C<notu5er> - the password may not match the user name
+case-insensitively, even with symbol replacement (e.g. "5" for "S".
+
+=back
+
+=head2 [admin user passwords]
+
+Rules for validating (not verifying) administrative user passwords.
+See L</[siteuser passwords]> on the keys that can be set.
+
+=head2 [site user lockouts]
+
+Controls when accounts and IP addresses are locked out due to repeated
+site user authentication failures.
+
+=over
+
+=item *
+
+I<account maximum failures> - the maximum number of login failures for
+a given account in I<account time period>. A successful login of the
+account resets the count. Default: 3.
+
+=item *
+
+C<account_time_period> - the number of minutes in which
+C<account_maximum_failures> login failures occurring will cause an
+account lock-out. Default: 10.
+
+=item *
+
+C<account_lockout_time> - the number of minutes to lock out an account
+that fails too many logins. Default: 60.
+
+=item *
+
+C<ip_maximum_failures> - the maximum number of login failures for a
+given IP address with-in C<ip_time_period>. A successful login of any
+account at the IP address resets the count. Default: 10.
+
+=item *
+
+C<ip_time_period> - the number of minutes in which
+C<ip_maximum_failures> login failures occurring causes an IP address
+lock-out. Default: 30.
+
+=item *
+
+C<ip_lockout_time> - the number of minutes to lock out an IP
+address that fails too many logins. Default: 120.
+
+=item *
+
+C<ip_maximum_failures2> - the maximum number of login failures for a
+given IP address with-in C<ip_time_period>. A successful login of any
+account at the IP address I<does not reset> the count. Default: 50.
+
+=item *
+
+C<ip_lockout_time2> - the number of minutes to lock out an IP address
+that fails too many logins against C<ip_maximum_failure2>. Default:
+120.
+
+=back
+
+Note: an administrator unlocking an account resets the account lock
+count but has no effect on the IP address lock count. An
+administrator unlocking an IP address resets both IP address lock
+counts, but has no effect on account lock counts.
+
+=head2 [admin user lockouts]
+
+Control account and IP address lockouts for admin user authentication.
+
+See L</[site user lockouts]> for details of the configuration
+possible.
+
+=head2 [pregenerate]
+
+Defines templates to be generated as base templates.
+
+Each entry is of the form:
+
+=over
+
+I<output-template>=I<profile-name>,I<input-template>
+
+=back
+
+where:
+
+=over
+
+=item *
+
+I<output-template> - the output template name, stored in the directory
+defined by [paths].templates
+
+=item *
+
+I<profile-name> - used to select a section in the config file to load
+dummy article settings from, as C<< [I<profile-name> settings] >>.
+
+=item *
+
+I<input-template> - the source template to generate from.
+
+=back
+
=head1 AUTHOR
Tony Cook <tony@develop-help.com>
projects / bse.git / blobdiff