Vol. 1, No. 24
Intro to CGI — Passing Data

To the delight of our builders, Tripod is now offering CGI capability to members. CGI, or common gateway interface (an unenlightening acronym if ever there was one), is a protocol that allows you to run a program or script on your Web server. For example, when a visitor fills out a form and clicks "Submit," the results are instantly e-mailed to you. How does a typical CGI-scripts operation work? Read and learn: A standard HTML form sends data to the Web server, which inputs that data into your script. The script does its little data-processing shtick and outputs a new HTML page, often incorporating some permutation of the data. Simple, no? CGI scripting can be used for a wide variety of applications, including real-time chat, shopping carts, and user-data file management.

CGI scripts can be written in a number of handy languages; on Tripod, we use Perl. Perhaps the most commonly used scripting language, Perl treads a nice median between godlike power and taking-candy-from-a-baby ease of use. It can be complicated, but fortunately you don't need to master the language in order to understand and write basic CGI scripts. (If anyone asks, Perl stands for "Practical Extraction and Report Language," but that has unpleasant connotations of painful dentistry and — even worse — junior high. Let's just stick with "Perl.")

Because CGI is so powerful, there are some ground rules. Face it, you're basically running your own software on Tripod's server, and we really don't want your software to delete all of our files, spoilsports we may be. All of your scripts will live and work on the cgi.tripod.com server, in the cgi-bin directory. If your script needs to modify another file, you must include that other file in the same directory, which will keep CGI from reaching out of its little enclosed bin and messing with other unsuspecting directories. Upload your CGI scripts — each with a .pl extension — to: cgi.tripod.com/yourname/cgi-bin/yourscript. In addition, file permissions are all handled on our end.

Perl Syntax

We don't have room to do more than just touch on the basics of Perl. You'd be well advised to read one of the Perl tutorials listed below. Remember, it's easy. Here's how it works.

Writing a Perl script is just like coding anything else — you simply type lines of text and then save them as a file. Of course, the text must be understandable by Perl. Don't worry about any white space in your code. You can put ten blank lines between each line of code or write all of your code on one line, for all Perl cares. The trick is, each statement has to end with a semicolon.

Also, a line of text beginning with a "#" isn't interpreted by Perl:

# This is the equivalent of commenting out some text in HTML. It doesn't affect your coding.

Variables in Perl are used to store whatever you want. The basic common type is called a "scalar." It begins with a dollar sign (as so many good things do) and an equals sign is used to assign it a value. You can give a scalar any name and any value you like:

$fruit = "pomegranate";
$number_of_seeds = 700;

Using the above examples, the following line:

print "A $fruit has $number_of_seeds seeds.";

... will display the following statement:

A pomegranate has 700 seeds.

The "print" command displays whatever text is in the quotes following the command. We could go on, but let's get our super-basic CGI up and running first and see how it goes.

What we'll be doing is making an HTML form that sends data to a Perl script. Perl reads form input (at least, form input sent using the POST method, which is what we'll be using) from standard input. Standard input is just what it sounds like, and is represented by <STDIN>. So the script that will read and display the data will look like this:

$name = <STDIN>;
# That puts the form data into the scalar variable called $name
print "$name";

That does the job, but since we want the script to give its output in the form of an HTML page, a few more steps are required. We need to send a header so that the browser knows what it's getting (you can always use the one below), and we also need to enclose our "Hello" statement in some simple HTML tags. So the final script looks like:

$name = <STDIN>;
print "Content-Type: text/html\n\n";
print "<html><body>";
print "<h1>$name</h1>";
print "</body></html>";

Save that in your cgi-bin directory as name.pl. All set? Now, on another HTML page, we'll have a form that sends a line of data to name.pl, like this.

<html><body>
<form action="cgi-bin/name.pl" method=POST>
Enter your name, please.<p>
<input type="text" name="yourname">
<input type="submit" value="Send">
</form>
</body></html>

That's quick and dirty coding, without even a pause to title the page. Let's save that little beauty as "shortform.html." Notice that the form's action attribute points to the CGI script that's going to field the data. You can see it in action here.

What happens when we run it? First, type your name into the form field and click "Send." That sends a name/value pair to the Perl script — the name of the form field ("yourname") and the value entered into it (your name; let's say "Dave" for our purposes). The Perl script reads that info into a variable called "$name" and then outputs an HTML page containing the contents of $name, shown as: "yourname=Dave." Voila!

For such a script to be useful, you might want it to file all of the name/value pairs it gets for later tabulation. Or you might have it trim off the "yourname=" part of the variable, so that it can say something cool like, "Hi, Dave, welcome to my cave" rather than something lame like, "Hi, yourname=Dave." That could be done with the split function, which works a lot like the JavaScript split function that was covered in our cookies tutorial. You'll find details about how to accomplish this, and ever so much more, in later installments of Handcrafted. If you can't wait, check out some of the links below. Welcome to CGI. Experiment and have fun!

HINTS, POINTERS, AND TIPS 'O THE TRADE:

If you "borrow" a Perl script from somewhere other than Tripod, you'll probably see that the first line is something like "#!/usr/bin/perl." This tells the server how to run the script. Tripod doesn't require that line. Yet another reason Tripod rules.

If you have multiple form fields passing multiple bits of data to your CGI script, the variable that reads the data in from <STDIN> will be an array. Arrays are fun.

When your script doesn't work, first check to see if there's a semicolon at the end of each line. Then make sure that every quotation mark, parenthesis, and so on, is both opened and closed. Then start debugging for real.

Up to a certain point, older bread makes better toast.

RESOURCES:

Tripod JavaScript/CGI Library

Everything You Ever Wanted to Know About Tripod CGI (But Were Afraid to Ask)

Webmonkey: Intro to Perl for CGI

Webmonkey: CGI Scripts for Fun and Profit

Matt's Script Archive

Handcrafted Archive