Config.pm contains general configuration parameters,
site-specific setup data, and global variables used throughout
the ExSite system.
This file is designed so that it never has to be modified. To set
configuration variables, use an ``exsite.conf'' file, which will be
loaded automatically, overriding the presets below. This file can be
placed in cgi-bin/, or cgi-bin/conf/. Special configuration
routines and functions can be defined in the module myConfig.pm.
use ExSite::Config;
This is required in all ExSite programs. In addition, every program should also include the following first line of executable code:
&exsite_init;
The system defines six global configuration hashes, described below.
These are exported to all programs that use ExSite::Config.
%config%config is used for system constants that do not normally change.
The system constants in %config are read first from the hard-coded
values in Config.pm, and then from the local configuration file
``exsite.conf'', which can override the former values.
Modifications to the site configuration should be made
in exsite.conf, not in Config.pm.
Specific configuration parameters are described in the ExSite Configuration documentation, or in Config.pm.
Any module or other package can read its own configuration file(s) into
%config, by calling: read_exsite_conf().
In a plain CGI setup, %config is re-read on each request, so
configuration changes are picked up immediately. In a persistent perl
setup, %config will remain defined from the previous request, and
you will need to restart your persistent perl to refresh %config.
In a setup with the persistent data store (see %store, below),
ExSite will try to load a cached version of %config from %store
before reparsing the raw config files. To change the configuration,
you will need to reset the %store to force the data to reload.
%share%share is used as a general-purpose shared-memory area for the current
request. %share is cleared on each page request.
The %share hash is used for sharing data between widely separated
modules and routines. The primary difference between %config and
%share is that the former is regarded as persistent (values stay
the same from request to request), while the latter is volatile
(values vary from request to request).
The differences are not especially significant for normal CGI setups,
since %config must be reloaded on each request anyway. But in a
persistent perl or persistent data store configuration, %config may
only be configured once, whereas %share will be cleared and rebuilt
on every request. (If you do not follow this convention, you may have
problems when switching to use persistence.)
%share is cleared every time &exsite_init() is called.
%share will be used to store pointers to the current database and
page objects ($share{DB} and $share{Page}, respectively), plus
any other shareable data placed there by localization routines and
content modules.
%session%session stores semi-persistent data for a particular user. That
is, it remembers data between different page requests, but clears the
data after a certain amount of time has passed with no activity. The
%session hash only holds data for the current user; other sessions'
data are not available. This is a useful mechanism for temporarily
preserving a visitor's state. Sessions last for 1 hour by default,
but are automatically renewed if used. In other words, if no activity
is detected under a session for one hour, the session will be
terminated.
Session management is automatically enabled if you are using the
persistent data store (%store). Actual session records are created
only if data is written to %session, however. That is, there is no
persistent record of a session if nothing is ever written into
%session. The number of session records indicates the number of
users who have session data that is being tracked, not necessarily the
total number of users active on the site.
%session will will automatically be populated with data previously
written to that user's session. (See ExSite::Session for technical
details.) These data include _mtime and _ctime, which are
timestamp values (Unix system times) of the last modification of the
session data, and the creation time of the session.
Warnings:
If persistent storage is not enabled, sessions are not especially
useful, as they will not remember data between requests. However,
there is no harm in reading or writing to %session in this case, and
it will behave as a normal hash variable.
(You can also use %cookie to store semi-persistent data.
%session is more secure, powerful, and reliable if enabled, since
the data is stored on the server, and can store complex structures.
Note that when a session is initiated, the session ID is stored in
%cookie, so both are in fact needed to make proper use of
sessions.)
%cookie%cookie is used for session-like variables that are tracked
client-side rather than server-side. As the name implies, these
variables are stored as cookies in the user's browser. The %cookie
hash automatically acquires all of the relevant cookies, and can be
inspected to view the values of those cookies at any time.
Changing/setting cookie values is also easy; simply assign a new value to a cookie name, eg.
$cookie{name} = $value;
The appropriate HTTP headers will be printed to ensure that the new cookie data is sent to the client browser for storage.
Warnings: Because cookies are stored as simple text strings on the client browser, cookie values should also be simple text strings. Do not store references or objects in cookies.
Because browsers can disregard cookies, and cookies can be manually
deleted or edited at any time, there is no guarantee that cookies will
in fact persist, nor that they will not be tampered with. They are
also transmitted in cleartext, so are vulnerable to snooping. That
means that %cookie is a useful convenience, but not a secure place
for storing data. Sensitive data should be encrypted before being
placed into a cookie. For example:
%store%config stores parameters that do not change,
%store stores data that is regularly modified but needs to be
available to future requests. %store is the underlying mechanism
behind sessions, database caches, and configuration caches.
The persistent data store is optional; by default it is not enabled,
and %store is just a normal hash whose values are cleared on each
request. (Which means that sessions and caches do not store data
beyond the current request.) If the persistent store is enabled (see
the docs for ExSite::Store) you automatically get the benefit of file
caching, database caching, and sessions. You do not need to interact
directly with %store to gain these features; ExSite manages that on
your behalf.
Items can be placed in the store with an expiry time (which can be 0 for no limit). Items past their expiry time are automatically purged from the store.
%msg%msg hash is a simple Internationalization facility. By default
it simply echoes its key back as a value. If you have a language other
than English defined as your default language, however, then it will
attempt to return an appropriate translation of the key instead. By this
means, a line such as:
print $msg{'Hello World'};
will print out the ``Hello World'' message in whatever language the system is defined to use (assuming that an appropriate dictionary is installed).
server_autoconf()This routine attempts to set the various server configuration
parameters (ie. file paths and machine names) automatically, by
inferring them from the server environment. It works for simple
system configurations, but may get confused by unusual server
setups. In the latter case, disable autoconfiguration by setting
server.auto = 0 in your configuration file. You will then need
to specify the various server parameters manually.
Warning: auto-configuration may fail when testing CGI programs from the command line for testing/debugging purposes, because it may infer different paths than the web server uses. If you need to have correct configuration, then either hard-code your configurations in exsite.conf, or set some environment variables on your command line to resemble the server environment. The following environment variables are used for auto-configuration: DOCUMENT_ROOT, SCRIPT_NAME, SCRIPT_FILENAME, HTTPS, HTTP_HOST.
read_exsite_conf()This routine loads configuration values from files. By default
it looks for ``exsite.conf'' files in the conf, ExSite and . directories.
An alternate filename can be given. By default configuration values
are read straight into the root of %config, but a starting key can
be given, eg. &read_exsite_conf("MyModule.conf","MyModule") will
read the values in MyModule.conf into $config{MyModule}{...}.
Configuration files contain parameters and values, separated by ``=''
(with any amount of whitespace around the ``=''. Values extend from the
first non-whitespace character after the ``='', to the end of line.
Simple parameters are placed directly into %config's keys.
Parameters of the form ``a.b.c'' are stored as $config{a}{b}{c}.
Config array references can be created using ``+='' to set the values
in the array.
Example exsite.conf settings:
trim_whitespace = 0
form.style=list
db_ops.new.url = append.cgi
exsite_init()This routine configures ExSite, and performs any local initializations. This routine is called automatically at the start of all generic CGI scripts, and should be called by custom scripts as well.
Local initialization can be done in &myConfig::my_exsite_init,
which is called automatically from here.
exsite_close()Call this at the end of every ExSite program to ensure that files, caches, sessions, etc. are properly flushed.
get_obj()There are a handful of global objects that ExSite commonly works with. The most common are the primary database object, and the current page being constructed. These are normally stored in %share to make them available to all components.
You can use get_obj() to fetch a predefined object safely. That is,
it will return the predefined object if it exists, and it will create
the object if it does not exist.
Example:
my $db = &get_obj('DB');
install_handlers()Handlers allow plug ins or other subsystems to register special business logic that should take precedence over the default logic in certain cases.
The ExSite base system has to do this in a few cases for its content management tables, which have their own logic that differs from the generic database handling. Otherwise, it is expected that most handlers will be site-specific (registered in myConfig::my_handlers() ) or plug-in-specific (registered from the plug-in module in Modules/).