Puma::ServerPages::Server - Server object for Puma::ServerPages
use Puma::ServerPages::Config qw( getConfig );
my $config = getConfig();
The Puma::ServerPages::Config package provides a function used by the handler to load configuration information for a page.
getConfig()This function returns a configuration hash generated from the various config.xml files. See the sections below for details on parameters and configuration options.
Puma::ServerPages uses the <serverpages> section of Puma's global configuration file in addition to a number of local .config.xml files to confgigure various elements within the system.
The global config.xml has a <serverpages> section:
<?xml version="1.0" encoding="UTF-8"?>
<puma>
<serverpages>
...
</serverpages>
</puma>
while local .config.xml files only contain the <serverpages> section:
<?xml version="1.0" encoding="UTF-8"?>
<serverpages>
...
</serverpages>
Aside from that difference, all options (unless otherwise specified) can be set in any of the configuration files.
Here's an example of the <serverpages> tag to show the options available for the config.xml files:
<serverpages>
<config cascade="full" file=".config.xml" parent=".."/>
<cookie name="Global30d" expires="+30d"/>
<session Context="user" Location="state" UseCookie="Global30d"
module="Puma::ServerPages::User" prefix="user"/>
<include root="." uri="/" />
<perl libs="/web/lib/perl" />
<psp myName="Ingmar" myCity="Seattle" />
<startscript>
$ENV{PATH} .= ':/usr/local/bin';
</startscript>
<endscript>
print "Copywrong (w) 1929, Gomer Pyle/n";
</endscript>
</serverpages>
The config tag tells the ServerPages system how to process the configuration files.
The optional 'file=' parameter defines the name of the local configuration files within the web path. This parameter should only be used in the global configuration file. The default value is '.config.xml'.
The 'parent=' parameter allows you to specify which config.xml file is to be processed as the parent of the current file. This is similar to an OO inheritance structure. This parameter is meaningless in the global configuration file, and may specify either an absolute or relative path or filename.
The 'cascade=' parameter can have one of the following values: 'off', 'root', 'local', 'on' and 'full'.
cascade=``off'' turns off all processing of files. If it is used in a local .config.xml, it will stop any further processing.
cascade=``root'' will limit the processing to the global configuration file (usually located in /etc/puma/config.xml).
cascade=``local'' will process the global configuration file, the local configuration file and any 'parent=' references. It will not search for ther .config.xml files outside of the current dorectory.
cascade=``on'' (default) is the same as ``local'' except that it looks up the filesystem for the first .config.xml if $ENV{DOCUMENT_ROOT}/$ENV{REQUEST_URI} is the same as the current directory.
cascade=``full'' is the same as ``on'' except that it will look up the filesystem tree even if $ENV{DOCUMENT_ROOT}/$ENV{REQUEST_URI} is different from the current directory.
The cookie tag instructs the ServerPages system to create a cookie on the user's browser with the name and expiry time specified by the 'name=' and 'expires=' parameters. The format of the parameter values is restricted to that specified for the HTTP standard.
The session tag associates a stateful object of type 'module' to the cookie 'UseCookie'. The 'Location' and 'Context' parameter are passed to the stateful object as constructions parameters (see Puma::State::Core(3)) and are exposed to the PSP page by the name stated in 'prefix'. In the above example, that would be $user.
The include tag is used to set the web and filesystem paths that the client and server will use to resolve include tags.
This feature emulates the functionality of the global.asa file that allows you to set an arbitrary root for an 'application' (for lack of a better term).
The 'root' parameters is the location on the filesystem that the <:include/> tag will prepend to any filenames it recieves. If the 'root' parameter is not set, it will revert to the default value obtained from $ENV{DOCUMENT_ROOT}.
The 'root' parameter can also take relative paths. The path will be relative to the configuration (.xml) file and NOT the HTML (.psp) file that is being displayed. Note that setting a relative path in the global config.xml won't work and is a rather lame idea anyhow.
The 'uri' parameter is currently unused but is intended to be prepended to paths for client-side includes. It is particularly useful when the web URI is mapped to be different from the filesystems path - something not uncommon for more complex web sites. It is reserved for future use, but you can reliably use it in your own code. If the 'uri' parameter is not set, it will revert to the default value obtained from $ENV{REQUEST_URI}.
For easy access, $ENV{INCLUDE_ROOT} and $ENV{INCLUDE_URI} are set to the root and uri values taken from the configuration file.
The 'libs' parameter for the <perl/> tag adds a line to the beginning of the script that defines the specified directories to be a part of the Perl library path. The value of the parameter formatted as a whitspace separated list of directories.
In the first incarnation of the ServerPages system, I used the <startscript> tag to set global variables for the .psp pages. This was a good idea until I turned 'use strict' on. It was then that I received all sorts of errors on pages where the variables were undefined (for one reason or another).
The solution to this problem was to set values in a hash where we can use the 'exists' and 'defined' functions to see if the keys existed before working on them. That eventually evolved into this tag.
You may set the parameters for this tag to be anything you want. The example above would be converted to be:
my $psp = {
myName => 'Ingmar',
myCity => 'Seattle'
};
The $psp hash can be accessed anywhere within the .psp page.
The <startscript> tag provides a way for you to insert a bit of Perl that will be run before every page. It is a replacement for ASP's onStart function.
<endscript> works in the same manner as the <startscript> tag except that is is executed fater the script.
<etc> = /etc/puma <webroot> = DOCUMENT_ROOT <uri> = REQUEST_URI <cwd> = PATH_TRANSLATED minus the filename
cascade="off"
Only processes <etc>/config.xml
cascade="root"
Only processes <webroot>/.config.xml and <etc>/config.xml
cascade="local"
Processes <cwd>/.config.xml and all 'parent' references, then same as
"root". Will not search path for another .config.xml if there is none in
<cwd>.
cascade="on" (default)
Same as "local" except that it looks up the fs tree for a .config.xml
when there is not one in <cwd>. It will not search the tree unless
<webroot>/<uri> is not the same as <cwd>.
cascade="full"
Same as "on" except that it will look up the filesystem tree even if
<webroot>/<uri> is not the same as <cwd>.
file=".config.xml" (default)
Used in the <etc>/config.xml, this sets/changes the name of the
configuration file that this module looks for.
parent="dir" or "file"
Essential for cascading, this directive in the .config.xml files
indicates which parent directory to look in for the next cascading XML
file.
Puma::Config(3)
Copyright (c) 2001, 2002 by Ingmar Ellenberger.
Distributed under The Artistic License. For the text of this license, see http://puma.site42.com/license.psp or read the file LICENSE in the root of the distribution.