server_autoconf()
- autoconfigure ExSiteread_exsite_conf()
- load config parameters from a fileexsite_init()
- generic ExSite initialization routineexsite_close()
- clean uppage_header($title)
- standard top-of-page HTMLpage_footer()
- standard end-of-page HTMLinstall_handlers()
- register handlers
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. Handlers and custom setup routines can be defined in the module myConfig.pm.
use ExSite::Config;
In addition, every program should also include the following first line of executable code:
&exsite_init;
All system parameters are stored in one of three configuration hashes, which are exported automatically to every program that uses Config.pm:
%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: &ExSite::Config::read_exsite_conf()
.
%share
%share
is used for per-request constants that need to be remembered
or shared by modules on a given page request. These are 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 significant for normal CGI setups, since %config
must be reconfigured on each request anyway. But in a mod_perl setup,
%config
may only be configured once at server startup, whereas
%share
will be cleared and rebuilt on every request. It is good
practice to follow this convention, to ease the transition to a mod_perl
setup, when it comes.
%share
is empty when initialized by default, and 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
is used for session constants that need to be remembered
for short times between page requests, but not for extended periods. These
are cleared periodically (typically after 1 hour of idle time).
The %session
hash stores semi-persistent data. That is, it
remembers data between different page requests, but clears the data
after a certain amount of time has passed. It is a useful mechanism
for temporarily preserving state. By default, session data is stored
for a maximum of 1 hour if no page requests renew the session, or 24
hours if the session is continually renewed. After this time, the
session will be closed, and a new one will have to be opened.
If session management is enabled on a particular installation of ExSite,
then %session will automatically be filled with the current session data.
(See ExSite::Session
for technical details.) These data include
_atime
and _ctime
, which are timestamp values (Unix system times)
of the last access, and the creation time of the session. If session
management is not enabled, then the contents of %session are undefined
(but will probably be blank in a conventional CGI setup).
Warning: session management is not enabled by default in the
standard ExSite distribution. In this case, %session
will be cleared
on each page request, like %share
.
server_autoconf()
- autoconfigure ExSiteThis routine attempts to set the various server configuration parameters (ie. file paths and machine names) automatically, by inferring them from the server environment.
WARNING: auto-configuration will probably fail when testing CGI programs from the command line for testing/debugging purposes. 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()
- load config parameters from a fileThis 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()
- generic ExSite initialization routineThis 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. Note that my_exsite_init()
is called on every initialization, so it should try to avoid
reconfiguring static configurations (eg. handler registration) on
every pass.
exsite_close()
- clean up
page_header($title)
- standard top-of-page HTMLOutputs the standard HTML to begin an ExSite administration page (eg. a control panel). Optionally, a page title can be provided.
Invokes &myConfig::my_page_header
, which should contain any
localized code for generating locally customized page headers.
page_footer()
- standard end-of-page HTMLOutputs the standard HTML to end an ExSite administration page.
Invokes &myConfig::my_page_footer
, which should contain any
localized code for generating the page footer.
install_handlers()
- register handlersHandlers 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 ExSite::Modules).