RISC DISC 2/RISC_DISC_2.iso/the_web/documents/spec/html_spec/forms_sgm

Text File | 1995-08-04 | 14.4 KB | 447 lines

<!-- $Id -->
<h1 id=forms>Forms

<p>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 <attr/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.

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

<p> Form processing is a level 2 feature.

<h2>Form Elements

<h3>Form: FORM

<p>The <tag/FORM/ element contains a sequence of input elements, along
with document structuring elements. The attributes are:

<tl>
<tli>ACTION: specifies the action URI for the form. The action URI of
a form defaults to the base URI of the document (see <hdref
refid=hyperlink>).

<tli>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 <hdref refid=queryf> and <hdref refid=formpost>.

<tli>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 <hdref refid=urlencode>.

</tl>

<h3 id=input>Input Field: INPUT

<p>The <tag/INPUT/ element represents a field for user input. The
<attr/TYPE/ attribute discriminates between several variations of
fields.

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

<h4>Text Field: INPUT TYPE=TEXT

<p>The default vaule of the <attr/TYPE/ attribute is <code/TEXT/,
indicating a single line text entry fields. (Use the <tag/TEXTAREA/
element for multi-line text fields.)

<p>Required attributes are:

<tl>
<tli>NAME: name for the form field corresponding to this
element.
</tl>

The optional attriubtes are:

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

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

<tli>VALUE: The initial value of the field.
</tl>


<p> For example:

<listing><![CDATA[
<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>
]]></listing>

<h4>Password Field: INPUT TYPE=PASSWORD

An <tag/INPUT/ element with <code/TYPE=PASSWORD/ is a text field as
above, except that the value is obscured as it is entered. (see also:
<hdref refid=security>).

<p> For example:

<listing><![CDATA[
<p>Name: <input name=login> Password: <input type=password name=passwd>
]]></listing>

<h4>Check Box: INPUT TYPE=CHECKBOX

<p> An <tag/INPUT/ element with <code/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:

<tl>
<tli>NAME: symbolic name for the form field corresponding to this
element or group of elements.

<tli>VALUE: The portion of the value of the field contributed by this
element.
</tl>

<p>Optional attributes are:

<tl>
<tli>CHECKED: indicates that the initial state is on.
</tl>


<p>For example:

<listing><![CDATA[
<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>
]]></listing>

<h4>Radio Button: INPUT TYPE=RADIO

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

<tl>
<tli>CHECKED: indicates that the initial state is on.
</tl>

<p>At all times, exactly one of the radio buttons in a set is
checked. If none of the <tag/INPUT/ elements of a set of radio buttons
specifies <code/CHECKED/, then the user agent must check the first
radio button of the set initially.

<p>For example:

<listing><![CDATA[
<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>
]]></listing>

<h4>Image Pixel: INPUT TYPE=IMAGE

<p>An <tag/INPUT/ element with <code/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 <code/.x/ and <code/.y/
appended. <code/TYPE=IMAGE/ implies <code/TYPE=SUBMIT/ processing;
that is, when a pixel is chosen, the form as a whole is submitted.

<p>The <attr/NAME/ attribute is required as for other input
fields. The <attr/SRC/ attribute is required and the <attr/ALIGN/ is
optional as for the <tag/IMG/ element (see <hdref refid=img>).

<p>For example:

<listing><![CDATA[
<p>Choose a point on the map:
<input type=image name=point src="map.gif">
]]></listing>

<h4>Hidden Field: INPUT TYPE=HIDDEN

<p>An <tag/INPUT/ element with <code/TYPE=HIDDEN/ represents a hidden
field.The user does not interact with this field; instead, the
<attr/VALUE/ attribute specifies the value of the field. The
<attr/NAME/ and <attr/VALUE/ attributes are required.

<p>For example:

<listing><![CDATA[
<input type=hidden name=context value="l2k3j4l2k3j4l2k3j4lk23">
]]></listing>

<h4>Submit Button: INPUT TYPE=SUBMIT

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

<tl>
<tli>NAME: indicates that this element contributes a form field whose
value is given by the <attr/VALUE/ attribute. If the <attr/NAME/
attribute is not present, this element does not contribute a form
field.

<tli>VALUE: indicates a label
for the input (button).
</tl>

<listing><![CDATA[
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>
]]></listing>

<h4>Reset Button: INPUT TYPE=RESET

An <tag/INPUT/ element with <code/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 <attr/VALUE/ attribute, if
present, indicates a label for the input (button).

<listing><![CDATA[
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>
]]></listing>

<h3>Selection: SELECT

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

<tl>
<tli>MULTIPLE: indicates that more than one option may be included in
the value.

<tli>NAME: specifies the name of the form field.

<tli>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.

</tl>

<p> For example:

<listing><![CDATA[
<SELECT NAME="flavor">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION value="RumRasin">Rum and Raisin
<OPTION selected>Peach and Orange
</SELECT>
]]></listing>

<p>The initial state has the first option selected, unless a
<attr/SELECTED/ attribute is present on any of the <tag/OPTION/
elements.

<h4>Option: OPTION

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

<tl>
<tli>SELECTED: Indicates that this option is initially selected.

<tli>VALUE: indicates the value to be returned if this
option is chosen. The field value defaults to the content of the
<tag/OPTION/ element.
</tl>

<p>The content of the <tag/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.

<h3>Text Area: TEXTAREA

<p>The <tag/TEXTAREA/ element represents a multi-line text
field. Attributes are:

<tl>
<tli>COLS: the number of visible columns to display for the text area,
in characters.
<tli>NAME: Specifies the name of the form field.
<tli>ROWS: The number of visible rows to display for the text area, in
characters.
</tl>

<p>For example:

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

<p>The content of the <tag/TEXTAREA/ element is the field's initial
value.

<p>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.

<h2>Form Submission

<p> 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.

<p>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.

<h3 id=urlencode>The form-urlencoded Media Type

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

<ol>
<li>The form field names and values are escaped: space characters are
replaced by <code/+/, and then reserved characters are escaped as per
[URL]; that is, non-alphanumeric characters are replaced by
<code/%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. <code/%0D%0A/.

<li>The fields are listed in the order they appear in the document
with the name separated from the value by <code/=/ and the pairs
separated from each other by <code/&/. 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 <attr/VALUE/
attributes present should.
<note>The URI from a query form submission can be used in a normal
anchor style hyperlink. Unfortunately, the use of the <code/&/
character to separate form fields interacts with its use in SGML
attribute values as an entity reference delimiter. For example, the
URI <code><![CDATA[http://host/?x=1&y=2]]></> must be written
<code><![CDATA[<a href="http://host/?x=1&y=2"]]></code> or
<code><![CDATA[<a href="http://host/?x=1&y=2">]]></>.

<p>HTTP server implementors, and in particular, CGI implementors are
encouraged to support the use of <code/;/ in place of <code/&/ to save
users the trouble of escaping <code/&/ characters this way.
</note>
</ol>

<h3 id=queryf>Query Forms: METHOD=GET

<p>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 <code/GET/. Many database searches have no visible
side-effects and make ideal applications of query forms.

<p>To process a form whose action URL is an HTTP URL and whose method
is <code/GET/, the user agent starts with the action URI and appends a
<code/?/ and the form data set, in
<code>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 <hdref refid=traverse>).
<note>
The URL encoding may result in very long URIs, which cause some
historical HTTP server implementations to exhibit defective behavior.
As a result, some HTML forms are written using <code/METHOD=POST/ even
though the form submission has no side-effects.
</note>

<h3 id=formpost>Forms with Side-Effects: METHOD=POST

<p>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 <code/POST/.

<p>To process a form whose action URL is an HTTP URL and whose method
is <code/POST/, the user agent conducts an HTTP POST transaction using
the action URI, and a message body of type
<code>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.


<h3>Example Form Submission: Questionnaire Form

<p>Consider the following document:

<listing><![CDATA[
<!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>
]]></listing>

<p>The initial state of the form data set is:

<tl>
<tli>name: ""
<tli>gender: "male"
<tli>family: ""
<tli>other: ""
<tli>nickname: ""
</tl>

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

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

<tl>
<tli>name: "John Doe"
<tli>gender: "male"
<tli>family: "5"
<tli>city: "kent"
<tli>city: "miami"
<tli>other: "abc\ndef"
<tli>nickname: "J&D"
</tl>

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

<listing><![CDATA[
name=John+Doe&gender=male&family=5&city=kent&city=miami&
other=abc%0D%0Adef&nickname=J%26D
]]></listing>