Many CGI programs use HTML forms to gather user input. This chapter summarizes the tags used to produce forms, and then gives an example of how to use them.
See Chapter 3, HTML Tags, for a more complete listing of all available HTML tags.
Forms are comprised of one or more text-input boxes, clickable radio buttons, multiple-choice checkboxes, and even pull-down menus and clickable images, all placed inside the <form> tag. Within a form, you may also put regular body content, including text and images.
You place a form anywhere inside the body of an HTML document with its elements enclosed by the <form> tag and its respective end tag </form>. All of the form elements within a <form> tag comprise a single form. The browser sends all of the values of these elements--blank, default, or user-modified--when the user submits the form to the server.
The required action attribute for the <form> tag gives the URL of the application that is to receive and process the form's data. A typical <form> tag with the action attribute looks like this:
<form action="http://www.ora.com/cgi-bin/update"> ... </form>
The example URL tells the browser to contact the server named www.ora.com and pass along the user's form values to the application named update located in the cgi-bin directory.
The browser specially encodes the form's data before it passes that data to the server so it does not become scrambled or corrupted during the transmission. It is up to the server to either decode the parameters or to pass them, still encoded, to the application.
The standard encoding format is the media type named application/x-www-form-urlencoded. You can change that encoding with the optional enctype attribute in the <form> tag. If you do elect to use an alternative encoding, the only other supported format is multipart/form-data.
The standard encoding--application/x-www-form-urlencoded--converts any spaces in the form values to a plus sign (+), nonalphanumeric characters into a percent sign (%) followed by two hexadecimal digits that are the ASCII code of the character, and the line breaks in multiline form data into %0D%0A. (See Chapter 9, CGI Overview, for more information on URL encoding.)
The multipart/form-data encoding encapsulates the fields in the form as several parts of a single MIME-compatible compound document.
The other required attribute for the <form> tag sets the method by which the browser sends the form's data to the server for processing. There are two ways: the POST method and the GET method. See Chapter 9, CGI Overview for more information on GET and POST.
Use the <input> tag to define any one of a number of common form elements, including text fields, multiple-choice lists, clickable images, and submission buttons. Although there are many attributes for this tag, only the type and name attributes are required for each element (only type for a submission button). Each type of input element uses only a subset of the allowed attributes. Additional <input> attributes may be required based upon which type of form element you specify.
You select the type of element to include in the form with the <input> tag's required type attribute, and you name the field (used during the form-submission process to the server) with the name attribute.
The most useful (as well as the most common) form-input element is the text-entry field. A text-entry field appears in the browser window as an empty box on one line and accepts a single line of user input that becomes the value of the element when the user submits the form to the server. To create a text entry field inside a form in your HTML document, set the type of the <input> form element to text. You must include a name attribute as well.
The size and maxlength attributes allow you to dictate the width, in characters, of the text-input display box, and how many total characters to accept from the user, respectively. The default value for size is dependent upon the browser; the default value for maxlength is unlimited.
A text-entry field is usually blank until the user types something into it. You may, however, specify an initial default value for the field with the value attribute.
Password fields behave just like a regular text field in a form, except that the user-typed characters don't appear onscreen. Rather, the browser obscures the characters in a masked text to keep such things as passwords and other sensitive codes from prying eyes.
To create a password field, set the value of the type attribute to password. All other attributes and semantics of the conventional text field apply to the masked field. Note that a masked text field is not all that secure, since the browser transmits it unencrypted when the form is submitted to the server.
The file-selection form field (introduced by Netscape Navigator) lets users select a file stored on their computer and send it to the server when they submit the form. Browsers present the file-selection form field to the user like other text fields, but it's accompanied by a button labeled "Browse." Users either type the pathname directly as text into the field or, with the Browse option, select the name of a locally stored file from a system-specific dialog box.
Create a file-selection field in a form by setting the value of the type attribute to file. Like other text fields, the size and maxlength of a file-selection field should be set to appropriate values.
The checkbox element gives users a way to quickly and easily select or deselect an item in your form. Checkboxes may also be grouped to create a set of choices, any of which may be selected or deselected by the user.
Create individual checkboxes by setting the type attribute for each <input> tag to checkbox. Include the required name and value attributes. If the item is selected, it will contribute a value when the form is submitted. If it is not selected, that element will not contribute a value. The optional checked attribute (no value) tells the browser to display a checked checkbox and include the value when submitting the form to the server unless the user specifically clicks the mouse to deselect (uncheck) the box.
The browsers includes the value of selected (checked) checkboxes with other form parameters when they are submitted to the server. The value of the checked checkbox is the text string you specify in the required value attribute.
By giving several checkboxes the same name attribute value, you create a group of checkbox elements. The browser automatically collects the values of a checkbox group and submits their selected values as a comma-separated string to the server, significantly easing server-side form processing.
Radio buttons are similar in behavior to checkboxes, except only one in the group may be selected by the user. Create a radio button by setting the type attribute of the <input> element to radio. Like checkbox elements, radio buttons each require a name and value attribute; buttons with the same name value are members of a group. One of them may be initially checked by including the checked attribute with that element. If no element in the group is checked, the browser automatically checks the first element in the group.
You should give each radio button element a different value, so the server can sort them out after submission of the form.
The submit button (<input type=submit>) does what its name implies, setting in motion the form's submission to the server from the browser. You may have more than one submit button in a form. You may also include name and value attributes with a submit button.
With the simplest submit button (that is, without a name or value attribute), the browser displays a small rectangle or oval with the default label "Submit." Otherwise, the browser will label the button with the text you include with the tag's value attribute. If you provide a name attribute, the value attribute for the submit button will be added to the parameter list the browser sends along to the server.
The reset type of form <input> button is nearly self-explanatory: it lets the user reset--erase or set to some default value--all elements in the form. By default, the browser displays a reset button with the label "Reset" or "Clear." You can change that by specifying a value attribute with your own button label.
With the image type of <input> form element, you create a custom button, one that is a "clickable" image. It's a special button made out of your specified image that, when clicked by the user, tells the browser to submit the form to the server, and includes the x,y coordinates of the mouse pointer in the form's parameter list. Image buttons require a src attribute with the URL of the image file, and you can include a name attribute. You may also include the align attribute to control image alignment within the current line of text, much like the align attribute for the <img> tag.
The last type of form <input> element we describe in this chapter is a way to embed information into your forms that cannot be ignored or altered by the browser or user. Rather, the <input type=hidden> tag's required name and value attributes automatically get included in the submitted form's parameter list. These serve to "label" the form and can be invaluable when sorting out different forms or form versions from a collection of submitted and saved forms.
The <textarea> tag creates a multiline text-entry area in the user's browser display. In it, the user may type a nearly unlimited number of lines of text. When the form is submitted, the browser sends the text along with the name specified by the required name attribute.
You may include plain text between the <textarea> tag and its end tag </textarea>. The browser uses that text as the default value for the text area.
You can control the dimensions of a multiline text area by defining the cols and rows attributes for the visible rectangular area set aside by the browser for multiline input.
Normally, text typed in the text area by the user is transmitted to the server exactly as typed, with lines broken only where the user pressed the Enter key. With the wrap attribute set to virtual, the text is wrapped within the text area for presentation to the user, but the text is transmitted to the server as if no wrapping had occurred, except where the user pressed the Enter key. With the wrap attribute set to physical, the text is wrapped within the text area and is transmitted to the server as if the user had actually typed it that way. To obtain the default action, set the wrap attribute to off.
Checkboxes and radio buttons give you powerful means for creating multiple-choice questions and answers, but they can lead to long forms that are tedious to write and put a fair amount of clutter onscreen. The <select> tag gives you two compact alternatives: pulldown menus and scrolling lists.
By placing a list of <option> tagged items inside the <select> tag of a form, you create a pull-down menu of choices.
As with other form tags, the name attribute is required and used by the browser when submitting the <select> choices to the server. Unlike radio buttons, however, no item is preselected, so if the user doesn't select any, no values are sent to the server when the form is submitted. Otherwise, the browser submits the selected item or collects multiple selections, each separated with commas, into a single parameter list and includes the name attribute when submitting <select> form data to the server.
To allow more than one option selection at a time, add the multiple attribute to the <select> tag. This causes the <select> to behave like an <input type=checkbox> element. If multiple is not specified, exactly one option can be selected at a time, just like a group of radio buttons.
The size attribute determines how many options are visible to the user at one time. The value of size should be a positive integer. If size is set to 1 and multiple is not specified, the <select> list is typically implemented as a pop-up menu, while values greater than 1 or specifying the multiple attribute cause the <select> to be displayed as a scrolling list.
Use the <option> tag to define each item within a <select> form element. The browser displays the <option> tag's contents as an element within the <select> tag's menu or scrolling list, so the content must be plain text only, without any other sort of markup.
Use the value attribute to set a value for each option the browser sends to the server if that option is selected by the user. If the value attribute has not been specified, the value of the option is set to the content of the <option> tag.
By default, all options within a multiple-choice <select> tag are unselected. Include the selected attribute (no value) inside the <option> tag to preselect one or more options, which the user may then deselect. Single-choice <select> tags will preselect the first option if no option is explicitly preselected.