EIW Fall 2000 Lecture Notes - CGI and HTML Forms

CGI and ISINDEX Input

The input to a CGI program comes from a user as part of an HTTP request sent by the user's browser. We've already discussed how to use the HTML ISINDEX tag to allow the user to enter a single line of text - here is an example:

<H2>Magic Number Guessing Program</H2>

<ISINDEX ACTION=yup.html
PROMPT="Type in your favorite number and press Enter ">

Magic Number Guessing Program

In the above example the ACTION attribute of the ISINDEX tag refers to a simple HTML file, so the user sees the same thing no matter what value they enter (they get the file yup.html). However - if you look at the URL displayed by the browser after entering a number and pressing Enter, you can see that the URL includes the number as a query. In general we will want to have a CGI program send back a document that depends on the query.

CGI and HTML Forms

Many Web applications require more than a single line of input. HTML forms provide a mechanism for including many input boxes (and buttons) that the user can use to provide input to the CGI program. It is important to remember that the basic mechanism for getting input from the user to the CGI program is the same whether using forms or ISINDEX tags - a query string is appended to the URI after a '?'.

The FORM tag

All form elements must be placed between a <FORM> and </FORM>. There can be multiple forms within a single HTML document - each form is seperate entity and the contents of only one form are submitted as query (although a single form many contain many elements). The FORM tag has required attributes ACTION and METHOD.

The METHOD attribute of a form tag specifies the HTTP request method that should be used when the contents of the form are submitted as part of an HTTP request. Typically the request method is either GET or POST. The CGI program that will receive the contents of the form must support the method specified, or things won't work. In other words - it is possible to write a CGI program that only handles GET requests, so you need to know a little about the CGI program to decide whether to use GET or POST.

Recall that in an HTTP GET request the query is sent as part of the URL (after a '/'). In an HTTP POST request the query string is sent after all the request headers (as the content of the request).

The ACTION attribute specifies where the contents of the form should be sent. This is typically a URL (could be relative or absolute), although sometimes people use a mailto: URL so that when the user submits the form it is sent to as an email message to the specified email address.

Some FORM tag examples:

<FORM method=GET ACTION=http://www.foo.com/cgi-bin/aprog>


<FORM method="GET" action="prog.cgi">

<FORM method=POST action="mailto:billy@whitehouse.gov">

Form Elements (Fields)

Between the <FORM> and </FORM> tags you define the text and fields that make up the form. You can include HTML tags inside a form to format the text however you want, and there are a number of new tags that are used to define form fields

There are a variety of types of form fields:

Input Fields

Input fields allow the user to type in a string value as input or to click on buttons or menus to select specific options. These fields are all created with the INPUT tag, the required attribute TYPE indicates what specific kind of input field is being created.

The INPUT tag also has a required attribute named NAME that establishes the name of the field being created. This name is important, since it will be sent to the CGI program along with the value the user provides. Within a single form, every input must have a unique name.

Below is a description of many of the types of input fields, see any HTML reference for a complete description

TEXT Input Fields

TEXT is the most common type of input field, it allows the user to type in a single line of text. There are some additional attributes that can control the maximum length of the field (MAXLENGTH), the size of the box drawn by the browser (SIZE) and the initial/default value for the field (VALUE).

Here are a few examples of TEXT input fields:

<INPUT TYPE=TEXT NAME=FOO>
       
<INPUT TYPE=TEXT
       NAME=PIZZA
       SIZE=10
       MAXLENGTH=20
       VALUE=Pepperoni>

Here is an example form that includes a couple of text fields:

<FORM METHOD=POST ACTION=cgi-bin/foo>
Your Name: 
<INPUT TYPE=TEXT NAME="Name"><BR>
 
Your Age:
<INPUT TYPE=TEXT NAME="Age"><BR>
 
</FORM>

Your Name:
Your Age:

A couple of things to notice:

  1. There is no special kind of "number" field - we just use a text field to get the user's age (and hope they actually type in a number).
  2. The form above has no button to press, so there is no way for the user to submit the form!

Submission Buttons

Another type of input field is the SUBMIT type, this tells the browser to draw a button. When the user clicks on the button the browser knows to submit the contents of the form to the URL specified as the ACTION in the form tag.

Submit inputs support the attribute VALUE which is the string you want displayed in the button. If you don't include a VALUE attribute the browser will put the string "Submit" in the button. Note that the NAME attribute is not required for a submit input.

Reset Buttons

An input of type RESET tells the browser to create a button that the user can press to clear all form fields (set to the default values). You can specify the text to appear in the button with the VALUE attribute.

Now we can look at a complete form example:

<FORM METHOD=POST ACTION=cgi-bin/foo>
Your Name: <INPUT TYPE=TEXT NAME=Name><BR>
 
Your Age: <INPUT TYPE=TEXT NAME=Age><BR>
 
<INPUT TYPE=SUBMIT VALUE=Submit>
<INPUT TYPE=RESET VALUE="Clear Form">
</FORM>

Your Name:
Your Age:

Tables and Forms

Tables are often used to make forms look pretty - remember that you can include any HTML formatting tags you want within a form

<FORM METHOD=POST ACTION=cgi-bin/foo>
<TABLE><TR>
  <TD>Your Name: </TD>
  <TD><INPUT TYPE=TEXT NAME=Name></TD>
</TR><TR>
  <TD>Your Age:</TD>
  <TD> <INPUT TYPE=TEXT NAME=Age></TD>
</TR><TR>
  <TD><INPUT TYPE=SUBMIT VALUE=Submit ></TD>
  <TD><INPUT TYPE=RESET VALUE="Clear Form"></TD>
</TR></TABLE>
</FORM>

Your Name:
Your Age:

Checkbox Inputs

Inputs of type CHECKBOX present user with an item that can be selected or deselected. Each checkbox has a name and a value and can be initially selected/deselected. To set the checkbox to be initially checked assign the value 1 to the VALUE attribute.

Here are some example checkbox definitions:

<INPUT TYPE=checkbox name=chocchip value=1>
<INPUT TYPE=checkbox name=oreo value=1>

Here is a complete form example that includes some checkboxes:

<FORM METHOD=POST ACTION=cgi-bin/foo>

Select all the cookies you want to order:<BR>
 
<INPUT TYPE=CHECKBOX NAME=Oreo Value=1> 
   Oreo<BR>
<INPUT TYPE=CHECKBOX NAME=Oatmeal > 
   Oatmeal<BR>

<INPUT TYPE=CHECKBOX CHECKED NAME=ChocChip Value=1>
  Chocolate Chip<BR>
 
<INPUT TYPE=SUBMIT VALUE=Submit>
</FORM>

Select all the cookies you want to order:
Oreo
Oatmeal
Chocolate Chip

Radio Button Inputs

Radio Button inputs are like checkboxes, except that the user must select only one item from group of choices. The way the browser knows which radio buttons are part of a group of choices is by looking at the NAME attribute. All radio button inputs that form a group must have the same NAME, and each should have a different value for the VALUE attribute (this is how the CGI program will find out which was picked).

Here is a complete form that includes some radio buttons:

<FORM METHOD=GET ACTION=cgi-bin/foo>
Select the cookie you want to order:<BR>
 
<INPUT TYPE=RADIO 
       NAME=Cookie Value=Oreo>
       Oreo <BR>
<INPUT TYPE=RADIO 
       NAME=Cookie Value=Oatmeal>
       Oatmeal <BR>
<INPUT TYPE=RADIO CHECKED
       NAME=Cookie Value=ChocChip>
       Chocolate Chip<BR>

<HR>
Select the size drink you would like:<BR>

<INPUT TYPE=RADIO NAME=drink VALUE=1>
  <span style="font-size:small"> Small</SPAN><BR>

<INPUT TYPE=RADIO NAME=drink VALUE=2>
  <span style="font-size:medium"> Medium</SPAN><BR>

<INPUT TYPE=RADIO NAME=drink VALUE=3>
  <span style="font-size:large"> Large</SPAN><BR>

<INPUT TYPE=SUBMIT VALUE=Submit>
</FORM>

Select the cookie you want to order:
Oreo
Oatmeal
Chocolate Chip
Select the size drink you would like:
Small
Medium
Large

TEXTAREA Form Fields

You can create a multiline text field with the TEXTAREA tag - you don't use the INPUT tag to create this kind of field. The TEXTAREA tag requires the NAME attribute and supports the attributes ROWS and COLS (to define the size of the box drawn on the screen). Unlike the INPUT tag - the TEXTAREA tag has an end tag, so you need to include a </TEXTAREA tag.

Everything included between the <TEXTAREA and </TEXTAREA tags is the initial value of the multiline text box. The user can delete, edit or add to this initial text.

Here is a complete example:

<FORM METHOD=POST ACTION=cgi-bin/foo>

Please enter your address
in the space provided:<BR>

<TEXTAREA NAME=address COLS=40 ROWS=5>
Your address goes here
</TEXTAREA><BR>

<INPUT TYPE=SUBMIT VALUE=Submit>
</FORM>

Please enter your address in the space provided:

Form Submission

When the user presses on a submit button the following happens:

There are a few rules to keep in mind:

Checking what is sent by the browser

The Xitami Web Server includes a test cgi program that you can use to see what query string is built by the browser. Use the action: ACTION=/cgi-bin/TestCGI to send your form to this program. The output of this CGI program is a list of environment variables set by the web server before starting the CGI program, including the query string.

Other Form Field Types

There are more form field types:

Typical FORM/CGI Setup

In a typical web application involving a CGI program, the user fills out a form and presses a submit button. The CGI program gets a set of name,value pairs - one for each form field. The CGI decides what to do based on the name,value pairs and send back a dynamic document, sometimes the document is another form.

Student Grade Database Example

A sample student grade database based on CGI might work like this:

We can start developing this application by designing the HTML form required. We need 2 fields, one for the id and another for the password. Here is one possible form:

<FORM METHOD=GET ACTION=/studb.cgi>
<TABLE>
<TR>
 <TD>Login id:</TD>
 <TD><INPUT TYPE=TEXT NAME=student></TD>
</TR>
<TR>
 <TD>Password:</TD>
 <TD><INPUT TYPE=PASSWORD NAME=pw></TD>
</TR>
<TR COLSPAN=2>
 <TD><INPUT TYPE=submit Value="login"></TD>
</TR>
</TABLE>
</FORM>

Login id:
Password:

If the user was to enter the string "bobcostas" as the ID and the password "sydney", the request sent would look like this:

GET /studb.cgi?student=bobcostas&pw=sydney HTTP/1.0

Remember that the browser does URLencoding on the string before sending them as part of the query, so if the user entered the id "Bob Costas" the query would look like this:

GET /studb.cgi?student=Bob+Costas&pw=sydney HTTP/1.0

Now consider allowing an Instructor to update the grades database via the web. Now we need to add a couple of things to the system:

We can provide a different login screen for the instructor login, the id and password can be sent to a completely different CGI program. This new CGI program now needs to allow the instructor to enter a student id, and to then get back a form that allows the instructor to enter grades for that student. Here is a picture of this part of the system:

Think about the HTML that is required by this system. An initial login form is required (we've already looked at one possible form for this). The form the instructor uses to enter a student ID is pretty simple, but the form that supports making changes to the database is obviously a dynamic document since it includes the students current grades.