CGI Programming Guide - [Chapter 4] Forms and CGI

As we discussed briefly in Chapter 4, Forms and CGI forms are generally used for two purposes: data collection and interactive communication. You can conduct surveys or polls, and present registration or online ordering information through the use of forms. They are also used to create an interactive medium between the user and the Web server. For example, a form can ask the user to select a document out of a menu, whereby the server returns the chosen document.

The main advantage of forms is that you can use them to create a front end for numerous gateways (such as databases or other information servers) that can be accessed by any client without worrying about platform dependency. On the other hand, there are some shortcomings with the current implementation:

4.1 HTML Tags

A form consists of two distinct parts: the HTML code and the CGI program. HTML tags create the visual representation of the form, while the CGI program decodes (or processes) the information contained within the form. Before we look at how CGI programs process form information, let's understand how a form is created. In this section, we'll cover the form tags and show examples of their use.

The FORM Tag

Here is the beginning of a simple form:

<FORM ACTION="/cgi-bin/program.pl" METHOD="POST">

The <FORM> tag starts the form. A document can consist of multiple forms, but forms cannot be nested; a form cannot be placed inside another form.

The two attributes within the <FORM> tag ( ACTION and METHOD) are very important. The ACTION attribute specifies the URL of the CGI program that will process the form information. You are not limited to using a CGI program on your server to decode form information; you can specify a URL of a remote host if a program that does what you want is available elsewhere.

The METHOD attribute specifies how the server will send the form information to the program. POST sends the data through standard input, while GET passes the information through environment variables. If no method is specified, the server defaults to GET. Both methods have their own advantages and disadvantages, which will be covered in detail later in the chapter.

In addition, another attribute, ENCTYPE, can be specified. This represents the MIME type (or encoding scheme) for the POST data, since the information is sent to the program as a data stream. Currently, only two ENCTYPES are allowed: application/x-www-form-urlencoded and multipart/form-data. If one is not specified, the browser defaults to application/x-www-form-urlencoded. Appendix D, CGI Lite, shows an example of using multipart/form-data, while this chapter is devoted to application/x-www-form-urlencoded.

Text and Password Fields

Most form elements are implemented using the <INPUT> tag. The TYPE attribute to <INPUT> determines what type of input is being requested. Several different types of elements are available: text and password fields, radio buttons, and checkboxes. The following lines are examples of simple text input.

Name: <INPUT TYPE="text" NAME="user" SIZE=40><BR>
Age: <INPUT TYPE="text" NAME="age"  SIZE=3 MAXLENGTH=3><BR>
Password: <INPUT TYPE="password" NAME="pass" SIZE=10><BR>

In this case, two text fields and one password field are created using the "text" and "password" arguments, respectively. The password field is basically the same as a text field except the characters entered will be displayed as asterisks or bullets. If you skip the TYPE attribute, a text field will be created by default.

The NAME attribute defines the name of the particular input element. It is not displayed by the browser, but is used to label the data when transferred to the CGI program. For example, the first input field has a NAME="user" attribute. If someone types "andy" into the first input field, then part of the data sent by the browser will read:

    user=andy

The CGI program can later retrieve this information (as we talked about briefly in Chapter 2, Input to the Common Gateway Interface, and will discuss in more detail later in this chapter) and parse it as needed.

The optional VALUE attribute can be used to insert an initial "default" value into the field. This string can be overwritten by the user.

Other optional attributes are SIZE and MAXLENGTH. SIZE is the physical size of the input element; the field will scroll if the input exceeds the size. The default size is 20 characters. MAXLENGTH defines the maximum number of characters that will be accepted by the browser; by default there is no limit.

In the following line, the initial text field size is expanded to 40 characters, the maximum length is specified as 40 as well (so the field will not scroll), and the initial value string is "Shishir Gundavaram."

<INPUT TYPE="text"  NAME="user"  SIZE=40 MAXLENGTH=40 VALUE="Shishir Gundavaram"  >

Before we move on, there is still another type of text field. It is called a "hidden" field and allows you to store information in the form. The client will not display the field. For example:

<INPUT TYPE="hidden" NAME="publisher" VALUE="ORA">

Hidden fields are most useful for transferring information from one CGI application to another. See Chapter 8, Multiple Form Interaction, for an example of using hidden fields.

Submit and Reset Buttons

Two more important "types" of the <INPUT> tag are Submit and Reset.

<INPUT TYPE="submit" VALUE="Submit the form">
<INPUT TYPE="reset"  VALUE="Clear all fields">

Nearly all forms offer Submit and Reset buttons. The Submit button sends all of the form information to the CGI program specified by the ACTION attribute. Without this button, the form will be useless since it will never reach the CGI program.

Browsers supply a default label on Submit and Reset buttons (generally, the unimaginative labels "Submit" and "Reset," of course). However, you can override the default labels using the VALUE attribute.

You can have multiple Submit buttons:

<INPUT TYPE="submit" NAME="option" VALUE="Option 1">
<INPUT TYPE="submit" NAME="option" VALUE="Option 2">

If the user clicked on "Option 1", the CGI program would get the following data:

option=Option 1

You can also have images as buttons:

    <INPUT TYPE="image" SRC="/icons/button.gif" NAME="install" 
            VALUE="Install Program">

When you click on an image button, the browser will send the coordinates of the click:

install.x=250&install.y=20

Note that each field information is delimited by the " &" character. We will discuss this in detail later in the chapter. On the other hand, if you are using a text browser, and you select this button, the browser will send the following data:

install=Install Program

The Reset button clears all the information entered by the user. Users can press Reset if they want to erase all their entries and start all over again.

Figure 4.1 shows how the form will look in Netscape Navigator.

Figure 4.1: Form with text input fields

[Graphic: Figure 4-1]

Radio Buttons and Checkboxes

Radio buttons and checkboxes are typically used to present the user with several options.

A checkbox creates square buttons (or boxes) that can be toggled on or off. In the example below, it is used to create four square checkboxes.

    <FORM ACTION="/cgi-bin/program.pl" METHOD="POST">
Which movies do you want to order: <BR>
Amadeus <INPUT TYPE="checkbox" NAME="amadeus">
The Last Emperor <INPUT TYPE="checkbox" NAME="emperor">
Gandhi <INPUT TYPE="checkbox" NAME="gandhi">
Schindler's List <INPUT TYPE="checkbox" NAME="schindler">
<BR>

If a user toggles a checkbox "on" and then submits the form, the browser uses the value "on" for that variable name. For example, if someone clicks on the "Gandhi" box in the above example, the browser will send:

gandhi=on

You can override the value "on" using the VALUE attribute:

Gandhi <INPUT TYPE="checkbox" NAME="gandhi" VALUE="yes">

Now when the "Gandhi" checkbox is checked, the browser will send:

gandhi=yes

One checkbox is not related to another. Any number of them can be checked at the same time. A radio button differs from a checkbox in that only one radio button can be enabled at a time. For example:

How do you want to pay for this product: <BR>
Master Card: <INPUT TYPE="radio" NAME="payment" VALUE="MC" CHECKED><BR>
Visa: <INPUT TYPE="radio" NAME="payment" VALUE="Visa"><BR>
American Express: <INPUT TYPE="radio" NAME="payment" VALUE="AMEX"><BR>
Discover: <INPUT TYPE="radio" NAME="payment" VALUE="Discover"><BR>
</FORM>

Here are a few guidelines for making a radio button work properly:

All options must have the same NAME (in this example, "payment"). This is how the browser knows that they should be grouped together, and can therefore ensure that only one radio button using the same NAME can be selected at a time.
Whereas with checkboxes supplying a different VALUE is only a matter of taste, with radio buttons different VALUEs are crucial to getting meaningful results. Without a specified VALUE, no matter which item is checked, the browser will assign the string "on" to the "payment" NAME variable. The CGI program therefore has no way to know which item was actually checked. So each item in a radio button needs to be assigned a different VALUE to make sure that the CGI program knows which one was selected.

For both radio buttons and checkboxes, the CHECKED attribute determines whether the item should be enabled by default. In the radio button example, the "Master Card" option is given a CHECKED value, effectively making it the default value.

Figure 4.2 shows how this example will be rendered by the browser.

Figure 4.2: Form with radio buttons and checkboxes

[Graphic: Figure 4-2]

Menus and Scrolled Lists

Menus and scrolled lists are generally used to present a large number of options or choices to the user. The following is an example of a menu:

<FORM ACTION="/cgi-bin/program.pl" METHOD="POST">
Choose a method of payment: 
<SELECT NAME="card" SIZE=1>
<OPTION SELECTED>Master Card
<OPTION>Visa
<OPTION>American Express
<OPTION>Discover
</SELECT>

Option menus and scrolled lists are created using the SELECT tag, which has an opening and a closing tag. The SIZE attribute determines if a menu or a list is displayed. A value of 1 produces a menu, and a value greater than 2 produces a scrolled list, in which case the number represents the number of items that will be visible at one time.

A selection in a menu or scrolled list is added using the OPTION tag. The SELECTED attribute to OPTION allows you to set a default selection.

Now for an example of a scrolled list (a list with a scrollbar):

<SELECT NAME="books" SIZE=3 MULTIPLE>
<OPTION SELECTED>TCP/IP Network Administration
<OPTION>Linux Network Administrators Guide
<OPTION>DNS and BIND
<OPTION>Computer Security Basics
<OPTION>System Performance Tuning
</SELECT>
</FORM>

The example above creates a scrolled list with three visible items and the ability to select multiple options. (The MULTIPLE attribute specifies that more than one item can be selected.)

Figure 4.3 shows what the menus and scrolled list look like.

Figure 4.3: Form with menus and scrolled lists

[Graphic: Figure 4-3]

Multiline Text Fields

You must have seen numerous guestbooks on the Web that ask for your comments or opinions, where you can enter a lot of information. This is accomplished by using a multiline text field. Here is an example:

 
 <FORM ACTION="/cgi-bin/program.pl" METHOD="POST">
<TEXTAREA ROWS=10 COLS=40 NAME="comments">
</TEXTAREA>

This creates a scrolled text field with 10 rows and 40 columns. (10 rows and 40 columns designates only the visible text area; the text area will scroll if the user types further).

Notice that you need both the beginning <TEXTAREA> and the ending </TEXTAREA> tags. You can enter default information between these tags.

<TEXTAREA ROWS=10 COLS=40 NAME="comments_2">
This is some default information.
Some more...
And some more...
</TEXTAREA>
</FORM>

You have to remember that newlines (or carriage returns) are not ignored in this field--unlike HTML. In the preceding example, the three separate lines will be displayed just as you typed them.

The multiline examples will be rendered by the browser as shown in Figure 4.4.

Figure 4.4: Form with multiline text input

[Graphic: Figure 4-4]

Quick Reference to Form Tags

Before we get going, here's a short list of all the available form tags:

Table 4.1: Form Tags
Form Tag	Description
`<FORM ACTION="/cgi-bin/prog.pl" METHOD="POST">`	Start the form
`<INPUT TYPE="text" NAME="name" VALUE="value" SIZE="size">`	Text field
`<INPUT TYPE="password" NAME="value" VALUE="value" SIZE="size">`	Password field
`<INPUT TYPE="hidden" NAME="name" VALUE="value">`	Hidden field
`<INPUT TYPE="checkbox" NAME="name" VALUE="value">`	Checkbox
`<INPUT TYPE="radio" NAME="name" VALUE="value">`	Radio button
`<SELECT NAME="name" SIZE=1> <OPTION SELECTED>One <OPTION>Two : </SELECT>`	Menu
`<SELECT NAME="name" SIZE=n MULTIPLE>`	Scrolled list
`<TEXTAREA ROWS=yy COLS=xx NAME="name"> . . </TEXTAREA>`	Multiline text fields
`<INPUT TYPE="submit" VALUE="Message!"> <INPUT TYPE="submit" NAME="name" VALUE="value"> <INPUT TYPE="image" SRC="/image" NAME="name" VALUE="value">`	Submit buttons
`<INPUT TYPE="reset" VALUE="Message!">`	Reset button
`</FORM>`	Ends form