[bse.git] / site / docs / config.pod

=head1 NAME

config.pod - documents BSE configuration file options

=head1 DESCRIPTION

BSE historically used Constants.pm to keep most configuration
information.  The plan is to make sure any new configuration is kept
in bse.cfg, and to slowly move most configuration information into
bse.cfg.

Keeping configuration information in Constants.pm makes it difficult
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.

=head1 CONFIGURATION ENTRIES

=head2 [site]

Contains URL configuration for the site.

=over

=item url

The normal URL for the non-secure parts of the site.

=item secureurl

The secure URL for the shop, products and other portions of the site
that should use SSL.  This isn't checked to make sure it is https.

=item name

Used as the site "name" in a few places.

=item adminurl

If set, this is used as the base URL for accessing the administrative
functions of your site.

=item secureadmin

Ignored if C<adminurl> is set.

If this is true then C<secureurl> is used as the base URL for
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.

=back

=head2 [paths]

Contains various file system paths.

=over

=item downloads

This is where the files uploads with the file wizard are stored.  It
must be writable by the web server user.

=item admin_templates

Directory containing administrative templates.  Note: this is not
completely implemented for now, so assume the default.  Default: admin
directory under $TMPLDIR.

=item 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.  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

Where uploaded images are stored.  This is not yet completely
implemented.  Default: $IMAGEDIR.

=item libraries

Local search path for BSE::Custom, or the class configured by
C<custom_class> in [basic].

=item siteuser_images

Where uploaded siteuser images are stored.  This must be set in the
config file.  The default bse.cfg include an entry to use the current
values of [paths].downloads

=item dynamic_cache

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

The URL to the directory represented by scalecache.  Defaults to
/images/scaled.

=back

=head2 [extensions]

This section is used by the file wizard to map uploaded file
extensions to MIME content types.  This can be used to extend
BSE::FileEditor's internal extension map.  It cannot override that
map.

The key for each entry is the extension, without the leading '.'.

eg.

  xls = application/msexcel

=head2 [templates]

Used for translating symbolic template names into full names under the
template directory.

In each case the default is the name with a C<.tmpl> extension.

=over

=item user/logon

user logon page

=item user/register

user registration page

=back

=head2 [admin templates]

Used for translating the names of administration templates into filenames.

In each case the default is the name with a C<.tmpl> extension.

=over

=item filelist

article file wizard

=item catalog

Catalog editor page.  Default admin/edit_catalog.tmpl

=item 1

=item 2

=item 3

=item 4

=item 5

Article edit pages.  Default admin/edit_<number>.tmpl

=item steps

Step child/parent management page.  Default admin/edit_steps.tmpl

=back

=head2 [html]

Minor html items.

=over

=item charset

The value of the charset keyword when outputting HTML from a script.
Set to the empty string to suppress the charset keyword.  Default:
iso-8859-1.

=item redirect_links

If this is a non-zero number, then all but mailto links are redirected
to C<nuser.pl/redirect> so you can display a diclaimer.  If this
contained alphabetics it's treated as a comma separated list of url
schemes that should be handled via C<nuser.pl/redirect>.  If 0 or not
present, no redirection is done.

The redirect URL includes a hash of the url, title and the redirect
salt to prevent using this mechanism by external sites for cookie
stealing attacks.

=item redirect_salt

The salt used in generating the has for redirect_links.  Default: an
empty string.

=back

=head2 [basic]

=over

=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).  Default: +3h

=item cookie_domain

This overrides the domain value set for cookies.  This is useful if
you allow the site to run under both example.com and www.example.com,
if you set cookie_domain to example.com then a user visiting
www.example.com will still have their cookies when they visit
example.com.

=item cookie_name

This overrides the cookie name used to store the session id.  Default:
sessionid.  This is useful when you have 2 sites under the same
top-level domain, and helps disambiguate the cookie returned by the
browser.

=item minpassword

Minimum password length in characters.  Default: 4.

=item randomdata

Device to read random data from.  This device should not block when it
runs out of entropy.

=item sign

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 link_titles

If this is true then the links to your articles within BSE will be
followed by a / and then by a simplified version of the article title.
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

If this is true then the user/group/permissions database is used to
control access to the system.  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 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 server_auth

Set this to non-zero to enable authentication via server
authentication (usually Basic Authentication.)  You should normally
set this if you set htusers below.  Default: 0 (disabled)

=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 custom_class

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 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 staticajax

If true, the ifAjax and ajax tags will be active for static pages.

=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 static_thumbnails

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 alias_prefix

The prefix applied to articles that use a linkAlias url.  This should
start with a /.

=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 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 default_popupimage

This is the default popup image class for the popimage[] and
gpopimage[] tags.  Default: popup.

=item warn_obsolete

Some obsolete tags will warn to stderr if this is non-zero.  Default:
don't warn.

=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 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 track_uploads

If this is non-zero, and a cache is configured (see [cache]), file
uploads are tracked in entries in the cache.

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.

=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 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 make_userid_cookie

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.

=back

=head2 [mail]

This section controls how BSE sends email.

=over

=item smtp_server

The host or IP address of your mail server.  If this is not set
C<sendmail> will be used instead.  If this is set you must also set
I<helo>.

=item helo

The name that BSE uses to identify itself when sending mail via SMTP.
Required if I<smtp_server> is set.

=item sendmail

The path to the C<sendmail> binary.  Default: /usr/lib/sendmail

=item sendmail_opts

The options supplied to sendmail.  Default: -t -oi

You may want to add the -odq option to this if you want mail queued
rather than sent immediately.

=item set_errors_to_from

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.

=back

=head2 [children of I<id>]

Where I<id> is the identifier for an article.

=over

=item template

the name of the default template for children of the given parent

=item template_dirs

a comma-separated list of extra directories under $TMPLDIR to search
for templates that can be used for children of the given parent article.

=back

=head2 [article I<id>]

Where I<id> is the identifier of an article.

=over

=item template_dirs

A comma-separated list of extra directories under $TMPLDIR to search
for templates that can be used for children of the given parent
article.

=item extra_templates

A comma-separated list of extra templates under $TMPLDIR that can be
used for the given article.

=back

=head2 [level I<level>]

=over

=item template

The default template for this level of article, assuming it hasn't
been set in the [children of I<article id>] section.

=item template_dirs

A comma-separated list of extra directories under $TMPLDIR to search
for templates that can be used for articles at the given I<level>.

=back

=head2 [catalogs]

=over

=item template

The default template for catalogs.

=back

=head2 [products]

=over

=item template

The default template for products.

=item extra_templates

A comma separated list of extra templates that can be used for
products.

=back

=head2 [messages]

This can be used to control translation of error messages.  Each key
has a prefix identifying the module that uses the error, followed by
'/' followed by a specific identifier for the message.

Message parameters, expressed as $I<digit>, are replaced with the
parameters passed to the message.  C<$$> is replaced with C<$>.

Each message identifier below is documented with the id, when it
occurs, the default message, and any parameters.

=over

=item user/needlogon

the user attempted to logon without entering a logon name.  Default:
"Please enter a logon name".  No parameters.

=item user/needpass

the user attempted to logon without entering a password.  Default:
"Please enter your password."  No parameters.

=item user/baduserpass

the user's logon name or password was not found or did not match.
Default: "Invalid user or password".  No parameters.

=item user/notloggedon

the user attempted to logoff while not logged on.  Default: "You
aren't logged on".  No parameters.

=item user/optsoldpass

the user entered a new password on the options page without entering
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]

=over

=item must_be_paid

if non-zero, the order must be marked as paid for before the file can
be downloaded.

=item must_be_filled

if non-zero the order must be marked as filled before the files can be
downloaded.

=item require_logon

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]

Control over confirmation emails.

=over

=item subject

The subject of email confirmation emails.  Default: Subcription
Confirmation.

=item from

The from field for the email.  Default: $SHOP_FROM

=back

=head2 [subscriptions]

Control over subscription messages.

=over

=item from

The from field for the email.  Default: $SHOP_FROM.

=item testname

Default for the "Test Name" field for sending test subscription
messages.

=item testemail

Default for the "Test Email" field for sending test subscription
messages.

=item testtextonly

Set to 1 if you want the "Test Text Only" box checked by default for
sending test subscription messages.

=item testing

Set to 0 to disable display of the test subscription messages portions
of the subscriptions send form.

=item text_link_inline

Set to format links as they appear in the text version of emails.
C<$1> is replaced with the title, C<$2> with the URL and C<$3> with
the index. C<$$> is replaced with '$'. Default: C<$1 [$3]>

=item text_link_list

Set to format links as they appear at the footer of the body text.  If
this is set to the empty string then no list appears. C<$1>, C<$2>,
C<$3>, C<$$> are replaced as for I<text_link_inline> and $n is
replaced with newline.  Default: C<[$3] $2>

=item text_link_list_prefix

A line of text produced above the list of URLs if there is one.
Default: C<----->. $n in this is replaced with newlines.

=back

For example, if the configuration is:

  text_link_inline="$1" ($3)
  text_link_list_prefix=$n$n-------
  text_link_list=($3) "$1"$n  => $2

and the body text is:

  doclink[3]
  link[http://www.example.com/|Example]

the result will be:

  "The Shop" (1)
  "Example" (2)
  
  
  -------
  (1) "The Shop"
    => http://www.yoursite.com/shop/index.html
  (2) "Example"
    => http://www.example.com/

=head2 [search]

=over

=item highlight_partial

If this is true then partial matches will be highlight in search
result excerpts.  Default: True

=item keep_inaccessible

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 DBM::Deep module
be installed.

=back

=head2 [search highlight]

Sets the prefix and suffix used for highlighting matches for different
fields.

These are used by the highlight_result, excerpt, pageTitle, author,
keywords and matchFile tags.

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.

The default prefix is <b>.  The default suffix is </b>.

For example you can do:

  [search highlight]
  body_prefix=<span class="searchfound">
  body_suffix=</span>

=head2 [shop]

=over

=item enabled

Used by some templates to check if the shop is enabled.  Set this to 1
to enable the shop, or 0 to disable it.

=item secureurl_articles

If this is false then shop articles will not use the secureurl as their 
baseurl.  Default: True

=item register_if_files

If true the customer is required to register before checkout if there
are any for sale files attached to products in the cart.  Default: True

=item require_logon

If true the customer is required to be logged on before checkout,
whether or not for sale files are attached to products in the cart.
Default: False.

=item payment_types

A comma-separated list of acceptable payment types.  Default: 0

The possible payment types are:

=over

=item *

0 - the user enters a credit card number, name and expiry date

=item *

1 - the customer will send a cheque

=item *

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]
and [payment type descs] sections.

=item address1

=item address2

=item address3

These are used by various shop templates to present an address that a
cheque payment should be sent to.

=item from

From email address for emails sent by the shop.  Overides $SHOP_FROM
in Constants.pm

=item to_name

To name for emailed orders sent by the shop.  Overrides $SHOP_TO_NAME
in Constants.pm

=item to_email

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
encrypted.  Enabling this disabled acceptance of credit card orders,
and the default for C<payment_types> will become C<1> instead or C<0>.

Please realize that other potentially commercially sensitive
information is being sent in the clear to a central location,
unencrypted.

=item email_order

If true, then the order is email to to_email, possibly with credit
card information included.  Default: $SHOP_EMAIL_ORDER.

=item display_I<field>

Used to translate the stored order field name into a presentation name
suitable for error messages.

=item cardprocessor

The name of a class to load to process credit card transactions online.

Currently this can be either DevHelp::Payments::Test or
DevHelp::Payments::Inpho.

=item crypt_module

Name of the encryption module to use.  Default: $SHOP_CRYPTO.

=item crypt_signing_id

Id of the key to sign the order email with.  If this is non-empty then
the email is signed even if [basic].sign is false.  Default:
$SHOP_SIGNING_ID.

=item crypt_gpg

Path to the GnuPG program.  Default: $SHOP_GPG

=item crypt_passphrase

Passphrase of the key used to sign the email.  Default:
$SHOP_PASSPHRASE.

=item show_card_type

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.

=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 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]

This section can contain extra order validation information, including
specifying required fields, display names and extra validation rules.

=head2 [fields]

=over

=item title_size

The maximum length of the article title field.  Default: 255.  Should
not be set higher than this unless you change the database schema.

=back

=head2 [interest]

Controls the interest.pl script.

=over

=item notify

Email address that is notified of the interest.  Defaults to $SHOP_FROM.

=back

=head2 [debug]

Used for debugging.

=over

=item logon_cookies

When a user logs on, and the site url is different to the secure url
BSE attempts to refresh to the other "side" of the site to set the
same cookie.

BSE does some simple comparisons to attempt to determine whether the
logon form was triggered on the secure side of the site (possibly from
the shop) or on the insecure side.  Since CGI doesn't necessarily give
us all the information required, it's possible it will guess wrong.

Setting this option to 1 will enable debugging information sent to
standard error, which will be sent to the error log on Apache.  This
probably isn't useful on IIS.

=item file_unlink

Reports errors to STDERR (hence to the error log on Apache) if there
is a problem deleting the actual file when an attached file is
removed.

=item mail_encryption

Reports debugging information to standard error while encrypting your
mail.

=item cookies

Reports cookies received from the browser and sent to the browser to
STDERR (hence to the error log on Apache.)

=item dump_session

If nonzero the session hash is dumped to STDERR after it is retrived
from the database.

=item subscription_expiry

If non-zero then subscription expiry date calculations are dumped to
STDERR.

=item jit_dynamic_regen

If non-zero then information about jit_dynamic_regen is sent to
STDERR.

=item ifUserCan

If non-zero then the ifUserCan tag will output some trace information
to STDERR.

=back

=head2 [uri]

Contains various URIs.

This is underused, so don't rely on it yet.

=over

=item cgi

The URI to the CGI directory.  Default: /cgi-bin

=item images

The URI where images are kept.  Default: /images

=item shop

=item articles

=back

=head2 [articles]

This will provide translations from symbolic names to article ids.

Currently this is used for converting article ids in the access
control code, and for looking up the id of the shop.

=head2 [printable type]

If the user supplies a template name to printable.pl then you can use
a different content type by adding an entry to this section.  The key
is the template name, and the value is the full content type.

=head2 [search index scores]

This section is used when generating the search index to override the
default scores for each field in the articles.

The default scores are:

  Field           Score  Notes
  -----           -----  -----
  title             5
  body              3
  keyword           4
  pageTitle         5
  author            4
  summary           0
  description       0    Products only
  product_code      0    Products only
  file_displayName  2    displayName for files
  file_description  2    description for files
  file_notes        1    notes for files

=head2 [article flags]

=head2 [product flags]

=head2 [catalog flags]

Flags that can be set for articles, products and catalogs
respectively.  Note that flags for articles are also visible in
products and catalogs.

All flag Ids are single letters or digits.  Uppercase letters are
reserved for use by BSE internally, leaving lower-case letters and
digits for your own use.

Use the id of the flag as the key, and a description of the flag as
it's value.

=head2 [article uris]

Each key is an article id, the values are base URIs to store the HTML
form of those articles and their children under.

=head2 [protect link]

The keys are ids of articles that shouldn't have their link field
overwritten.  The value should be a true value, but is otherwise
ignored.

=head2 [datadump]

=over

=item to

The recipient for the data dump email sent by datadump.pl. Default:
$DATA_EMAIL.

=item from

the From for the data dump email sent by datadump.pl.  Default:
$SHOP_FROM.

=back

=head2 [site users]

Configuration for site users.

=over

=item nopassword

If this is set to true then no passwords are required during
registration, a confirmation email is sent immediately upon
registration and that confirmation email contains a link the user can
use to manage their details.

This option has some security concerns since it can leave links to the
user's information in the browser history.  This option is not
recommended.

You cannot use this to control access to the shop.

=item require_name1

=item require_name2

=item require_address

=item require_city

=item require_state

=item require_postcode

=item require_telephone

=item require_facsimile

=item require_country

=item require_title

=item require_organization

Set these to true to require the corresponding field during
registration, and to keep it required after modification.  Default:
false.

If you enable any of these, you should enable C<info_on_register> as
well, or modify the registration template to include the given fields.

=item display_I<field name>

Controls how the given field is displayed in error messages.  If you
change the field names on the registration and/or options forms you
should probably change them here too.  Default: internal field name
with the first character converted to upper-case.

=item info_on_register

If this is set then the user info is prompted for during user
registration.  The information still isn't required unless the
appropriate require_I<field> option is set.  Default: false.

=item register_refresh

The default URL to refresh to on completing registration if no r
parameter is supplied.

=item subscribe_all

If this is set then the subcription checkboxes are all checked on
registration by default.  Default: false.

The user will only receive the subscriptions if they leave them checked
and follow the link in the confirmation email.

=item subscribe_I<id>

Where I<id> is the number identifying a subscription.  If this is set
then the subscription checkbox for that subscription will be checked
by default on the registration form.  Default: false.

The user will only receive the subscriptions if they leave it checked
and follow the link in the confirmation email.

You can get the I<id> of a subcription by looking at the Edit link on the
subscriptions management page, the number after "id=" is the id.

=item billing_on_main_opts

If set to zero then user billing options will be managed on a separate
page.  This is controlled by the user/options_base.tmpl template.

=item user_register

If set to zero then users cannot register themselves.  Default: true,
allowing users to register themselves.

=item notify_register

If true then an email is sent when a new user registers on your site.
The email address sent to is the first set of [site
users].notify_register_email, [shop].from or $SHOP_FROM from
Constants.pm

No email is sent if a new user is created from the administration user
interface.

See also: notify_register_email, notify_register_subject.

=item notify_register_email

The email to sent the registration notification too.  See
notify_register above.

=item notify_register_subject

The subject of the notification email sent when a new user registers.
Any {I<field>} is replaced with the given field from the registered
user.  See notify_register above.

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]

=back

=head2 [payment type names]

This section and [payment type descs] are used to configure new
paymeny type ids.

The key is the integer representing the payment type.  The value is
the name used in tags for checking the payment type.

You can also add a description (currently unused) to [payment type
descs].

You should use numbers starting from 10 to avoid conflicts with future
BSE payment types.

=head2 [payment type descs]

See [payment type names].

=head2 [payment type required]

Set the key given by the payment type id to a value of a
comma-separated list of fields required for that payment type.

=head2 [help style I<style-name>]

This type of configuration section is used to set values for a style
of help icon.  Only the C<template> and C<prefix> values are used
directly by the code, the others are used by the default helpicon
templates.

=over

=item prefix

The URI to the help files for this style.  Default: /help/ in style
"user", /admin/help/ in style "admin".

=item template

The template used to produce the icon.  Default: helpicon in style
user, admin/helpicon in style "admin".

=item icon

URI to the help icon image.   Default: /images/admin/help.gif

=item iconwidth

The width of the help icon image.  Default: 16

=item iconheight

The height of the help icon image.  Default: 16

=back

If you just want to change the help icon image for user help icons you
might do:

  [help style user]
  icon=/images/help.gif

=head2 [affiliate]

=over

=item allowed_referer

A semi-colon (;) separated list of referer domains that are allowed to
link to the C<a_set> target of L<affiliate.pl>.

If the user's browser supplies a referer header then it will be
checked against this list.

=item require_referer

If this is set then the C<a_set> target of L<affiliate.pl> will
require that the user's browser supply a Referer header.

=item default_refresh

If no C<r> parameter is supplied to the C<a_set> target of
L<affiliate.pl> then this is used as the default refresh.

Default: the site base url.

=item subscription_required

This is either the numeric or text of a subscription for which the
affiliate must have an active subscription.

=item flag_required

A single letter flag which the site administrator must set for the
affiliate page to be displayed for the given member.

=item set_cookie

If this is set then affiliate.pl will set the named cookie to the
affiliate id.

=item other_cookies

This is a comma-separated list of other cookies that should be set by
the a_set target.  The values for the cookies should be passed to the
a_set target.  For example with:

  [affiliate]
  other_cookies=alpha,beta

if the url:

  http://your.site.com/cgi-bin/affiliate.pl?a_set=1&id=someid&alpha=1&beta=2&gamme=3

is accessed, then the cookie alpha is set to "1", beta is set to "2".
The cookie gamma will not be set since it's not listed.

=item linkbaseurl

Used as the link base URL for the afflink.tmpl side bar template when
an affiliate id is set.  Default: example.com

=item linkbasedesc

Used at the text of the link for the afflink.tmpl side bar template
when an affiliate id is set.  Default: Your Site.

=item linkdefurl

Used as the link URL for the afflink.tmpl side bar template when an
affiliate id is not set.  Default: example.com

=item linkdefdesc

Used as the text of the link for the afflink.tmpl side bar template
when an affiliate id is not set.  Default: Our site

=back

=head2 [BSE Siteuser Images]

Each key is the id of a member image, with a corresponding [BSE
Siteuser Image I<image_id>] section.  The values are ignored.

=head2 [BSE Siteuser Image I<image_id>]

Provides information about a single member image "template".

=over

=item description

Short description on the image, like "Logo".  Used in error messages.

=item help

Longer description of the image.  Accessible with the member_image tag.

=item minwidth

=item minheight

=item maxwidth

=item maxheight

The minimum and maximum dimensions of the image.

=item widthsmallerror

=item heightsmallerror

=item widthlargeerror

=item heightlargeerror

Error messages displayed in the when the image is outside the
configured dimensions.

=item largeerror

=item smallerror

Default error messages for the above.

=item maxspace

Maximum storage the image can use in bytes.  Default: 1000000.

=item spaceerror

Error message displayed if the image uses too much storage.

=back

=head2 [editor]

Various editor settings.

=over

=item allow_thumb

If this is non-zero the system will attempt to load the configured
thumbnail class, and put thumbnail images on the image manager page
rather than full-size images.  Default: off

=item thumbs_class

The name of a perl class that implement's BSE's thumbnail API.  At
this point the only class that implements that is BSE::Thumb::Imager,
supplied with BSE.  Default: None

=item default_thumbnail

URI to the default thumbnail image.  This is presented when the
runtime production of a thumbnail image fails.

=item default_thumbnail_width

=item default_thumbnail_height

Dimensions of the default thumbnail image.

=item default_thumbnail_alt

Alt text for the default thumbnail image.

=item check_modified

If this is true then BSE will check the value of the lastModified
parameter passed against the value in the article.  If these don't
match the article isn't saved and is redisplayed with an error
message.  This provides simple protection against one user saving
changes over those made by another.

=back

=head2 [thumbnails]

=over

=item max_width

=item max_height

=item max_pixels

Default values for the thumbimage tag.

=back

=head2 [includes]

Each value is used as the relative or absolute name of a file or
directory to load more configuration data from.

The keywords must remain unique.

Only the [includes] section from bse.cfg itself is used to locate more
configuration data.

If the value references a directory, all files with an extension of
C<.cfg> are read for configuration data.

The order the files are read (which later files overriding older
files) is:

=over

=item 1.

bse.cfg is read

=item 2.

the entries in [includes] are sorted alphabetically (or rather
asciily), so an entry with key "A" is read before one with key "B",
one with key "01" is read before "02", but key "10" would be read
I<before> key "2".

=item 3.

if an entry is a file then that is read and the values merged.

=item 4.

if an entry is a directory, then that is scanned and the files found
read alphabetically as above.

=back

=head2 [error_img]

This is used to configure the error icon displayed next to fields that
fail validation.

=over

=item image

URI to the image file.

=item width

=item height

The width and height of the error icon image.

=back

=head2 [site user flags]

Flags that can be set for site users.

All flag Ids are single letters or digits.  Uppercase letters are
reserved for use by BSE internally, leaving lower-case letters and
digits for your own use.

Use the id of the flag as the key, and a description of the flag as
it's value.

=head2 [article defaults]

=head2 [catalog defaults]

=head2 [product defaults]

These sections contain defaults values for the corresponding article
types.

Each key is the name of a column for the article type.

If an entry is not found in [catalog defaults] then [article defaults]
is also checked.

If an entry is not found in [product defaults] then [article defaults]
is also checked.

These sections are checked B<after> the C<[children of >I<id>C<]> and
C<[level >I<level>C<]> sections.

These defaults are used when creating an article where no value is
supplied, they can also be accessed via the <:default I<name>:> tag.

=head2 [newsletter filters]

Contains C<criteria>I<index> entries starting from C<criteria1>, then
C<criteria2>, etc.

Each entry consists of a filter class name, followed by a ; followed
by data passed to that filter.

  ; user the original SQL based filter, configured from 
  ; section [foo]
  criteria1=BSE::NLFilter::SQL;foo

See the documentation for each filter to configure the filters.

=head2 [Query Groups]

The key of each entry is the numeric identifier of a query group, the
values are the name of the query group.  For example:

  [query groups]
  1=some name

  [query group some name]
  sql=select id from site_users where id = ? and name1 like '%some%'

Each entry also has a corresponding [Query Group I<name>] section.

=head2 [query group I<name>]

This section corresponds to an entry in [Query Groups].

=over

=item sql

This is an SQL statement.  One placeholder is required and is passed
the siteuser id (primary key) of the user to be checked.  If this
query returns I<any> rows then the user is considered part of the
group.

=back

=head2 [template types]

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.
The key is the tag name, the value is the CSS class to be used.

By default the class used is the same as the name of the tag, but you
can switch this off by adding an entry setting the class to the empty
string, for example:

  ; no class attribute for any of the links
  [body class]
  link=
  poplink=
  doclink=
  popdoclink=

You can set p here too to set the class for paragraphs generated as
body text.  By default no class is set.

=head2 [popimage]

Controls the behaviour of the window displayed by the popimage[] body
text tag.  If the Javascript for this has been customized then this
may not apply.

=over

=item extrawidth

=item extraheight

Extra width and height for the window beyond the size of the image.
Default: no extra width or height.

=item popmiddle

If set to non-zero popimage[] will attempt to centre the popup within
the current window.  Default: 0.

=back

=over

=back

=head2 [inpho]

This is used to configure the DevHelp::Payments::Inpho module.

=over

=item test

If this is set then the test parameters are used instead of the
product values.

=item url

The URL to process requests through.  

Default: https://extranet.inpho.com.au/cc_ssl/process

=item user

Inpho supplied user name.

=item password

Inpho supplied password.

=item test_url

The URL to process test requests through.

=item test_user

The user to supply to test requests.

=item test_password

The password to supply to test requests.

=back

=head2 [custom]

This section controls whether some custom class methods are called:

=over

=item saveopts

If this is non-zero then siteuser_saveopts is called.

=back

=head2 [levelI<level> menus]

Where I<level> is the article level at which the defined menu options will be available.
Configure each menu value and description as I<key> and I<value>.

=over

For example:

  [level1 menus]
  0=Default
  1=Sidebar
  2=Footer

To create a menus using such values, use the "allkids_of" iterator "filter" option.

For example:

  <:iterator begin allkids_of -1 filter: [menu] == 2 :>

=back

=head2 [title alias]

Enable the "titleAlias" article field and set which level it will be available.

=over

=item levelI<level>

Where I<level> is the article "level" for which the "titleAlias" field should be enabled.  To enable
set the value to non-zero.

For example:

  [title alias]
  level1=1

The "titleAlias" can be used as an alternate "short" title for the given article, especially useful
for space critical iterated menus.  A template conditional can be used to display the "titleAlias" 
in place of the article "title" when appropriate.

=back

=head2 [thumb geometries]

Each key represents a geometry identifier for use by the thumbimage[],
gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
...:>, <:dthumbimage ...:> template tags.

The key is the geometry identifier, the value is the geometry string
as follows.

The geometry string consists of:

=over

=item *

dimensions

=item *

crop flag - if present

=item *

optional fill

=back

The dimensions can be in any of the following forms:

=over

=item *

<width>x<height> - the desired maximum width and height. eg 200x150

=item *

<width>x - the desired width, with the height calculated
proportionally based on the source image size

=item *

x<height> - the designed height, with the width calculated
proportionally based on the source image size.

=item *

<size> - the desired maximum size in both directions. so "200" is
equivalent to "200x200"

=back

The crop flag is a single letter "c", if present then the image should
be scaled so the smaller dimension matches the requested size, and the
longer dimension will be cropped to fit.

The fill if present is: fill(color) where color is a color recognized
by the underlying graphics implementation.  This should be at least
hex web colors without the #, eg fill(FF0000) will fill with red.

=head2 [thumb classes]

Each key represents a geometry identifier for use by the thumbimage[],
gthumbimage[] body text tags and the <:thumbimage ...:>, <:gthumbimage
...:>, <:dthumbimage ...:> template tags.

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.

=back

=head1 AUTHOR

Tony Cook <tony@develop-help.com>

=cut