CAM::App - Web database application framework
Directly instantiate this module:
use CAM::App;
require "./Config.pm"; # user-edited config hash
my $app = CAM::App->new(Config->new(), CGI->new());
$app->authenticate() or $app->error("Login failed");
my $tmpl = $app->template("message.tmpl");
my $ans = $app->getCGI()->param('ans');
if (!$ans) {
$tmpl->addParams(msg => "What is your favorite color?");
} elsif ($ans eq "blue") {
$tmpl->addParams(msg => "Very good.");
} else {
$tmpl->addParams(msg => "AIIEEEEE!");
}
$tmpl->print();
Subclass this module, create overridden methods (then use just like above):
package my::App;
use CAM::App;
@ISA = qw(CAM::App);
sub init {
my $self = shift;
$self->{config}->{cgidir} = ".";
$self->{config}->{basedir} = "..";
$self->{config}->{htmldir} = "../html";
$self->{config}->{templatedir} = "../tmpls";
$self->{config}->{libdir} = "../lib";
$self->{config}->{sqldir} = "../lib/sql";
$self->{config}->{error_template} = "error_tmpl.html";
$self->addDB("App", "live", "dbi:mysql:database=app", "me", "mypass");
$self->addDB("App", "dev", "dbi:mysql:database=appdev", "me", "mypass");
return $self->SUPER::init();
}
sub authenticate {
my $self = shift;
return(($self->getCGI()->param('passwd') || "") eq "secret");
}
sub selectDB {
my ($self, $params) = @_;
my $key = $self->{config}->{myURL} =~ m,^http://dev\.foo\.com/, ?
"dev" : "live";
return @{$params->{$key}};
}
CAM::App is a framework for web-based, database-driven applications. This package abstracts away a lot of the tedious interaction with the application configuration state. It is quite generic, and is designed to be subclassed with more specific functions overriding its behavior.
CAM::App relies on a few configuration variables set externally to achieve full functionality. All of the following are optional, and the descriptions below explain what will happen if they are not present. The following settings may be used:
These three are all used for session tracking via CAM::Session. New
sessions are created with the getSession() method. The cookiename can
be any alphanumeric string. The sessiontime is the duration of the
cookie in seconds. The sessiontable is the name of a MySQL table
which will store the session data. The structure of this latter table
is described in CAM::Session. The session tracking requires a
database connection (see the database config parameters)
Parameters used to open a database connection. Either dbistr or
dbname and dbhost are used, but not both. If dbistr is
present, it is used verbatim. Otherwise the dbistr is constructed
as either DBI:mysql:database=dbname or
DBI:mysql:database=dbname;host=dbhost (the latter if a dbhost is
present in the configuration). If dbpassword is missing, it is
assumed to be the empty string ("").
An alternative database registration scheme is described in the
addDB() method below.
If this config variable is set, then all EmailTemplate messages will
go out via SMTP through this host. If not set, EmailTemplate will use
the sendmail program on the host computer to send the message.
The directory where CAM::Template and its subclasses look for template
files. If not specified and the template files are not in the current
directory, all of the getTemplate() methods will trigger errors.
The directory where CAM::SQLManager should look for SQL XML files. Without it, CAM::SQLManager will not find its XML files.
The name of a file in the templatedir directory. This template is
used in the error() method (see below for more details).
Create a new application instance. The configuration object must be a hash reference (blessed or unblessed, it doesn't matter). Included in this distibution is the example/SampleConfig.pm module that shows what sort of config data should be passed to this constructor. Otherwise, you can apply configuration parameters by subclassing and overriding the constructor.
Optional objects will be accepted as arguments; otherwise they will be created as needed.
After an object is constructed, this method is called. Subclasses may want to override this method to apply tweaks before calling the superclass initializer. An example:
sub init { my $self = shift; $self->{config}->{sqldir} = "../lib/sql"; return $self->SUPER::init(); }
This init function does the following:
* Sets up some of the basic configuration parameters (myURL, cgidir, cgiurl)
* Creates a new CGI object if one does not exist
* Sets up the DBH object if one exists
* Tells CAM::SQLManager where the sqldir is located if possible
Returns the directory in which this CGI script is located. This can be a class or instance method.
Test the login information, if any. Currently no tests are performed -- this is a no-op. Subclasses may override this method to test login credentials. Even though it's currently trivial, subclass methods should alway include the line:
return undef if (!$self->SUPER::authenticate());
In case the parent authenticate() method adds a test in the future.
Compose and return a CGI header, including the CAM::Session cookie, if
applicable (i.e. if getSession() has been called first). Returns the
empty string if the header has already been printed.
This function is called from authenticate(). Checks the incoming host
and returns false if it should be blocked. Currently no tests are
performed -- this is a no-op. Subclasses may override this behavior.
Returns the configuration hash.
Returns the CGI object.
Return a DBI handle. This object is created, if one does not already exist, using the configuration parameters to initialize a DBI object.
There are two methods for specifying how to open the database
connection: 1) use the dbistr, dbname, dbhost, dbusername,
and dbpassword configuration variables, is set; 2) use the NAME
argument to select from the parameters entered via the addDB() method.
The config variables dbusername and dbpassword are used, along
with either dbistr (if present) or dbname and dbhost.
If no dbistr is specified via config, MySQL is assumed. The DBI
handle is cached in the package for future use. This means that under
mod_perl, the database connection only needs to be opened once.
If NAME is specified, the database definitions entered from addDB()
are searched for a matching name. If one is found, the connection is
established. If the addDB() call specified multiple options, they are
resolved via the selectDB() method, which mey be overridden by
subclasses.
Add a record to the list of available database connections. The NAME
specified here is what you would pass to getDBH() later. The LABEL is
used by selectDB(), if necessary, to choose between database options.
If multiple entries with the same NAME and LABEL are entered, only the
last one is remembered.
Given a data structure of possible database connection parameters,
select one to use for the database. Returns an array with dbistr,
dbusername and dbpassword values, or an empty array on failure.
The incoming data structure is a hash reference where the keys are labels for the various database connection possibilities and the values are array references with three elements: dbistr, dbusername and dbpassword. For example:
{ live => ["dbi:mysql:database=game", "gameuser", "gameon"], internal => ["dbi:mysql:database=game_int", "gameuser", "gameon"], dev => ["dbi:mysql:database=game_dev", "chris", "pass"], }
This default implementation simply picks the first key in alphabetical order. Subclasses will almost certainly want to override this method. For example:
sub selectDB { my ($self, $params) = @_; if ($self->getCGI()->url() =~ m,/dev/, && $params->{dev}) { return @{$params->{dev}}; } elsif ($self->getCGI()->url() =~ /internal/ && $params->{internal}) { return @{$params->{internal}}; } elsif ($params->{live}) { return @{$params->{live}}; } return (); }
Tell other packages to use this new DBH object. This method is called
from init() and getDBH() as needed. This contacts the following
modules, if they are already loaded:
CAM::Session, CAM::SQLManager, and CAM::Template::Cache.
Return a CAM::Session object for this application. If one has not yet been created, make one now. Note! This must be called before the CGI header is printed, if at all.
Creates, prefills and returns a CAM::Template object. The FILE should be the template filename relative to the template directory specified in the Config file.
See the prefillTemplate() method to see which key-value pairs are
preset.
Creates, prefills and returns a CAM::Template::Cache object. The CACHEKEY should be the unique string that identifies the filled template in the database cache.
Creates, prefills and returns a CAM::EmailTemplate object. This is
very similar to the template() method.
If the 'mailhost' config variable is set, this instead uses CAM::EmailTemplate::SMTP.
This fills the search-and-replace list of a template with typical
values (like the base URL, the URL of the script, etc. Usually, it is
just called from withing getTemplate() and related methods, but if you
build your own templates you may want to use this explicitly.
The following value are set (and the order is significant, since later keys can override earlier ones):
- the configuration variables, including:
- myURL => URL of the current script
- cgiurl => URL of the directory containing the current script
- cgidir => directory containing the current script
- many others...
- mod_perl => boolean indicating whether the script is in mod_perl mode
- anything passed as arguments to this method
Subclasses may override this to add more fields to the template. We recommend implementing override methods like this:
sub prefillTemplate {
my $self = shift;
my $template = shift;
$self->SUPER::prefillTemplate($template);
$template->addParams(
myparam => myvalue,
# any other key-value pairs or hashes ...
@_, # add this LAST to override any earlier params
);
return $self;
}
This is a handy repository for non-fatal status messages accumulated
by the application. [Fatal messages can be handled by the error()
method] Applications who use this mechanism frequently may wish to
override prefillTemplate to set something like:
status => join("<br>", $app->getStatusMessages())
so in template HTML you could, for example, display this via
<style> .status { color: red } </style>
...
??status??<div class="status">::status::</div>??status??
Returns the array of messages that had been accumulated by the
application via the addStatusMessage() method.
Clears the array of messages that had been accumulated by the
application via the addStatusMessage() method.
Prints an error message to the browser and exits.
If the 'error_template' configuration parameter is set, then that template is used to display the error. In that case, the error message will be substituted into the ::error:: template variable.
For the sake of your error template HTML layout, use these guidelines:
1) error messages do not end with puncuation
2) error messages might be multiline (with <br> tags, for example)
3) this function prepares the message for HTML display
(like escaping "<" and ">" for example).
Load a perl module, returning a boolean indicating success or failure. Shortcuts are taken if the module is already loaded, or loading has previously failed.
Chris Dolan, Clotho Advanced Media, chris@clotho.com