Forms

A form is a template for a form data set and an associated method and action URI. A form data set is a sequence of name/value pair fields. The names are specified on the NAME attributes of form input elements, and the values are given initial values by various forms of markup and edited by the user. The resulting form data set is used to access an information service as a function of the action and method.

Forms elements can be mixed in with document structuring elements. For example, a PRE element may contain a FORM element, or a FORM element may contain lists which contain INPUT elements. This gives considerable flexibility in designing the layout of forms.

Form processing is a level 2 feature.

Form Elements

Form: FORM

The FORM element contains a sequence of input elements, along with document structuring elements. The attributes are:

ACTION

specifies the action URI for the form. The action URI of a form defaults to the base URI of the document (see section Hyperlinks).

METHOD

selects a method of accessing the action URI. The set of applicable methods is a function of the scheme of the action URI of the form. See section Query Forms: METHOD=GET and section Forms with Side-Effects: METHOD=POST.

ENCTYPE

specifies the media type used to encode the name/value pairs for transport, in case the protocol does not itself impose a format. See section The form-urlencoded Media Type.

Input Field: INPUT

The INPUT element represents a field for user input. The TYPE attribute discriminates between several variations of fields.

The INPUT element has a number of attributes. The set of applicable attributes depends on the value of the TYPE attribute.

Text Field: INPUT TYPE=TEXT

The default vaule of the TYPE attribute is `TEXT', indicating a single line text entry field. (Use the TEXTAREA element for multi-line text fields.)

Required attributes are:

NAME

name for the form field corresponding to this element.

The optional attributes are:

MAXLENGTH

constrains the number of characters that can be entered into a text input field. If the value of MAXLENGTH is greater the the value of the SIZE attribute, the field should scroll appropriately. The default number of characters is unlimited.

SIZE

specifies the amount of display space allocated to this input field according to its type. The default depends on the user agent.

VALUE

The initial value of the field.

For example:

<p>Street Address: <input name=street><br>
Postal City code: <input name=city size=16 maxlength=16><br>
Zip Code: <input name=zip size=10 maxlength=10 value="99999-9999"><br>

Password Field: INPUT TYPE=PASSWORD

An INPUT element with `TYPE=PASSWORD' is a text field as above, except that the value is obscured as it is entered. (see also: section Security Considerations).

For example:

<p>Name: <input name=login> Password: <input type=password name=passwd>

Check Box: INPUT TYPE=CHECKBOX

An INPUT element with `TYPE=CHECKBOX' represents a boolean choice. A set of such elements with the same name represents an n-of-many choice field. Required attributes are:

NAME

symbolic name for the form field corresponding to this element or group of elements.

VALUE

The portion of the value of the field contributed by this element.

Optional attributes are:

CHECKED

indicates that the initial state is on.

For example:

<p>What flavors do you like?
<input type=checkbox name=flavor value=vanilla>Vanilla<br>
<input type=checkbox name=flavor value=strawberry>Strawberry<br>
<input type=checkbox name=flavor value=chocolate checked>Chocolate<br>

Radio Button: INPUT TYPE=RADIO

An INPUT element with `TYPE=RADIO' represents a boolean choice. A set of such elements with the same name represents a 1-of-many choice field. The NAME and VALUE attributes are required as for check boxes. Optional attributes are:

CHECKED

indicates that the initial state is on.

At all times, exactly one of the radio buttons in a set is checked. If none of the INPUT elements of a set of radio buttons specifies `CHECKED', then the user agent must check the first radio button of the set initially.

For example:

<p>Which is your favorite?
<input type=radio name=flavor value=vanilla>Vanilla<br>
<input type=radio name=flavor value=strawberry>Strawberry<br>
<input type=radio name=flavor value=chocolate>Chocolate<br>

Image Pixel: INPUT TYPE=IMAGE

An INPUT element with `TYPE=IMAGE' specifies an image resource to display, and allows input of two form fields: the x and y coordinate of a pixel chosen from the image. The names of the fields are the name of the field with `.x' and `.y' appended. `TYPE=IMAGE' implies `TYPE=SUBMIT' processing; that is, when a pixel is chosen, the form as a whole is submitted.

The NAME attribute is required as for other input fields. The SRC attribute is required and the ALIGN is optional as for the IMG element (see section Image: IMG).

For example:

<p>Choose a point on the map:
<input type=image name=point src="map.gif">

Hidden Field: INPUT TYPE=HIDDEN

An INPUT element with `TYPE=HIDDEN' represents a hidden field.The user does not interact with this field; instead, the VALUE attribute specifies the value of the field. The NAME and VALUE attributes are required.

For example:

<input type=hidden name=context value="l2k3j4l2k3j4l2k3j4lk23">

Submit Button: INPUT TYPE=SUBMIT

An INPUT element with `TYPE=SUBMIT' represents an input option, typically a button, that instructs the user agent to submit the form. Optional attributes are:

NAME

indicates that this element contributes a form field whose value is given by the VALUE attribute. If the NAME attribute is not present, this element does not contribute a form field.

VALUE

indicates a label for the input (button).

You may submit this request internally:
<input type=submit name=recipient value=internal><br>
or to the external world:
<input type=submit name=recipient value=world>

Reset Button: INPUT TYPE=RESET

An INPUT element with `TYPE=RESET' represents an input option, typically a button, that instructs the user agent to reset the form's fields to their initial states. The VALUE attribute, if present, indicates a label for the input (button).

When you are finished, you may submit this request:
<input type=submit><br>
You may clear the form and start over at any time: <input type=reset>

Selection: SELECT

The SELECT element constrains the form field to an enumerated list of values. The values are given in OPTION elements. Attributes are:

MULTIPLE

indicates that more than one option may be included in the value.

NAME

specifies the name of the form field.

SIZE

specifies the number of visible items. Select fields of size one are typically pop-down menus, whereas select fields with size greater than one are typically lists.

For example:

<SELECT NAME="flavor">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION value="RumRasin">Rum and Raisin
<OPTION selected>Peach and Orange
</SELECT>

The initial state has the first option selected, unless a SELECTED attribute is present on any of the OPTION elements.

Option: OPTION

The Option element can only occur within a Select element. It represents one choice, and has the following attributes:

SELECTED

Indicates that this option is initially selected.

VALUE

indicates the value to be returned if this option is chosen. The field value defaults to the content of the OPTION element.

The content of the OPTION element is presented to the user to represent the option. It is used as a returned value if the VALUE attribute is not present.

Text Area: TEXTAREA

The TEXTAREA element represents a multi-line text field. Attributes are:

COLS

the number of visible columns to display for the text area, in characters.

NAME

Specifies the name of the form field.

ROWS

The number of visible rows to display for the text area, in characters.

For example:

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

The content of the TEXTAREA element is the field's initial value.

Typically, the ROWS and COLS attributes determine the visible dimension of the field in characters. The field is typically rendered in a fixed-width font. HTML user agents should allow text to extend beyond these limits by scrolling as needed.

Form Submission

An HTML user agent begins processing a form by presenting the document with the fields in their initial state. The user is allowed to modify the fields, constrained by the field type etc. When the user indicates that the form should be submitted (using a submit button or image input), the form data set is processed according to its method, action URI and enctype.

When there is only one single-line text input field in a form, the user agent should accept Enter in that field as a request to submit the form.

The form-urlencoded Media Type

The default encoding for all forms is `application/x-www-form-urlencoded'. A form data set is represented in this media type as follows:

1. The form field names and values are escaped: space characters are replaced by `+', and then reserved characters are escaped as per [URL]; that is, non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks, as in multi-line text field values, are represented as CR LF pairs, i.e. `%0D%0A'.
2. The fields are listed in the order they appear in the document with the name separated from the value by `=' and the pairs separated from each other by `&'. Fields with null values may be omitted. In particular, unselected radio buttons and checkboxes should not appear in the encoded data, but hidden fields with VALUE attributes present should. (26)

Query Forms: METHOD=GET

If the processing of a form is idempotent (i.e. it has no lasting observable effect on the state of the world), then the form method should be `GET'. Many database searches have no visible side-effects and make ideal applications of query forms.

To process a form whose action URL is an HTTP URL and whose method is `GET', the user agent starts with the action URI and appends a `?' and the form data set, in `application/x-www-form-urlencoded' format as above. The user agent then traverses the link to this URI just as if it were an anchor (see section Activation of Hyperlinks). (27)

Forms with Side-Effects: METHOD=POST

If the service associated with the processing of a form has side effects (for example, modification of a database or subscription to a service), the method should be `POST'.

To process a form whose action URL is an HTTP URL and whose method is `POST', the user agent conducts an HTTP POST transaction using the action URI, and a message body of type `application/x-www-form-urlencoded' format as above. The user agent should display the response from the HTTP POST interaction just as it would display the response from an HTTP GET above.

Example Form Submission: Questionnaire Form

Consider the following document:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<title>Sample of HTML Form Submission</title>
<H1>Sample Questionnaire</H1>
<P>Please fill out this questionnaire:
<FORM METHOD="POST" ACTION="http://www.w3.org/sample">
<P>Your name: <INPUT NAME="name" size="48">
<P>Male <INPUT NAME="gender" TYPE=RADIO VALUE="male">
<P>Female <INPUT NAME="gender" TYPE=RADIO VALUE="female">
<P>Number in family: <INPUT NAME="family" TYPE=text>
<P>Cities in which you maintain a residence:
<UL>
<LI>Kent <INPUT NAME="city" TYPE=checkbox VALUE="kent">
<LI>Miami <INPUT NAME="city" TYPE=checkbox VALUE="miami">
<LI>Other <TEXTAREA NAME="other" cols=48 rows=4></textarea>
</UL>
Nickname: <INPUT NAME="nickname" SIZE="42">
<P>Thank you for responding to this questionnaire.
<P><INPUT TYPE=SUBMIT> <INPUT TYPE=RESET>
</FORM>

The initial state of the form data set is:

name

""

gender

"male"

family

""

other

""

nickname

""

Note that the radio input has an initial value, while the checkbox has none.

The user might edit the fields and request that the form be submitted. At that point, suppose the values are:

name

"John Doe"

gender

"male"

family

"5"

city

"kent"

city

"miami"

other

"abc\ndef"

nickname

"J&D"

The user agent then conducts an HTTP POST transaction using the URI `http://www.w3.org/sample'. The message body would be (ignore the line break):

name=John+Doe&gender=male&family=5&city=kent&city=miami&
other=abc%0D%0Adef&nickname=J%26D