Book HomeJava and XSLTSearch this book

Chapter 10. The CGI.pm Module

Contents:

HTML Tag Generation
Importing Method Groups
Maintaining State
Named Parameters
Using JavaScript Features
Debugging
CGI.pm Reference

CGI.pm is a Perl module for creating and parsing CGI forms. It has been distributed with the Perl source kit since 5.004, but you can upgrade your existing CGI.pm installation from CPAN. As of the writing of this edition, the current version of CGI.pm is 2.81.

CGI is an object-oriented module. Don't let the object-oriented nature scare you off, though; CGI.pm is very easy to use, as evidenced by its overwhelming popularity among all levels of Perl programmers. To give you an idea of how easy it is to use CGI.pm, let's take a scenario in which a user fills out and submits a form containing her birthday. Without CGI.pm, the script would have to translate the URL-encoded input by hand (probably using a series of regular expressions) and assign it to a variable. For example, you might try an antiquated parsing method like this:

#!/usr/local/bin/perl 
# CGI script without CGI.pm

$size_of_form_info = $ENV{'CONTENT_LENGTH'};
read ($STDIN, $form_info, $size_of_form_info);

# Split up each pair of key/value pairs
foreach $pair (split (/&/, $form_info)) {

   # For each pair, split into $key and $value variables
   ($key, $value) = split (/=/, $pair);

   # Get rid of the pesky %xx encodings
   $key =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;
   $value =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;

   # Use $key as index for $parameters hash, $value as value
   $parameters{$key} = $value;
}

# Print out the obligatory content type line
print "Content-type: text/plain\n\n";

# Tell the user what they said
print "Your birthday is on " . $parameters{birthday} . ".\n";

Regardless of whether this code actually works, you must admit it's ugly, and completely ignores important details such as dealing with tainted input. With CGI.pm, the script could be written as:

#!/usr/local/bin/perl -w
# CGI script with CGI.pm

use CGI;

my $query = CGI->new( );

my $bday = $query->param("birthday");

print $query->header(-type => 'text/plain');
print $query->p("Your birthday is $bday.");

Even for this tiny program, you can see that CGI.pm can alleviate many of the headaches associated with CGI programming.

As with any Perl module, the first thing you do is call the module with use. You then call the constructor (new( )), creating a new CGI object called $query. Next, get the value of the birthday parameter from the CGI program using the param method. Note that CGI.pm does all the work of determining whether the CGI program is called by the GET or POST methods, and it does all the URL decoding for you. To generate output, use the header method to return the content type header and the p method to generate a paragraph marker <P> tag.

However, this is only the tip of the iceberg as far as what CGI.pm can do for you. There are three basic categories of CGI.pm methods: CGI handling, creating forms, and retrieving environment variables. (A fourth category is creating HTML tags, but we don't cover those in detail.) Table 10-1 lists most of these methods. They are also covered in more detail later in this chapter.

Table 10-1. CGI.pm methods

Method

Description

CGI handling

keywords

Gets keywords from an <ISINDEX> search

param

Gets (or sets) the value of parameters

append

Appends to a parameter

import_names

Imports variables into a namespace

delete

Deletes a parameter

delete_all

Deletes all parameters

save

Saves all parameters to a file

self_url

Creates self-referencing URL

url

Gets URL of current script without query information

header

Creates HTTP header

redirect

Creates redirection header

cookie

Gets (or sets) a cookie

nph

Declares this to be a NPH script

dump

Prints all name/value pairs

Form generation

start_html

Generates an <HTML> tag

end_html

Generates an </HTML> tag

autoEscape

Sets whether to use automatic escaping

isindex

Generates an <ISINDEX> tag

startform

Generates a <FORM> tag

start_multipart_form

Generates a <FORM> tag for multipart/form-data encoding

textfield

Generates an <INPUT TYPE=TEXT> tag

textarea

Generates an <TEXTAREA> tag

password_field

Generates an <INPUT TYPE=PASSWORD> tag

filefield

Generates an <INPUT TYPE=FILE> tag

popup_menu

Generates a pop-up menu via <SELECT SIZE=1> and <OPTION> tags

scrolling_list

Generates a scrolling list via <SELECT> and <OPTION> tags

checkbox_group

Generates a group of checkboxes via multiple <INPUT TYPE=CHECKBOX> tags

checkbox

Generates a single checkbox via an <INPUT TYPE=CHECKBOX> tag

radio_group

Generates a group of radio buttons via <INPUT TYPE=RADIO> tags

submit

Generates a <SUBMIT> tag

reset

Generates a <RESET> tag

defaults

Generates a <DEFAULTS> tag

hidden

Generates an <INPUT TYPE=HIDDEN> tag

image_button

Generates a clickable image button via a <SELECT> tag

button

Generates a JavaScript button

Handling environment variables

accept

Gets accept types from ACCEPT header

user_agent

Gets value of USER_AGENT header

path_info

Gets value of EXTRA_PATH_INFO header

path_translated

Gets value of PATH_TRANSLATED header

remote_host

Gets value of REMOTE_HOST header

raw_cookie

Gets value of HTTP_COOKIE header

script_name

Gets value of SCRIPT_NAME header

referer

Gets value of REFERER header

auth_type

Gets value of AUTH_TYPE header

remote_user

Gets value of REMOTE_USER header

user_name

Gets user name (not via headers)

request_method

Gets value of REQUEST_METHOD header

10.1. HTML Tag Generation

In addition to the form-generation methods, CGI.pm includes a group of methods for creating HTML tags. The names of the HTML tag methods generally follow the HTML tag name (e.g., p for <P>) and take named parameters that are assumed to be valid attributes for the tag (e.g., img(src=>'camel.gif') becomes <IMG SRC="camel.gif">). We do not list all tags in this book; see the CGI.pm manpage for more information, or the book Official Guide to Programming with CGI.pm by Lincoln Stein (John Wiley & Sons, 1998).



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.