A Tutorial for CGI::Application

A contact form using HTML::Template

Most Web developers find themselves creating some of the same functionality site after site. The repetition can become tedious—lots of typing, cutting and pasting, and testing—with the same errors popping up.

CGI::Application (C::A), and it's many Plug-in's, was developed to eliminate some of the tedium, helping the developer to more efficiently use their time by solving problems and structuring their applications.

CGI::Application falls under the category of a framework. Frameworks enable developers to use shorter, more readable coding conventions, at least on the surface, that can be performing more complicated, and possibly combined tasks behind it. The result is faster development, more consistent style, and fewer errors, to name but a few. C::A provides an addition model of mapping your Web application to "screens" (forms, etc.) and creating the functions to process by pages.

There are more robust frameworks (with more robust learning curves), like Catalyst and Maypole, and more recently, Jifty, but CGI::Application provides a very approachable, easy-to-use, low overhead framework for Web developers who like working in a less abstracted environment and a little closer to Perl itself.

This tutorial does not cover the installation of CGI::Application, or any of it's growing number of plug-ins, but will show how you can use CGI::Application and HTML::Template to build one of the most common ancillary interactive applications on the Web: a contact form. We will start out with an example that is pure CGI::Application, just to show that it can be done, though not really practical.

Also, this tutorial is not meant as a placement for C::A's well-written POD, which should be required reading.

A Word About HTML::Template

While this is not a tutorial for HTML::Template (H::T) or HTML::FillInForm, the novice Web developer will see an example of how they can all work together with CGI::Application to create more useful, dynamic, and user-friendly applications.

Basic C::A Concepts

1. All C::A applications are invoked by an instance script, which, in test case below, is named index.cgi. One of the advantages of using C::A, is that it encourages "smart" URI's, e.g., http://www.acmecorp.com/contact/ The instance script can be named anything, but this author prefers some__directory/index.cgi to take advantage of the smart URI, and using the .cgi extension, reserving .pl) and .pm for the actual modules.
2. A instance usually passes one run mode, which can be equated to the processing of one screen or Web page. For example, the first run mode might populate and display a form, and the second run mode might validate that form upon submission. If a runmode is not passed, a default run mode can be set at the top of the actual application (more on that in a minute).
3. After the function is run in the application, the application must return something or to something: usually an HTML page through a redirect, or in our case, an H::T template using output.
4. $self, or the object, is passed throughout the application and finally returned at the end. It can be called anything, but $self is common practice in the OO world.

The Layout

The locations of your files will vary depending on your server, e.g., you could be on a shared host and using something like '/usr/home/foobar' and /foobar/public_html/. The salient point is that the C::A applications (server-side) are placed out-of-reach of the public Web directory (client-side).

/opt/foobar/apps/---+
       |            |
       |            |
       |      Foobar_Super.pm
       |            |
       |        Common.pm
       |            |
       |       /Acmecorp/---+
       |                    |
       |                Contact.pm
       |                    |
       |               acmecorp.conf
       |
       |
/var/www/acmecorp/--+   
                    |
                 home.html                    
                    |
                /contact/----+
                    |        |  
                    |     index.cgi
                    |
               /templates/---+     
                    |        |
                    |   contact.tmpl
                    |
              thankyou.html
[download]

Sample Application

CGI::Application, Plugin's, and HTML::Template

index.cgi (our instance script)

Notes:

1. this instance script will pass a PARAM to the application
2. in this example, we need to output the form that now in a .tmpl file. Though some browsers will actually display the .tmpl file without H::T, we'll use an instance of our application to simply display the form.
3. the instance script might be evoked by a text link:
   <a href="http://www.acmecorp.com/contact/">Contact Us</a>
4. note that paths are relative to the location of the .tmpl file and not the instance script or application.

#!/usr/local/bin/perl -T

use lib "/opt/foobar/apps/";
use warnings;
use strict;
use Acmecorp::Contact;

my $app = Acmecorp::Contact->new( PARAM => 'client' );
$app->run();
[download]

contact.tmpl ('rm' is our runmode and will be passed upon submission to our instance script '/contact/index.cgi')

   <form action="/contact/index.cgi" method="post">
      <input type="hidden" name="rm" value="s" />
      
      <tmpl_if errors>
         <tmpl_loop errors>
            <p style="color: red"><tmpl_var error></p>
         </tmpl_loop>
      </tmpl_if>
      
      <p>Today's date: <tmpl_var today></p>
      
      <p>Name: <input name="name" type="text" value="" /></p>
      <p>Address: <input name="address" type="text" value="" /></p>
      <p>City: <input name="city" type="text" value="" /></p>
      <p>More info: <input name="more_info" type="checkbox" value="yes
+" /></p>
      <p><input name="Submit" type="submit" value="Submit" /></p>
   </form>
[download]

Foobar_Super (a super class for C::A applications)

Notes:

1. because you may be creating several C::A applications for other sites on your server, developing a super class eliminate repetition
2. C::A Plugin's integrates the modules they are associated with, negating the necessity of loading the native CPAN module
3. cgiapp_init is run before anything in the application. In the super class you can read configuration files, set paths, set sessions, etc.
4. the PARAM 'client' that was passed by the instance script is used by the super class to 'personalize' the instance.

package Foobar_Super;

use strict;
use warnings;

use base 'CGI::Application';
use CGI::Application::Plugin::FillInForm(qw/fill_form/);
use CGI::Application::Plugin::Config::Simple;
use CGI::Application::Plugin::Redirect;
use CGI::Application::Plugin::Session;
use CGI::Application::Plugin::DBH (qw/dbh_config dbh/);
use HTML::Template;

#--- Start CGI::APP 
sub cgiapp_init {
   my $self = shift;
      
   #--- Set Paths
   $self->config_file( '/opt/foobar/' . ucfirst $self->param('client')
+ .'/'. $self->param('client').'.conf');;
   $self->tmpl_path( '/var/www/' . $self->param('client') . '/template
+s );
                         
   #--- Session
   $self->session_config( DEFAULT_EXPIRY => '+8h');
                         
   #--- Contact to DB  
   $self->dbh_config( $self->config_param('db.host'), 
                      $self->config_param('db.user'),
                      $self->config_param('db.pass'), 
                      {RaiseError => 1} );
}
1;
[download]

acmecorp.conf (a configuration file)

Note: read by CA_Super's cgiapp_init

#--- MySQL Server ---
[db]
host  = DBI:mysql:foobar:localhost
user  = acmecorp
pass  = AKCgKYxc
[download]

Contact.pm (the actual application called by the instance script

Notes:

1. in the method 'display', the C::A convention for specifying a template is used: $self->load_tmpl
2. in the first firing of the instance script, no run mode will be passed, so the application will use the default function defined by the $self->start_mod('d') in the setup method. This will simply output, or display, the template file containing our form.
3. we also use the C::A::Plugin::FillInForm convention for outputting the form with the fill-in-form values: $self->fill_form

package Acmecorp::Contact;
use base qw(Foobar_Super Common);

use strict; 
use warnings;
use MIME::Lite;    #load any extra modules needed
use Date::Calc qw(Today);

#--- SETUP Runmodes

sub setup {
   my $self = shift;
   $self->start_mode('d');         #if no runmode, use 'd'
   $self->mode_param('rm');
   $self->run_modes(
      'd'         => 'display',
      's'         => 'save_form'
   );
}

#--- Display 

sub display {
   my $self = shift;
   
    my $template = $self->load_tmpl( 'contact.tmpl',
                                      die_on_bad_params => 0 );
                                      
   $template->param( today => sprintf( '%4d-%02d-%02d', Today() ) );  
+                                 

   return $template->output();
}

#--- Process 

sub save_form {
   my $self = shift;
   
   my ( %sql, @errors, $error, $fifvalues );
   
   ($sql{'name'}, $error ) = $self->validate( $self->query->param('nam
+e') );
      if ( $error ) { push @errors, ( { 'error' => 'Name'.$error } ); 
+}
   ($sql{'address'}, $error ) = $self->validate( $self->query->param('
+address') );
      if ( $error ) { push @errors, ( { 'error' => 'Address'.$error } 
+); }
   ($sql{'city'}, $error ) = $self->validate( $self->query->param('cit
+y') );
      if ( $error ) { push @errors, ( { 'error' => 'City'.$error } ); 
+}
   $sql{'more_info'} = $self->query->param('more_info');

   #if there are errors, return the form with original input and error
+ messages 
   if ( @errors ) { 
      my $template = $self->load_tmpl( 'contact.tmpl',
                                        die_on_bad_params => 0,
                                     );
   
      $template->param( errors => \@errors,
                        today  => sprintf( '%4d-%02d-%02d', Today() ),
                      );
   
      for my $key ( keys %sql ) { 
         $fifvalues->{$key} = $sql{$key}; #assign fill-in-form values
      }

      return $self->fill_form( \$template->output, $fifvalues );
      
   } else {
   
      $self->record(\%sql);  #record the input
      
      return $self->redirect('/thankyou.html');
   }   

}

#--- Record

sub record {
   my $self = shift;
   my $sql  = shift;
   my %sql  = %{ $sql };

    #we use CAP::DBH to connect to the DB and execute our SQL statemen
+t
   my $stmt = 'INSERT INTO contacts (' . join(',', keys %sql) . ') 
                  VALUES (' . join(',', ('?') x keys %sql) . ')';
   $self->dbh->do($stmt, undef, values %sql);   
}   
1;

<p><b>Common.pm</b> (a module with common methods)</p>
package Common;

sub validate {
   my $self = shift;
   my $to_check = shift;
   
   if ( $to_check !~ /^([\w ]+)$/ ) {
      return ( $to_check, " has invalid characters or is blank" );
   } else {
      return $1;
   }
}
1;
[download]

Summary

This tutorial has shown use of the basis tenents of using C::A as an application framework:

1. file layout and directory structure
2. instance scripts
3. run modes
4. cgiapp_init and redirect
5. integration of C::A::Plugin's
6. use of super class
7. intro to the H::T templating system

As always, you are encouraged to read the POD for C::A and then take a look at the growing number of Plugins to see if C::A can further streamline your coding process.

Other Resources

CGI::Application Wiki
Mailing List
HTML::Template Tutorial