Appendix B

HTML Forms


CONTENTS

The information in this appendix is a subset of an Internet draft known as Hypertext Transfer Protocol-HTTP/1.0 and is available at

http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-v10-spec-01.html

You can use HTML fill-out forms for questionnaires, hotel reservations, order forms, data entry, and a wide variety of other applications. The form is specified as part of an HTML document. The user fills in the form and then submits it. The user agent then sends the form's contents as designated by the Form element. Typically, this is to an HTTP server, but you also can e-mail form contents for asynchronous processing.

Forms are created by placing Input fields within paragraphs, preformatted text, lists, and tables. This gives you considerable flexibility in designing the layout of forms.

HTML 3.0 supports these kinds of fields:

Future revisions to HTML probably will add support for audio fields, multirow entry of database tables, and extending multiline text fields to support a range of other data types, in addition to plain text. Client-side scripts will provide the means to constrain field values and to add new field types.

Every form must be enclosed within a Form element. Several forms can exist in a single document, but the Form element can't be nested. The browser is responsible for handling the input focus-which field currently will get keyboard input. Many platforms have existing conventions for forms-for example, pressing Tab and Shift+Tab to move the keyboard focus forward and backward between fields and pressing Enter to submit the form.

The submitted contents of the form logically consist of a list of name/value pairs, where the names are given by the Name attributes of the various fields in the form. Each field usually will be given a distinct name. Several radio buttons can share the same name, because this is how you specify that they belong to the same control group; at any time, only one button in the group can be selected.

Form Attributes

The attributes of the HTML Form field-Action, Enctype, Method, and Script-are described in this section.

Action

The Action attribute is a URI specifying the location to which the contents of the form are submitted to elicit a response. If the Action attribute is missing, the URI for the document itself is assumed. The way in which data is submitted varies with the access protocol of the URI and with the values of the Method and Enctype attributes.

Enctype

The Enctype attribute specifies the MIME content type to be used to encode the form's contents. It defaults to this string:

"application/x-www-form-urlencoded"

Method

The Method attribute specifies variations in the protocol used to send the form's contents. It currently is restricted to Get (the default) or Post. This attribute was introduced to inform user agents which HTTP methods the server supports.

Script

You can use the Script attribute to give a URI for a script. The scripting language and the interface with the user agent are not part of the HTML 3.0 specification.

Input Fields

The Input field is used for a wide variety of entry fields within HTML fill-out forms. The Type attribute determines the type of field.

Checkbox Fields

A Checkbox field has two states: Selected and Unselected. Its name/value pair appears in the submitted data only when selected. Checkboxes are used for Boolean attributes. They also can be used for attributes that can take multiple values at the same time. This is represented by a checkbox for each optional value, with the same name for each of the checkboxes. Unselected checkboxes don't appear in the submitted data. Both Name and Value attributes are required for checkboxes. To initialize the checkbox to its selected state, include the Checked attribute. Checkboxes provide an alternative to using the Select element for multiple choice menus.

File Attachments

File attachments enable users to attach one or more files to be submitted with the form's contents. You can use the Accept attribute to specify a comma-separated list of MIME content types. You can use these types to restrict the kinds of files that can be attached to the form. For example,

<input name=pictures type=file accept="image/*">

restricts files to match "image/*" (to registered MIME image types). For Windows-based user agents, the standard suggests that File fields display the name of the last file attached, with the capability to open a File dialog box to view the complete list of files attached so far. The Accept attribute then acts to specify the filter on the list of candidate files.

Hidden Fields

With Hidden fields, no field is presented to the user, but the contents of the field are sent with the submitted form. This value can be used to transmit state information about client/server interaction-for example, a transaction identifier. Hidden fields are needed because HTTP servers don't preserve state information from one request to the next.

Image Fields

Image fields act like Submit buttons but include the location where the user clicked on the image. The image is specified with the SRC attribute.

Password Fields

Password fields are the same as single-line text fields except that each character typed is echoed by a shadow character-an asterisk or the space character. The user can see how many characters have been typed but not what was typed.

Radio Buttons

Radio buttons are suitable for attributes that can take a single value from a set of alternatives. All radio buttons in the same group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Both Name and Value attributes are required for radio buttons. To initialize the radio button to its selected state, include the Checked attribute. Radio buttons offer an alternative to using the Select element for single-choice menus.

Range Fields

Range fields enable the user to pick a numeric value between a lower and an upper bound. You specify the range with the Min and Max attributes, as in

<input name=rating type=range min=1 max=10>

If either the lower or upper bound is a real number, the range is a real value; otherwise, it is restricted to integer values only. You can use the Value attribute to initialize the Range field. It is an error for the value to lie outside the specified range. The default value is midway between the lower and upper limits.

Reset Buttons

After a Reset button is clicked, the form's fields are reset to their specified initial values. The label to be displayed on the button can be specified just as for the Submit button. Likewise, you can use the SRC attribute to specify a graphic.

Scribble on Image Fields

The Scribble on Image fields enable users to scribble with a pointing device (such as a mouse or pen) on top of a predefined image. You specify the image as a URI with the SRC attribute. If the user agent can't display images or can't provide a means for users to scribble on the image, you should treat the field as a Text field. You can use the Value attribute to initialize the Text field for these users. It is ignored when the user agent provides Scribble on Image support.

Single-Line Text Fields

You use single-line text fields to enable users to enter short text strings, such as people's names, numbers, and dates. You can set the visible width of the field in characters with the Size attribute. When using a variable-pitch font, the Size attribute sets the width in en units (half the point size).

Users should be able to enter more than this; the contents of the field should scroll horizontally as needed. You can use the Maxlength attribute to specify the maximum number of characters permitted for the string.

If the Type attribute is missing, the Input element is assumed to be a single-line text field. You use the Name attribute to identify the field when the form's contents are converted to the name/value list.

You use the Value field to initialize the text string. You can use character entities such as accented characters in this string.

Note
Use the Textarea element for multiline text entry fields.

Submit Buttons

After users click the Submit button, the form's data is submitted. You can use the Value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. You can specify a graphic for the Submit button by using the SRC attribute.

The Submit button usually makes no contribution to the submitted data. The exception is when the field includes a Name attribute, in which case the Name and Value attributes are included with the submitted data. This can be used to distinguish which Submit button the user clicked.

Permitted Attributes for the Input Element

The Input element isn't necessarily complex, but it can take a large variety of attributes, and each attribute can have different fields. The different attributes and fields of the Input element are described in this section.

Accept

The Accept attribute is a comma-separated list of MIME content types used to restrict the types of files that can be attached to a form with a File field.

Align

The Align attribute applies only to fields with background images-for example, Scribble, Image, Submit, or Reset fields. It is intended to provide the same positional control as for the Img element. The Align attribute takes the values Top, Middle, or Bottom; this defines whether the top, middle, or bottom of the field should be aligned with the baseline for the text line in which the Input element appears.

For ALIGN=LEFT, the field floats down and over to the current left margin, and subsequent text wraps around the right-hand side of the field. For ALIGN=RIGHT, the field aligns with the current right margin, and text wraps around the left.

Checked

The Checked attribute indicates that a radio button or checkbox should be initialized to its selected state.

Class

The Class attribute is a space-separated list of SGML name tokens and is used to subclass tag names. By convention, Class attributes are interpreted hierarchically, with the most general class on the left and the most specific on the right, with each class separated by a period. You generally use the Class attribute to attach a different style to some element, but you'll also want to use it in cases in which practical Class attributes should be picked on the basis of the element's semantics; this permits other uses, such as restricting searches through documents by matching on element Class attributes. The conventions for choosing Class attributes are outside the scope of this specification.

Disabled

When present, the Disabled attribute should be rendered as normal but is unmodifiable by the user. When practical, the rendering should provide a cue that the attribute is disabled by graying out the text or changing the color of the background.

Error

The Error attribute specifies an error message explaining why the field's current value is incorrect. When this attribute is missing, the field can be assumed to be okay. It is a good idea for user agents to indicate that the field is in error.

ID

ID is an SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Identifiers are name tokens and must be unique within the scope of the current document.

Lang

Lang is one of the ISO standard language abbreviations-for example, en.uk is used for the variation of English spoken in the United Kingdom. Lang can be used by parsers to select language-specific choices for quotation marks, ligatures, hyphenation rules, and so on. The Lang attribute is comprised of the two-letter language code from ISO 639, optionally followed by a period and a two-letter country code from ISO 3166.

Max

The Max attribute is an integer or real number that specifies the upper bound for a Range field.

Maxlength

The Maxlength attribute specifies the maximum number of characters permitted for Text and Password fields.

MD

The MD attribute specifies a message digest or cryptographic checksum for the associated image specified by the SRC attribute. You use it when you want to be sure that the image is indeed the same one the author intended and that it hasn't been modified in any way. For example,

MD="md5:jV2OfH+nnXHU8bnkPAad/mSQlTDZ"

specifies an MD5 checksum encoded as a base-64 character string. The MD attribute generally is allowed for all elements that support URI-based links.

Min

The Min attribute is an integer or real number that specifies the lower bound for a Range field.

Name

The Name attribute provides a character string used to name the field when submitting the form's data. Several fields may share the same name-for example, a group of radio buttons or checkboxes. The name is not case sensitive.

Size

The Size attribute specifies the visible width of a Text or Password field. For fixed-pitch fonts, it specifies the maximum number of characters visible; for variable-pitch fonts, it specifies the width in en units (half the point size).

SRC (Source)

The SRC attribute specifies the URI for an image for use as the background of a Scribble, Image, Submit, or Reset field. Its syntax is the same as that of the Href attribute of the <A> tag.

Type

Type defines the type of the field as one of the following: Text, Password, Checkbox, Radio, Range, File, Scribble, Hidden, Submit, Image, or Reset. It defaults to Text. The attribute value is an SGML name token and, as such, is not case sensitive.

Value

Value is a character string or number used to initialize Text, Range, and Hidden fields.

Textarea

To let users enter more than one line of text, use the Textarea element, as shown in this example:

<TEXTAREA NAME="address" ROWS=64 COLS=6>
HaL Computer Systems
1315 Dell Avenue
Campbell, California 95008
</TEXTAREA>

The text up to the end tag is used to initialize the field's value. The initialization text can contain SGML entities-for accented characters, for example-but otherwise is treated as literal text. This end tag always is required even if the field initially is blank. When submitting a form, the line terminators are implementation-dependent. Servers should be capable of recognizing a carriage return (CR) immediately followed by a line-feed character (LF) or separate CRs and LFs as all signifying the ends of lines. User agents should tolerate the same range of line terminators within the initialization text. In a typical rendering, the Rows and Cols attributes determine the visible dimension of the field in characters. The field is rendered in a fixed-width font. User agents should allow text to grow beyond these limits by scrolling as needed. User agents should wrap words as they are entered, so that the words will fit within the Textarea field. It is also a good idea to provide a means for users to turn this feature off and on.

Note
In the initial design for forms, multiline text fields were supported by the Input element with TYPE=TEXT. Unfortunately, this causes problems for fields with long text values because SGML limits the length of attribute literals. The HTML 2.0 DTD allows for up to 1,024 characters (the SGML default is only 240 characters).

The Textarea tag uses the same attributes as the Input type except for the following additions.

Cols

Cols are the visible number of characters across the field. User agents should allow text to grow beyond these limits by scrolling as needed.

Rows

Rows gives the visible number of text lines shown by the field. User agents should allow text to grow beyond these limits by scrolling as needed.

Select Elements

The Select element is used for single- and multiple-choice menus. It generally is rendered as a drop-down or pop-up menu and offers a more compact alternative to using radio buttons for single-choice menus or checkboxes for multiple-choice menus, as illustrated in this code:

Example:
<SELECT NAME="flavor">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION>Rum and Raisin
<OPTION>Peach and Orange
</SELECT>

This is a single-choice menu. When you want a multiple-choice menu, you need to include the Multiple attribute with the Select element, as in this example:

<SELECT MULTIPLE NAME="flavor">

The Name attribute is used when creating the name/value list describing the form's contents. A name/value pair is contributed for each selected option. The value is taken from the Option element's Value attribute and defaults to the contents of the Option element when the Value attribute is missing.

For single-choice menus, if no option initially is marked as selected, the first item listed is selected. This is inappropriate for multiple-choice menus, though. HTML 3.0 extends the Select element to support graphical menus. This enables you to specify an image for the Select element and hotzones for each of the Option elements. In this way, the same menu can be rendered as a conventional, text-based menu for nongraphical user agents and as a graphical menu for graphical user agents. The image is specified in the same way as for Img elements. This means that you can specify suggested values for the width and height. You also can float the image to the left or right margin and flow other elements around it. You specify the hotzones for Option elements by using the Shape attribute in the same way as for anchor elements.

The Select tag uses the same attributes as the Input type, except for the following additions.

Height

The Height attribute is the optional suggested height for the image. By default, this is given in pixels.

Multiple

The presence of the Multiple attribute denotes that the Select element defines a multiple-choice menu. In its absence, the element defines a single-choice menu.

SRC (Source)

The SRC attribute is used for graphical menus to specify the URI for the image. Its syntax is the same as that of the Href attribute of the <A> tag.

Units

The Units attribute is optional and specifies the units for the Width and Height attributes. It is units=pixels (the default) or units=em (the width of the letter m), which scales with the font size.

Width

The Width attribute is the optional suggested width for the image. By default, this is given in pixels.

The Option Element

The Option element can occur only within a Select element. It represents a possible choice. It can contain only text, together with SGML entities for accented characters. When the form is submitted, the name of the enclosing Select attribute is paired with the Option element's Value attribute to contribute a name/value pair for the selection. Unselected options don't contribute to the form's submitted data. You can initialize the option to its selected state by including the Select attribute. It is an error for more than one option to be selected for single-choice menus.