STIMULUS Internet 101: CGI Perl

How to build a form?
How to write a Perl script?
How to get the values from the FORM?
How to process the information?
How to process send back an HTML page?
How to send an e-mail using Perl?

Welcome to our lesson on CGI Process. Now where did we leave off? We briefly went over various commands that relate to CGI programming using HTML and Perl. This lesson will gather all the miscellaneous information and provide a step-by-step example of how to build an HTML FORM that talks to a Perl/CGI and get a response.

How to build a FORM object in your HTML page

Okay, this is a two part step: The first part is a very quick step which tells the FORM where to send the information once the user presses the SUBMIT button that we talked about in Preface to CGI. The "tag" in HTML that tells the page where to send the information is called the ACTION tag, and is an attritude tag just inside the FORM itself. Example of starting form that you can copy:

<FORM METHOD=POST ACTION="http://www.stimulus.com/cgi-bin/lesson5.pl">

Once you've created the FORMs ACTION tag, you can then start laying out the FORM FIELDS. As we showed you in our Preface to CGI lesson, the best method for laying out fields is to use TABLE objects. This is to ensure that the fields are spaced evenly. The other professional trick is to make sure that the FIELDS have the correct SIZE and MAX tags. This will make sure that someone doesn't type too many characters inside a particular FIELD. Since most people use standard CUT and PASTE methods of creating HTML forms, its not too uncommon to see amateur forms that look like this:

Name:
Address:
City:
State:
ZIP Code:

Even though this is a quick method of making forms, it forever demonstrates a complete lack of professional industrial strength data gathering. You wouldn't create a window like this to gather information inside a database application. The main question is: What do you do with all the extra data? Maybe its important information that the user entered, not knowing what you were doing using a 35 character long State FIELD.

So the golden rules about FORMs, are to make sure the SIZE is set appropriately, and that the MAX limits the number of characters that can be typed into in a single FIELD. Here is a better example of a form that collects the correct amount of data:

Name:
Address:
City:
State:
ZIP Code:

You'll notice that the above form has different sizes for the various fields, while it also limits the number of characters that the user can type in to match the number of characters that have been used in the database where we plan to store the information. Granted, this form will only work in the United States, because of the 2 character STATE field, but we thought this was a good way to make a point.

After you have laid out your FIELDs, it is time to add the SUBMIT button. The code for this looks like:

<INPUT TYPE="submit" VALUE="Submit Form">

The SUBMIT button as we mentioned in CGI Preface, actually tells the internet browser to send the information in the form fields to the destination in the SUBMIT part of the FORM tag. In our case, the data will be sent to the lesson5.pl PERL script sitting on the STIMULUS server.

Great, I know this part, where does it go?

You guys ask the best questions! Alright, this is where we enter the world of CGI. Remember, CGI is merely a language type, it isn't a language in itself. For this lesson we are going to use the most common CGI language in the world, Perl.

The way this works, is there is a Perl compiler (an application that can run Perl scripts) on the STIMULUS.COM server. When we send this information to a particular Perl script, that "compiler" compiles the scripts instructions, processes the information that was sent to it, and does any number of things in return. In our case, we are going to collect the information from the fields, and send an HTML page back to the user as a response.

One of the best ways to think about writing Perl scripts is to break things down into tasks. When processing incoming information, we:

Gather the field information
Make sure the user gave us all the information we need
Process that information however we'd like
Send some response back to indicate we got the information

Here is a typical Perl script in the smallest form:


#!/usr/bin/perl 
#
# This electronic Perl script was written by 
#
#[Your name here]
#©Copyright 1998-06, [Your company]. All Rights Reserved.

require "cgi-lib.pl";

&ReadParse(*in);

$name = $in{"name"};

print "Content-type: text/html\n\n";
print "<HTML>";
print "<HEAD><TITLE>CGI Process: $name\n</TITLE></HEAD>";
print "<BODY>";

if($name eq "") {
	print "<H1>Invalid Name. Please Try Again.</H1></BODY></HTML>";
	exit (0);
}

print "The name is <b>", $name, "</b>";
print "</BODY></HTML>";

That's it. That is the entire script that will take a single field called "name" and check to see if it has a value. If it does have a value it then sends back an HTML document to the browser to display that name. Now we realize that Perl doesn't look familiar, but it will soon.

Now you try it!

The following field information will post to the lesson5.pl CGI, and return results. The script that is executing, is EXACTLY the script above.

Name:

Now lets review the Perl script ONE STEP AT A TIME

Lets take the first line:

#!/usr/bin/perl

This is an important line that tells the server where to find the Perl "compiler." The compiler is the piece of software that reads the script, and compiles it into machine language so the computer can understand what to do with it. Once its compiled, its ready to run.


#
# This electronic Perl script was written by 
#
#[Your name here]
#©Copyright 1998-06, [Your company]. All Rights Reserved.

Now the rest of the lines that start with "#" signs, are lines of comments. Only the first line with the "#" is used by the server to do anything. All other lines that begin with "#" are ignored by the compiler when its trying to figure out what to do with the script. It is always a good idea to comment your code. You and others will forget what the heck you were doing, even with a well written script, because it will probably run for several months (and maybe even years) before its ever changed. Bottom-line, COMMENT YOUR CODE!!!!

Getting a little help from the internet itself

Moving right along, in order to make things easier for us to get values from the form itself, we're using a file that was created by someone else. This file is called "cgi-lib.pl" and it contains a library of procedures that we can use in our code. The most widely used by us, is the &ReadParse() routine. NOTE: You can find this file at http://www.bio.cam.ac.uk/cgi-lib/.


require "cgi-lib.pl";

Reading in all the values

After we've required the cgi-lib.pl file, we can now take advantage of its power. We do this by calling the &ReadParse() routine which will (okay bare with me) read all the values into an array called "in." We could have called it anything, buy we chose "in."


&ReadParse(*in);

Once we've read the values into the "in" array, we can go on to parse the individual field values out of that array. NOTE: An Array is a collection of values stored in a numbered list. The list in our case has a single name "in." The first item is in[0], the second is in[1], the third is in[2], and so on. One can also access values by using names instead of numbers. For instance; in['name'], in['address'], in['state'], etc..

Getting individual field values from the "in" array

As we said above, its time to get the value from the "name" field. This is done as follows:


$name = $in{"name"};

Now since we only have one variable, we only need one line. If we had more than one, we would continue to add lines for every value that we want to analyze. In this line we have created a new variable inside the Perl script which uses also the same name as the original, except that it adds a "$" to the name of the field. This is what Perl uses to distinguish a field name from other commands and variables.

Setting up the return page

Now we need to grasp a new concept. This concept relates to the way that a Perl script communicates back with the browser. When you send a submission to a CGI script (regardless of language), the server creates what is known as a "pipe" from the script to the browser. This "pipe" is used to send information back to the browser. In Perl, the old "print" command from basic programming days, is used to send information directly back through the pipe that was initially created. In our case, the pipe talks directly back to the browser. Since our goal is to send an HTML page back to the browser in response to the submission, we have to set up the "header" information for the HTML page. This is done with the following code:


print "Content-type: text/html\n\n";
print "<HTML>";
print "<HEAD><TITLE>CGI Process: $name\n</TITLE></HEAD>";
print "<BODY>";

Notice the strange line "Content-type: text/html\n\n." This line is always sent to the server when HTML pages are sent to your browser, but usually your browser removes this line from display. This is known as the header to an HTML page. It tells the browser and the server what kind of file it is. The strange "\n" characters are actually carriage returns. The server will replace the "\n" with ASCII character 13s, as if you had typed them yourself.

The rest of the print commands should be understood as normal HTML page header information that you learned from the previous HTML lessons.

Testing to see if we got a valid name

The next logical step we must preform is a test to see if the user gave us a name to return to them. If they didn't, we want to tell them so. This is accomplished by using an "if" statement. This is very similar to most computer languages. We use the "eq" argument to see if the variable "$name" that we set up in a previous line equals something. The easiest way to do this is to test to see if it equals nothing, then warn against that eventuality. NOTE: The "eq" is used for comparing variables that contain "text" data. The "=" sign is used for comparing "numeric" data. Otherwise, an "=" acts as a verb that will set the variable to a value, e.g., x = 3, which makes x = 3.

If we didn't get a value, this code will execute completely:


if($name eq "") {
	print "<H1>Invalid Name. Please Try Again.</H1></BODY></HTML>";
	exit (0);
}

Notice the "exit (0);" command. This tells the script to halt execution in its tracks. This will only execute if the user didn't provide a value for the $name variable. If a value wasn't provided inside the $name variable, we send back an HTML page telling the "Invalid Name. Please Try Again.," and then we halt the execution of the Perl script.

If they did give us a value

If there is a value in the $name variable, then the above argument will fail and the code will continue to execute. At this point, we send back a page that repeats the name that was provided.


print "The name is <b>", $name, "</b>";
print "</BODY></HTML>";

Notice how we've used the $name variable inside the print command. This is one method of accomplishing this. You can simply include the $name inside the return sentence like, "The name is <b> $name </b>" but sometimes this doesn't always work depending on the data in the variable, so we opted for the most reliable method.

Recommended Books: