CGI::Application Tutorial - A more extensive example using CGI::Application

As the CGI::Application documentation says, using this module is the inverse of using "page-based" applications such as JSP, PHP, and ASP.
Instead of dividing the CGI application into "pages", the entire application is an object, written as a module. The module is used as any Perl module, with no need to be within the web cgi-bin path. The only file needed within the web cgi-bin path is a small CGI script, which only creates an instance of our application object.
To make an analogy to a "page-based" application, CGI::Applications uses "run-modes", which correspond to subroutines, where each subroutine can be seen as a "page". So, instead of creating three scripts ("pages"), such as:

    helloworld.cgi-app1.pl
    helloworld.cgi-app2.pl
    helloworld.cgi-app3.pl

each "page" is defined as a "run-mode" in the application module:

    $self->run_modes(
        'mode1' => 'helloworld_cgi_app1',
        'mode2' => 'helloworld_cgi_app2',
        'mode3' => 'helloworld_cgi_app3',
    );

The corresponding subroutine's return value is handled by CGI::Application as the HTML output, so we don't have to care about "printing" the HTML:

sub helloworld_cgi_app1 {
        $html_output .= "<html>";
        $html_output .= "<head>";
        .
        .
        .
        $html_output .= "</body>";
        $html_output .= "</html>";
        return $html_output;
    }

NOTE: Don't try to 'print' anything directly to output in your Perl code. You'll probably get an error similar to this:

[Mon Aug 27 18:28:10 2001] [error] [client 127.0.0.1] malformed header from script.
Bad header=2: /home/kuuse/redantigua/www/scgi-bin/anymail.pl

If you want to get quick-and-dirty debug info about any variable, just insert the following temporary line where suitable in any run mode subroutine:

return $my_bogus_variable;

which will cause your application to output only the value of $my_bogus_variable to your browser.
A more flexible way is to print the variable to STDERR:

print STDERR $my_bogus_variable;

This will not cause any problems with malformed headers etc.
If you run the script from the command line, you will see the variable value among the other output.
If you run the script from the browser, you will find the variable value in the web server error log.

To go from one page/mode to another, the parameter "rm" has to be passed as

either as a HTML form field:

<input type="HIDDEN" name="rm" value="mode3">

or a HTML query string:

<a href="helloworld.cgi-app.pl?rm=mode3">Go to run mode 3</a>

We can fetch form/query parameters in the same manner as with the CGI.pm module. To fetch the HTML parameter "calling_mode",

either use a form field

<input type="HIDDEN" name="rm" value="mode3">
<input type="HIDDEN" name="calling_mode" value="1">

or a query string

<a href="helloworld.cgi-app.pl?rm=mode3;calling_mode=1">Go to run mode 3</a>

We use the query object in the subroutine "helloworld_cgi_app3":

sub helloworld_cgi_app3 {
  # Get CGI query object
  my $q = $self->query();
  my $calling_mode = $q->param("calling_mode");
  .
  .
  .
}

To show a real example, we will use three pages/modes in our application, generating the same output, but each one using its own technique:
1. Using strings
2. Using the CGI query object
3. Using a HTML template

Now we have enough information to create the module HelloWordCgiApp2.pm.
Run the script from the command line:

# perl -w helloworld.cgi-app.pl
(offline mode: enter name=value pairs on standard input)
rm=mode2
calling_mode=1

(press CTRL-D after entering the value pairs)
or in your browser (don't forget to configure DNS and Apache first):

# chmod 755 helloworld.cgi-app2.pl
# cp helloworld.cgi-app.pl /usr/local/apache/cgi-bin/.
# opera http://localhost/cgi-bin/helloworld.cgi-app.pl

which should look like this.

This is a very simple application using one 'CGI wrapper', one module, and one template.
When the application grows, the module grows and there may be more templates. But it is still easy to organize.
You can pass your templates to your web designer, and encourage other programmers to use the same modular design, to (hopefully) build a happier future, understanding, and better modules.

If you want to see a full-scaled CGI::Application-based program, download AnyMail.

IndexPreviousNext

Last modified: Thu Jan 18 12:34:19 Romance Standard Time 2007