Building a Web Form - A Script to Process It

IMPORTANT: These instructions are for the www.indstate.edu server.

How do Web Forms Work?

Form content is processed by a special program written for that purpose. The web server uses the common gateway interface to run that program.

CGI (common gateway interface) refers to the convention by which the web serving process initiates another executable program on the machine. All scripts are executable programs; not all programs are scripts. Using agreed-upon conventions, the web serving process passes information to and receives information from the program. This program is called a cgi script (or program) because it is the object of the cgi interface. 

The Tools

SSH

SSH will allow you to login to a remote computer and issue commands to get that remote computer to do certain things, such as edit or copy a file.

Official ISU SSH documentation is available here:
http://ithelp.indstate.edu/info/ssh-client.html

Common UNIX Commands:

Pico

Pico is a text editor. This editor will allow you to edit and create text files right on the web server. After you have logged into your account, you can run Pico by typing pico at the Unix prompt and pressing enter. This will create a new file for you to edit. To open an existing file, type pico filename and press enter.

Pico is fairly simple to use. Use the arrow keys to move through your document. Commands for using Pico are listed at the bottom of the screen. Most of the commands are a combination of the control key and a letter. For instance, to move down a screen in your document press control -Y.

After you are finished editing your document, you will want to exit and save it. To exit and save your document:

1. Press control-X.
2. Pico will ask,"Save Modified Buffer (answering No will destroy changes)?" Type Y.
3. Pico will then ask "File Name to write?" Type the name you want to call the file and press Enter. If the name of the file is listed and you want to save your changes to that file, simply press enter.

Web Browser

You will also need a web browser such as Netscape to view and test your forms.

The Nuts and Bolts of Forms 

For each form item, whether it be a checkbox, a text entry field, or a pull down list, you must define the following:

The syntax for defining Input Type, Name, and Value for each form input type is different.

Form Input Items

<form></form> tags

This tag tells the web browser that anything lying between the <form></form> tags should be considered an HTML form. This tag is necessary for writing an HTML form. For each <form> tag you must define the Method and the Action. 

• Method: this tells the form how to send the information to the server. Scripts written on the ISU web server should always use the method "POST"
• Action: this tells the form which script should receive the information.

A sample <form> tag here on a document residing on web.indstate.edu would look like this:

Plain Text Entry <input type="text">

The code for a plain text entry form item would look like this:

<input type="text" Name="favorite_animal" Value="frog" size="30">

• Name: name of the field
• Value : value of the field. If you wish to leave it blank you can use value=""
• Size: this determines how long the blank is on screen. It defaults to 20 characters.

A plain text entry form element looks like this:

Text Box <textarea></textarea>

The code for a text box form item would look like this:

<TEXTAREA Name="description" Rows="4" Cols="40">

You can leave this line blank or you can add text to have it appear in the text box.

</TEXTAREA>

• Name: this is the name of the field
• ROWS: this defines how many rows the text area will have
• COLS: this defines how many columns the text area will have

A text box form element looks like this:

Select Menu <select></select>

The code for a select menu would look like this:

<select name="favorite_pet">

<option value="cat"> Cat

<option value="frog"> Tree frog

<option value="dog">Dog

</select>

• Name: name of the field
• Option: specifies what will be listed in the select list
• Value: defines the associated value for each option. This will be the value submitted to the cgi script. If no value is defined, the option text will be submitted instead.

A select menu form element looks like this:

Checkboxes <input type="checkbox">

The code for check boxes look like this:

<input type="checkbox" name="dog" value="yes_I_have_a_dog"> Yes, I have a dog.

<input type="checkbox" name="cat" value="yes_I_have_a_cat">Yes, I have a cat

<input type="checkbox" name="frog" value="yes_I_have_a_frog"> Yes, I have a frog.

• Name: name of the field. Check boxes are best used when you want people to be able to select more than one answer. In order to allow people to select more than one answer, you must have a separate field name for each check box.
• Value: defines the value that is sent to the server if the box is checked.

Check box form elements look like this:

Radio Buttons <input type="radio">

The code for radio buttons look like this:

<input type="radio" name="frog_type" value="whites">Whites Tree Frog

<input type="radio" name="frog_type" value="green_mantella">Green Mantella

<input type="radio" name="frog_type" value="barking" CHECKED>Barking Tree Frog

<input type="radio" name="frog_type" value="red_legged">Red Legged Walking Frog

• Name: name of the field.
• Checked: specifies which radio button is selected by default
• Value: defines the value that is sent to the server if the box is checked.

Radio button form elements look like this:

Reset and Submit Buttons

The code for reset and submit buttons look like this:

<INPUT TYPE="reset" VALUE="Clear fields">

<INPUT TYPE="submit">

Reset and submit button form elements look like this:

Script Elements  

IT has provided a simple mailing script that you can customize. Make sure you save the file as text (not source) or cut and paste the information from the web browser into your text editor. If you have an account on web.indstate.edu you can also copy the file directly into your account by issuing the following command from the SSH prompt:

cp /it/user-serv/websupport/form-script.cgi my-script.cgi

Once you have copied the sample script into your web account (make sure you it has a .cgi extension) , you will need to customize the items below so that it will work with the form you have developed.

To customize the form, you must be familiar with a few basic elements of the Perl scripting language:

Configuration Options:

#----------------------------
# Start Configuration Options
#----------------------------

# Edit this line to specify one or more domain names authorized to use this
# service (can be full or partial domain name)

@Referers = ( "web.indstate.edu", "www-isu.indstate.edu" );

# Edit this line to specify the email address of the recipient that should
# receive this evaluation

$Recipient = "dduck@water.indstate.edu";

# Edit this line to specify the full path to your send Internet mail utility

$MailUtil = '/usr/lib/sendmail';

# Edit this line to specify the title of the resultant HTML response

$Title = 'Pet Information';

# Edit this line to specify the heading of the resultant HTML response

$Heading = 'Pet Information';

#--------------------------
# End Configuration Options
#--------------------------

Adjusting what the response page will look like

# Print a title and initial heading

print "<HEAD><TITLE>$Title</TITLE></HEAD>"
print "<BODY bgcolor=white>"
print "<img src='http://web.indstate.edu/it/user-serv/graphics/header.gif'>"
print "<H1>$Heading</H1>"

Making Form Fields Required

# Send blank form error message if no comments were specified

# &blank_response unless $FORM{'favorite_animal'};
# &blank_response unless $FORM{'pets'};
# &blank_response unless $FORM{'name'};
# &blank_response unless $FORM{'email'};

AND

sub blank_response
{
    print "Your comments appear to be blank and thus were not sent to the";
    print " specified recipient.\n";
    exit( 0 );
}

Sending the Mail Message and Response Screen.

# Now send mail to specified recipient
open ( MAIL, "|$MailUtil -t -n -oi" ) || die "Unable to open $MailUtil\n";
print MAIL "To: $Recipient\n";
print MAIL "From: webmaster\@indstate.edu (ISU Web Server)\n";
print MAIL "Reply-to: $FORM{'email'} ($FORM{'name'})\n";
print MAIL "Subject: Animal Query (Forms Submission)\n\n";
print MAIL " \n";
print MAIL "What is your favorite animal: $FORM{'favorite_animal'}\n";
print MAIL "\n";
print MAIL "Do you have any pets? $FORM{'pets'}\n";
print MAIL "\n";
print MAIL "What is the name of your pet? $FORM{'name_of_pet'}\n";
print MAIL "\n";
print MAIL "Name: $FORM{'name'}\n";
print MAIL "\n";
print MAIL "Email: $FORM{'email'}\n";
print MAIL " \n";
close ( MAIL );

AND

# Make the person feel good about submitting these comments<

print "Thank you for filling out this form.

";

Calling the Script from your Form 

After you have customized your script and put it into your account on the web server, you need to edit your html form to call that specific script. Calling the script is done from the <form> tag. To call a script with the filename of favorites.cgi, your <form> tag should look like this:

In order for your script to run, you must make sure that it is executable. To do this, from the SSH prompt type:

and press enter.

For instance, to make sure the script favorites.cgi is executable you would type: chmod 755 favorites.cgi and press the enter key.

Troubleshooting  

Often your script won't work the first time you run it. Here are some troubleshooting hints:

• Open the sample script and compare it to your own.
• Look for mismatching quotation marks.
• Look for missing ; at the end of lines.
• Look for special characters such as @ that have not been escaped with a backslash \@.
• SSH into your account and type the name of your script and press enter. This will give you a list of errors and at what line they occur.
• Run 'chmod' on your script file again. Make sure it is set to be an executable file.
• Make sure your form is calling up your script correctly. For instance, is it using the right name?
• Make sure all your comment lines start with an # .
• Make sure you don't have any lines that wrap down to the next line.
• 403 Forbidden. Your client does not have permission . . . This usually means you haven't made your script executable. To do this type chmod 755 scriptfilename.cgi at the SSH prompt.
• 500 Server Error. This usually signals a problem with the script itself. SSH into your account and type the name of your script and press enter. This will give you a list of errors and at what line they occur.
• Nothing happens when you click on the submit button. This usually means that you have forgotten to define the Method and Action in the Form tag.