CAM::App

"CAM" stands for Clotho Advanced Media, www.clotho.com, which
supported most of the development of this module.  Contact us at
cpan@clotho.com.

Install via the usual:
  perl Makefile.PL
  make
  make test
  make install

This module implements a basic framework for building web database
applications with the CAM libraries.  It is designed to be subclassed
(see SUBCLASSING below) by your software to provide web functionality
with low overhead.  It is intended for the usual Apache, Perl, MySQL,
and Linux environment, but as little as possible is hardcoded for that
idiom (or, when hardcoded, we try to make the pieces overrideable).

External libraries referenced:
  Required:
    CGI
    CAM::Template
  Optional: (NOTE! Some of these have not yet been released to CPAN)
    CGI::Compress::Gzip
    DBI
    CAM::Session
    CAM::SQLManager
    CAM::SQLObject
    CAM::EmailTemplate
    CAM::EmailTemplate::SMTP
    CAM::Template::Cache

This module is released under the GNU Public License v2.  See
"COPYING".

The Perl module CAM::App most closely resembles is CGI::Application. It's
main advantages over that module are:

 * Simplifies DBI connections
 * Prefills templates
 * Integrated with a session manager (CAM::Session)
 * Centralized error handling
 * Simple email sending (via CAM::EmailTemplate)
 * Integrates a very simple configuration mechanism
 * Can auto-compress output HTML

It's main disadvantages vs. CGI::Application are:

 * Doesn't autodetect or support run modes, except via subclassing.
 * Doesn't support HTML::Template
 * Run modes are not necessarily centralized

And features which may or may not be advantages:

 * Can behave as a helper instead of a harness
 * Uses CAM::Template instead of HTML::Template
 * Caller sets up explicitly scripted run modes instead of
   CGI::Application's run modes.  (if you think this is an advantage,
   then CGI::Application really was never an option for you, was it?)

In general, CGI::Application is great for highly-structured web
applications that are easily broken into use modes.  CAM::App is good
for apps that are much more free form, and just need a little help
with organization.


--- TO DO ---

Future versions of CAM::App will hopefully accomplish some of the
following goals (in the order that they interest me today).

* Simplify the use of CAM::Session for authentication
  [This is done in CAM::UserApp, which has not yet been released to
   the public as of this writing.  Email me if you are interested]
* Aid for multilingual support in templates and in-code messages
  (Locale::Maketext?)
* Generalize the template mechanism so other template packages are
  possible
* Extend the integration with CAM::SQLManager and CAM::SQLObject


--- SUBCLASSING ---

There are a few important steps for you to use this library.

1) Although it's not strictly necessary, we HIGHLY recommend starting
with a subclass.  This can be as simple as creating a trivial file
like this in, for example, "MyApp.pm":

   package MyApp;
   use CAM::App;
   our @ISA = qw(CAM::App);
   1;

2) Create a configuration file.  We recommend starting with the
SampleConfig.pm, but you can quite easily build your own from scratch.

   cp example/SampleConfig.pm MyConfig.pm
   edit MyConfig.pm

3) Set up your CGI script to use MyApp and MyConfig.  It should
contain lines something like this.

   use lib qw(.); # or where ever you stored the new .pm file
   use MyApp;
   use MyConfig;
   
   my $app = MyApp->new(config => MyConfig->new());
   $app->authenticate() or $app->error("Login failed");
   my $cgi = $app->getCGI();
   ...
