CGI::Application::Demo - A vehicle to showcase CGI::Application
CGI::Application::Demo
#!/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:
CGI::Application
This module, CGI::Application::Demo, demonstrates various features available to programs based on CGI::Application:
Class::DBI
Class::DBI::Loader
HTML::Template
This replaces a CGI object with a lighter-weight CGI::Simple object.
CGI
CGI::Simple
See CGI::Application::Demo::LogDispatchDBI.
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:
CGI::Session
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.
CGI.pm
Of course you can do this for any module, not just CGI.pm.
When that's working, move on.
One.pm
Run 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.
Two.pm
Run via cgi-app-two.cgi.
This adds:
See sub cgiapp_get_query().
sub cgiapp_get_query()
See sub cgiapp_init() and sub start().
sub cgiapp_init()
sub start()
Three.pm
Run via cgi-app-three.cgi.
CGI::Application::Plugin::Config::Context
Here for the first time we read a config file.
Naturally, you'll need to edit the config file to suit your environment.
Four.pm
Run via cgi-app-four.cgi.
Now we're testing a more complex config file.
DBI
And 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.
faculty
The faculty table has no purpose other than to provide data to be displayed, either via DBI or via Class::DBI.
Five.pm
Run 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.
Base.pm
Demo.pm
Five.pm adds:
Actually, 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.pm
This uses Class::DBI to automatically load a module-per-table. DBIx::Class provides similar features, but I've never used it.
DBIx::Class
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...
Run via cgi-app-demo.cgi.
This adds
CGI::Application::Plugin::LogDispatch
Now we log things to a database table via LogDispatchDBI.pm (below).
LogDispatchDBI.pm
CGI::Application::Plugin::Session
Now we use sessions stored in the database via CGI::Session.
Install my module CGI::Session::Driver::oracle, if necessary.
CGI::Session::Driver::oracle
Create.pm
The 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).
A module to share code between all per-table modules.
A module dedicated to a specific table.
A module to customize logging via Log::Dispatch::DBI.
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.
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) = ...;
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:
And finish off with...
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.
HTML::Entities::encode_entities()
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.
HTML::Entities::Interpolate
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:
CGI::Application::Plugin::BREAD
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.
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
To install CGI::Application::Demo, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Application::Demo
CPAN shell
perl -MCPAN -e shell install CGI::Application::Demo
For more information on module installation, please visit the detailed CPAN module installation guide.