NAME

CAM::App - Web database application framework

SYNOPSIS

use CAM::App;
require "./Config.pm";  # user-edited config hash

my $app = CAM::App->new(Config->new(), CGI->new());
if (!$app->authenticate()) {
  exit;
}
my $tmpl = $app->template("message.tmpl");
my $ans = $app->{cgi}->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();

DESCRIPTION

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.

FUNCTIONS

new config => CONFIGURATION, [cgi => CGI], [dbi => DBI], [session => SESSION]

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.

Optional objects will be accepted as arguments; otherwise they will be created as needed.

authenticate

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.

header

Compose and return a CGI header. Returns the empty string if the header has already been printed.

isAllowedHost

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.

getConfig

Returns the configuration hash.

getCGI

Returns the CGI object.

getDBH

Return a DBI handle. This object is created, if one does not already exist, using the parameters from the configuration hash to initialize a DBI object. 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.

getSession

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.

getTemplate FILE, [KEY => VALUE, KEY => VALUE, ...]

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.

getTemplateCache CACHEKEY, FILE, [KEY => VALUE, KEY => VALUE, ...]

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.

getEmailTemplate FILE, [KEY => VALUE, KEY => VALUE, ...]

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.

prefillTemplate TEMPLATE, [KEY => VALUE, KEY => VALUE, ...]

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
- mod_perl => boolean indicating whether the script is in mod_perl mode
- myURL => URL of the current script
- 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;
}

error MSG

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 me 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).

loadModule MODULE

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.

AUTHOR

Chris Dolan, Clotho Advanced Media, chris@clotho.com