CGI::Application and CPAN

Chapter 11 - CGI Application Modules for CPAN
by?Sam Tregar?
Apress ? 2002
Companion Web Site

Now that you know how to build reusable applications using CGI::Application, you're ready to learn to release your creations on CPAN. But first, I should address a burning question that's likely on your mind—why release CGI applications on CPAN? To me the answer is simple: because it will help reduce the needless work that Perl CGI programmers do every day. The Web is filled with endless incarnations of the same applications done and redone—bulletin boards, Web counters, shopping carts, and so on. Each one needs to be done again and again primarily because they need to look or function slightly differently.

Since most CGIs include their HTML inline with their code, either by including it in the source or including the source in the HTML (that is, HTML::Mason or EmbPerl), it is unusual to be able to reuse applications across projects. Furthermore, since most CGIs are built as scripts, the only way to reuse them is to copy them from project to project. With CGI::Application comes the opportunity for the Perl community to pool its collective strength and create powerful, configurable, reusable Web applications. And after all, isn't reusability what CPAN is all about?

Okay, enough manifesto, let's get down to the mechanics.

Size and Shape

A good CGI::Application module has to be the right size and shape; otherwise, it won't fit into the large variety of Web sites on the Internet. What I mean is that an ideal module should be sized to serve a clear and defined purpose within the larger scheme of a site. And it should be shaped to fill several screens without requiring a great deal of overlap with the rest of the site. For example, the BBS application discussed earlier would make a good CPAN module (if it actually worked and had a better name like, say, CGI::Application::BBS). It is clearly a separate application within a larger site that can safely control its own screens.

An example of a CGI project that wouldn't make an ideal module might be a search application. Typically search functionality is tightly integrated into the underlying data and user interface of a Web site. It may still be possible to solve this problem with CGI::Application, but the results are unlikely to be usable on other sites.

Configurability

The primary goal of a successful CGI::Application module on CPAN has to be configurability. These applications will live in a varied environment, and their mode of operation has to be flexible. For example, the CGI::Application::MailPage module,^[6] which provides a "mail this page to a friend" application for static HTML documents, is configurable in how it sends mail, what options it offers to its users, and how it accesses the underlying documents. For example, here's a typical instance script used with CGI::Application::MailPage:

 #!/usr/bin/perl use CGI::Application::MailPage; my $mailpage = CGI::Application::MailPage->new(                   PARAMS => { document_root => '/home/httpd',                               smtp_server => 'smtp.foo.org',                               use_page_param => 1,                             }); $mailpage->run(); 

Template Usage

All CGI::Application modules on CPAN will have to use templating of some sort to be widely reusable. Otherwise it would be impossible for the output of the module to be reconfigured to match the look of the site where it is being used. However, this doesn't mean that CGI::Application modules should require users to provide their own templates. The modules should come with a default set with simple HTML formatting. This serves two purposes. First, it provides an example for users to build off of. Second, it allows users to more easily evaluate the module and test its functionality.

One issue does arise in packaging default templates—how will the module find them after installation? Perl doesn't (yet!) support a default template path, so you'll have to do something about it yourself. The technique I used in building CGI::Application::MailPage was to install them in a Perl module path by specifying them as modules using the PM option to WriteMakeFile() in my Makefile.PL:

 WriteMakefile(              'NAME' => 'CGI::Application::MailPage',              'VERSION_FROM' => 'MailPage.pm',              'PM' => {                       'MailPage.pm' => '$(INST_LIBDIR)/MailPage.pm',                       'email.tmpl' => '$(INST_LIBDIR)/MailPage/email.tmpl',                       'form.tmpl' => '$(INST_LIBDIR)/MailPage/form.tmpl',                       'thanks.tmpl' => '$(INST_LIBDIR)/MailPage/thanks.tmpl',                      },              ); 

Then when loading them, I simply added the contents of @INC to HTML::Template's search path for template files (via the path option):

     $template = $self->load_tmpl('CGI/Application/MailPage/form.tmpl',                                  path => [@INC]); 

Another possibility would have been to include the template text directly inside the module file or interactively prompt the user for a template location during module installation.

^[6]I wrote CGI::Application::MailPage as a proof-of concept in building a CGI::Application for CPAN.