CGI::Application::Demo - A vehicle to showcase CGI::Application
#!/usr/bin/perl
use strict;
use warnings;
use CGI::Application::Demo;
# -----------------------------------------------
delete @ENV{'BASH_ENV', 'CDPATH', 'ENV', 'IFS', 'PATH', 'SHELL'}; # For security.
CGI::Application::Demo -> new() -> run();
CGI::Application::Demo is a vehicle for the delivery of a sample CGI::Application application, with these components:
This module, CGI::Application::Demo, demonstrates various features available to programs based on CGI::Application:
Class::DBI and Class::DBI::Loader to auto-generate code per database table
HTML::Template style templates
This replaces a CGI object with a lighter-weight CGI::Simple object.
See CGI::Application::Demo::LogDispatchDBI.
Note: Because I use Class::DBI::Loader, which wants a primary key in every table, and I use CGI::Session, I changed the definition of my 'sessions' table from this:
create table sessions
(
id char(32) not null unique,
a_session text not null
);
to this:
create table sessions
(
id char(32) not null primary key, # I.e.: 'unique' => 'primary key'.
a_session text not null # For Oracle, 'text' => 'long'.
);
compared to what's recommended in the CGI::Session docs.
Also, as you add complexity to this code, you may find it necessary to change line 10 of Base.pm from this:
use base 'Class::DBI';
to something like this:
use base $^O eq 'MSWin32' ? 'Class::DBI' : 'Class::DBI::Pg'; # Or 'Class::DBI::Oracle';
The five modules One.pm .. Five.pm have been designed so as to be graduated in complexity from simplistic to complex, to help you probe the preculiarities of a strange environment.
Each module ships with a corresponding config file, instance script and template. Well, actually, One.pm and Two.pm are too simple to warrant their own config files, and One.pm does not even need a template.
In each case, you are advised to examine the code in these modules while reading what follows.
Our plan then becomes:
This just tests your usage of 'use lib ...'.
By commenting this out, or not, you can check you're actually finding the system's CGI.pm, or the one you installed.
Of course you can do this for any module, not just CGI.pm.
When that's working, move on.
One.pmRun via cgi-app-one.cgi.
This adds usage of a module based on CGI::Application, but the module itself has, deliberately, no complexity of its own. It simple display a build-in web page.
When that's working, move on.
Two.pmRun via cgi-app-two.cgi.
This adds:
CGI with CGI::SimpleSee sub cgiapp_get_query().
HTML::Template-style templatesSee sub cgiapp_init() and sub start().
When that's working, move on.
Three.pmRun via cgi-app-three.cgi.
This adds:
CGI::Application::Plugin::Config::ContextHere for the first time we read a config file.
Naturally, you'll need to edit the config file to suit your environment.
When that's working, move on.
Four.pmRun via cgi-app-four.cgi.
This adds:
Now we're testing a more complex config file.
DBIAnd we use those parameters to test a direct connexion to the database.
We use this connexion to display all records in the faculty table, using the CSS's url.
The faculty table has no purpose other than to provide data to be displayed, either via DBI or via Class::DBI.
When that's working, move on.
Five.pmRun via cgi-app-five.cgi.
WARNING
But first a warning. Base.pm is used by both Five.pm and Demo.pm. You must edit line 77 of Base.pm to say either 'cgi-app-five.conf' or 'cgi-app-demo.conf', depending on which module you are testing.
Five.pm adds:
Base.pm, for all table modulesActually, there's only per-table module, Faculty.pm, at this time, but at least you can see how to use a base module to share code across table modules.
faculty table: Faculty.pm
Class::DBI::LoaderThis uses Class::DBI to automatically load a module-per-table. DBIx::Class provides similar features, but I've never used it.
As above, we just display all records in the faculty table.
By now, if successful, you will have tested all the components of Demo.pm, one-by-one.
So, the next step is obvious...
Demo.pmRun via cgi-app-demo.cgi.
This adds
CGI::Application::Plugin::LogDispatchNow we log things to a database table via LogDispatchDBI.pm (below).
CGI::Application::Plugin::SessionNow we use sessions stored in the database via CGI::Session.
Install my module CGI::Session::Driver::oracle, if necessary.
Create.pmThe code to drop tables, create tables, and populate tables is all in this module.
This was a deliberate decision. For example, when everything's up and running, there is no need for your per-table modules such as Faculty.pm to contain code to do with populating tables, especially constant tables (as faculty is in this demo).
Base.pmA module to share code between all per-table modules.
Faculty.pmA module dedicated to a specific table.
LogDispatchDBI.pmA module to customize logging via Log::Dispatch::DBI.
This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.
See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.
CGI::Application-based script: The instance script (see Synopsis) contains 'use CGI::Application::Demo', which causes Perl to load the file /perl/site/lib/CGI/Application/Demo.pm.
At this point the instance script is initialized, in that package CGI::Application::Demo has been loaded. The script has not yet started to run.
This package contains "use base 'CGI::Application'", meaning CGI::Application::Demo is a descendent of CGI::Application. That is, CGI::Application::Demo is-a CGI::Application.
This (CGI::Application::Demo) is what I'll call our application module.
What's confusing is that application modules can declare various hooks (a hook is an alias for a sub) to be run before the sub corresponding to the current run mode. Two of these hooked subs are called cgiapp_init() (hook is 'init'), and cgiapp_prerun() (hook is 'prerun').
Further, a sub prerun_mode() is also available.
None of these 3 sub are called yet, if at all.
Now CGI::Application::Demo -> new() is called, and it does what it has to do.
This is, it initializes a new object of type CGI::Application.
This includes calling the 'init' hook (sub cgiapp_init() ) and sub setup(), if any.
Since we did in fact declare a sub cgiapp_init() (hook is 'init'), that gets called, and since we also declared a sub setup(), that then gets called too.
You can see the call to setup() at the very end of CGI::Application's sub new().
Oh, BTW, during the call to cgiapp_init, there was a call to sub setup_db_interface(), which, via the magic of Class::DBI::Loader, tucks away an array ref of a list of classes, one per database table, in the statement $self -> param(cgi_app_demo_classes => $classes), and an array ref of a list of table names in the statement $self -> param(cgi_app_demo_tables => $tables).
Now CGI::Application::Demo -> run() is called.
First, this calls our sub cgiapp_get_query() via a call to sub query(), which we declared in order to use a light-weight object of type CGI::Simple, rather than an object of type CGI.
Then, eventually, our application module's run mode sub is called, which defaults to sub start().
So, sub start() is called, and it does whatever we told it to do. The app is up and running, finally.
This list has been moved into a separate document:
http://savage.net.au/Perl-modules/html/modules-for-a-new-pc.html
Unpack the distro, and you'll see various directories to be moved to where your web server can find them.
These are CGI scripts.
These are config files.
This is the one CSS file.
These are the templates.
Now you may have to edit a line or two in some files.
I realise all this seems to be a bit of an effort, but once you appreciate the value of such configuation options, you'll adopt them as enthusiastically as I have done. And you only do this once.
Here I just list the lines you should at least consider editing. Similar comments apply to all *.conf and *.pm files.
css_url=/css/cgi-app-demo/cgi-app-demo.css
dsn=dbi:mysql:cgi_app_demo, username and password
session_driver=driver:Oracle
tmpl_path=/apache2/htdocs/templates/cgi-app-demo/
my($config_file) = ...;
my($config_file) = ...;
Patch the 'use lib' line if you've installed your modules in a non-standard location.
Patch, if necessary:
my($config_file) = "$ENV{'ASSETS'}/conf/cgi-app-demo/cgi-app-demo.conf";
In these, you need to set the environment variables (which are not used by *.cgi):
Lastly, cd $distro/scripts/ and create and populate the database:
Now test http://127.0.0.1/cgi-bin/cgi-app-demo/cgi-app-lib.cgi, and each of cgi-app-(one,two,three,four,five).cgi in turn.
Finally, point your web client at http://127.0.0.1/cgi-bin/cgi-app-demo/cgi-app-demo.cgi and see what happens.
HTML::Entities In general, a CGI::Application-type app could be outputting any type of data whatsoever, and will need to protect that data by encoding it appropriately. For instance, we want to stop arbitrary data being interpreted as HTML.
The sub HTML::Entities::encode_entities() is designed for precisely this purpose. See that module's docs for details.
Now, in order to call that sub from within a double-quoted string, we need some sort of interpolation facility. Hence the module HTML::Entities::Interpolate. See its docs for details.
This demo does not yet need or use HTML::Entities::Interpolate.
I've tested these modules in these environments:
I drew significant inspiration from code in the CGI::Application::Plugin::BREAD project:
http://charlotte.pm.org/kwiki/index.cgi?BreadProject
I used those ideas to write my own bakermaker, the soon-to-be-released (Dec '05) DBIx::Admin.
In fact, the current module is a cut-down version of DBIx::Admin.
CGI::Application::Demo was written by Ron Savage <ron@savage.net.au> in 2005.
Home page: http://savage.net.au/index.html
Australian copyright (c) 2005, Ron Savage. All rights reserved.
All Programs of mine are 'OSI Certified Open Source Software';
you can redistribute them and/or modify them under the terms of
The Artistic License, a copy of which is available at:
http://www.opensource.org/licenses/index.html
