forms.html
html-spec/specifications/prose/html-4.01/interact/forms.html · 3100 line(s) · html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Forms in HTML documents</title>
<link rel="previous" href="../present/frames.html">
<link rel="next" href="scripts.html">
<link rel="contents" href="../cover.html#toc">
<link rel="stylesheet" type="text/css" href=
"http://www.w3.org/StyleSheets/TR/W3C-REC">
<link rel="STYLESHEET" href="../style/default.css" type="text/css">
</head>
<body>
<div class="navbar" align="center"> <a href="../present/frames.html">
previous</a> <a href="scripts.html">next</a> <a href=
"../cover.html#minitoc">contents</a> <a href="../index/elements.html">
elements</a> <a href="../index/attributes.html">attributes</a> <a
href="../index/list.html">index</a>
<hr></div>
<h1 align="center"><a name="h-17">17</a> <a name="forms">Forms</a></h1>
<div class="subtoc">
<p><strong>Contents</strong></p>
<ol>
<li><a class="tocxref" href="#h-17.1">Introduction to forms</a></li>
<li><a class="tocxref" href="#h-17.2">Controls</a>
<ol>
<li><a class="tocxref" href="#h-17.2.1">Control types</a></li>
</ol>
</li>
<li><a class="tocxref" href="#h-17.3">The <samp class="einst2">FORM</samp>
element</a></li>
<li><a class="tocxref" href="#h-17.4">The <samp class="einst2">INPUT</samp>
element</a>
<ol>
<li><a class="tocxref" href="#h-17.4.1">Control types created with
INPUT</a></li>
<li><a class="tocxref" href="#h-17.4.2">Examples of forms containing INPUT
controls</a></li>
</ol>
</li>
<li><a class="tocxref" href="#h-17.5">The <samp class="einst2">BUTTON</samp>
element</a></li>
<li><a class="tocxref" href="#h-17.6">The <samp class="einst2">SELECT</samp>,
<samp class="einst2">OPTGROUP</samp>, and <samp class="einst2">OPTION</samp>
elements</a>
<ol>
<li><a class="tocxref" href="#h-17.6.1">Pre-selected options</a></li>
</ol>
</li>
<li><a class="tocxref" href="#h-17.7">The <samp class="einst2">TEXTAREA</samp>
element</a></li>
<li><a class="tocxref" href="#h-17.8">The <samp class="einst2">ISINDEX</samp>
element</a></li>
<li><a class="tocxref" href="#h-17.9">Labels</a>
<ol>
<li><a class="tocxref" href="#h-17.9.1">The <samp class="einst2">LABEL</samp>
element</a></li>
</ol>
</li>
<li><a class="tocxref" href="#h-17.10">Adding structure to forms: the <samp
class="einst2">FIELDSET</samp> and <samp class="einst2">LEGEND</samp>
elements</a></li>
<li><a class="tocxref" href="#h-17.11"><span class="index-def" title=
"focus|control::giving focus to">Giving focus to an element</span></a>
<ol>
<li><a class="tocxref" href="#h-17.11.1"><span class="index-def" title=
"control::tabbing navigation|tabbing navigation|form::navigating through
controls">Tabbing navigation</span></a></li>
<li><a class="tocxref" href="#h-17.11.2"><span class="index-def" title="access
key|control::access key for|accessibility::access keys">Access
keys</span></a></li>
</ol>
</li>
<li><a class="tocxref" href="#h-17.12">Disabled and read-only controls</a>
<ol>
<li><a class="tocxref" href="#h-17.12.1">Disabled controls</a></li>
<li><a class="tocxref" href="#h-17.12.2">Read-only controls</a></li>
</ol>
</li>
<li><a class="tocxref" href="#h-17.13">Form submission</a>
<ol>
<li><a class="tocxref" href="#h-17.13.1">Form submission method</a></li>
<li><a class="tocxref" href="#h-17.13.2">Successful controls</a></li>
<li><a class="tocxref" href="#h-17.13.3">Processing form data</a>
<ul>
<li><a class="tocxref" href="#h-17.13.3.1">Step one: Identify the successful
controls</a></li>
<li><a class="tocxref" href="#h-17.13.3.2">Step two: Build a form data
set</a></li>
<li><a class="tocxref" href="#h-17.13.3.3">Step three: Encode the form data
set</a></li>
<li><a class="tocxref" href="#h-17.13.3.4">Step four: Submit the encoded form
data set</a></li>
</ul>
</li>
<li><a class="tocxref" href="#h-17.13.4">Form content types</a>
<ul>
<li><a class="tocxref" href="#h-17.13.4.1"><span class="index-def" title=
"application/x-www-form-urlencoded|content
type::application/x-www-form-urlencoded">
application/x-www-form-urlencoded</span></a></li>
<li><a class="tocxref" href="#h-17.13.4.2"><span class="index-def" title=
"multipart/form-data|content type::multipart/form-data">
multipart/form-data</span></a></li>
</ul>
</li>
</ol>
</li>
</ol>
</div>
<h2><a name="h-17.1">17.1</a> Introduction to forms</h2>
<p>An HTML form is a section of a document containing normal content, markup,
special elements called <a href="#form-controls"><em>controls</em></a>
(checkboxes, radio buttons, menus, etc.), and labels on those controls. Users
generally "complete" a form by modifying its controls (entering text, selecting
menu items, etc.), before submitting the form to an agent for processing (e.g.,
to a Web server, to a mail server, etc.)</p>
<div class="example">
<p>Here's a simple form that includes labels, radio buttons, and push buttons
(reset the form or submit it):</p>
<pre>
<FORM action="http://somesite.com/prog/adduser" method="post">
<P>
<LABEL for="firstname">First name: </LABEL>
<INPUT type="text" id="firstname"><BR>
<LABEL for="lastname">Last name: </LABEL>
<INPUT type="text" id="lastname"><BR>
<LABEL for="email">email: </LABEL>
<INPUT type="text" id="email"><BR>
<INPUT type="radio" name="sex" value="Male"> Male<BR>
<INPUT type="radio" name="sex" value="Female"> Female<BR>
<INPUT type="submit" value="Send"> <INPUT type="reset">
</P>
</FORM>
</pre>
</div>
<div class="note">
<p><em><strong>Note.</strong> This specification includes more detailed
information about forms in the subsections on <a href=
"../appendix/notes.html#notes-forms">form display issues</a>.</em></p>
</div>
<h2><a name="h-17.2">17.2</a> <a name="form-controls">Controls</a></h2>
<p><span class="index-def" title="control|form::controls in"><a name=
"didx-control">Users interact with forms through named <dfn>
controls</dfn>.</a></span></p>
<p>A control's <span class="index-def" title="control::control name"><a name=
"control-name"><dfn>"control name"</dfn></a></span> is given by its <samp>
name</samp> attribute. The scope of the <samp>name</samp> attribute for a
control within a <a href="forms.html#edef-FORM" class="noxref"><samp class=
"einst">FORM</samp></a> element is the <a href="forms.html#edef-FORM" class=
"noxref"><samp class="einst">FORM</samp></a> element.</p>
<p>Each control has both an initial value and a current value, both of which
are character strings. Please consult the definition of each control for
information about initial values and possible constraints on values imposed by
the control. In general, a control's <span class="index-def" title=
"control::initial value"><a name="initial-value"><dfn>"initial
value"</dfn></a></span> may be specified with the control element's <samp>
value</samp> attribute. However, the initial value of a <a href=
"forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a> element is given by its contents, and the initial value of
an <a href="../struct/objects.html#edef-OBJECT" class="noxref"><samp class=
"einst">OBJECT</samp></a> element in a form is determined by the object
implementation (i.e., it lies outside the scope of this specification).</p>
<p>The control's <span class="index-def" title="control::control value"><a
name="current-value"><dfn>"current value"</dfn></a></span> is first set to the
initial value. Thereafter, the control's current value may be modified through
user interaction and <a href="../interact/scripts.html">scripts.</a></p>
<p><span class="index-def" title="form::reset of|resetting a form"><a name=
"didx-form-1">A control's initial value does not change.</a></span> Thus, when
a form is reset, each control's current value is reset to its initial value. If
a control does not have an initial value, the effect of a form reset on that
control is undefined.</p>
<p>When a form is submitted for processing, some controls have their name
paired with their current value and these pairs are <a href="#submit-format">
submitted</a> with the form. Those controls for which name/value pairs are
submitted are called <a href="#successful-controls">successful
controls</a>.</p>
<h3><a name="h-17.2.1">17.2.1</a> <span class="index-inst" title=
"control::types of|form::control types"><a name="idx-control-7">Control
types</a></span></h3>
<p>HTML defines the following control types:</p>
<dl>
<dt><a name="buttons"><strong>buttons</strong></a></dt>
<dd>Authors may create three types of buttons:
<ul>
<li><span class="index-def" title="submit button"><a name="submit-button">
submit buttons</a></span>: When activated, a submit button <a href=
"#submit-format">submits a form.</a> A form may contain more than one submit
button.</li>
<li><span class="index-def" title="reset button"><a name="reset-button">reset
buttons</a></span>: When activated, a reset button resets all controls to their
<a href="#initial-value">initial values.</a></li>
<li><span class="index-def" title="push button"><a name="push-button">push
buttons</a></span>: Push buttons have no default behavior. Each push button may
have <a href="scripts.html">client-side scripts</a> associated with the
element's <a href="scripts.html#events">event</a> attributes. When an event
occurs (e.g., the user presses the button, releases it, etc.), the associated
script is triggered.
<p>Authors should specify the scripting language of a push button script
through a <a href="scripts.html#default-script">default script declaration</a>
(with the <a href="../struct/global.html#edef-META" class="noxref"><samp class=
"einst">META</samp></a> element).</p>
</li>
</ul>
<p>Authors create buttons with the <a href="forms.html#edef-BUTTON" class=
"noxref"><samp class="einst">BUTTON</samp></a> element or the <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
element. Please consult the definitions of these elements for details about
specifying different button types.</p>
<div class="note">
<p><em><strong>Note.</strong> Authors should note that the <a href=
"forms.html#edef-BUTTON" class="noxref"><samp class="einst">BUTTON</samp></a>
element offers richer rendering capabilities than the <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
element.</em></p>
</div>
</dd>
<dt><span class="index-def" title="checkbox"><a name="checkbox"><strong>
checkboxes</strong></a></span></dt>
<dd>Checkboxes (and radio buttons) are on/off switches that may be toggled by
the user. A switch is "on" when the control element's <a href=
"forms.html#adef-checked" class="noxref"><samp class="ainst">checked</samp></a>
attribute is set. When a form is submitted, only "on" checkbox controls can
become <a href="#successful-controls">successful</a>.
<p>Several checkboxes in a form may share the same <a href="#control-name">
control name.</a> Thus, for example, checkboxes allow users to select several
values for the same property. The <a href="forms.html#edef-INPUT" class=
"noxref"><samp class="einst">INPUT</samp></a> element is used to create a
checkbox control.</p>
</dd>
<dt><span class="index-def" title="radio button"><a name="radio"><strong>radio
buttons</strong></a></span></dt>
<dd>Radio buttons are like checkboxes except that when several share the same
<a href="#control-name">control name</a>, they are mutually exclusive: when one
is switched "on", all others with the same name are switched "off". The <a
href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a> element is used to create a radio button control.</dd>
<dd>If no radio button in a set sharing the same control name is initially
"on", user agent behavior for choosing which control is initially "on" is
undefined. <strong>Note.</strong> Since existing implementations handle this
case differently, the current specification differs from RFC 1866 (<a rel=
"biblioentry" href="../references.html#ref-RFC1866" class=
"normref">[RFC1866]</a> section 8.1.2.4), which states:
<blockquote>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.</blockquote>
<p>Since user agent behavior differs, authors should ensure that in each set of
radio buttons that one is initially "on".</p>
</dd>
<dt><span class="index-def" title="menu"><a name="menu"><strong>
menus</strong></a></span></dt>
<dd>Menus offer users options from which to choose. The <a href=
"forms.html#edef-SELECT" class="noxref"><samp class="einst">SELECT</samp></a>
element creates a menu, in combination with the <a href=
"forms.html#edef-OPTGROUP" class="noxref"><samp class="einst">
OPTGROUP</samp></a> and <a href="forms.html#edef-OPTION" class="noxref"><samp
class="einst">OPTION</samp></a> elements.</dd>
<dt><span class="index-def" title="text input control"><a name="text-input">
<strong>text input</strong></a></span></dt>
<dd>Authors may create two types of controls that allow users to input text.
The <a href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a> element creates a single-line input control and the <a href=
"forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a> element creates a multi-line input control. In both cases,
the input text becomes the control's <a href="#current-value">current
value</a>.</dd>
<dt><span class="index-def" title="file select control"><a name="file-select">
<strong>file select</strong></a></span></dt>
<dd>This control type allows the user to select files so that their contents
may be submitted with a form. The <a href="forms.html#edef-INPUT" class=
"noxref"><samp class="einst">INPUT</samp></a> element is used to create a file
select control.</dd>
<dt><span class="index-def" title="hidden control"><a name="hidden-control">
<strong>hidden controls</strong></a></span></dt>
<dd>Authors may create controls that are not rendered but whose values are
submitted with a form. Authors generally use this control type to store
information between client/server exchanges that would otherwise be lost due to
the stateless nature of HTTP (see <a rel="biblioentry" href=
"../references.html#ref-RFC2616" class="informref">[RFC2616]</a>). The <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
element is used to create a hidden control.</dd>
<dt><span class="index-def" title="object control|object::in form"><a name=
"object-control"><strong>object controls</strong></a></span></dt>
<dd>Authors may insert generic objects in forms such that associated values are
submitted along with other controls. Authors create object controls with the <a
href="../struct/objects.html#edef-OBJECT" class="noxref"><samp class="einst">
OBJECT</samp></a> element.</dd>
</dl>
<p>The elements used to create controls generally appear inside a <a href=
"forms.html#edef-FORM" class="noxref"><samp class="einst">FORM</samp></a>
element, but may also appear outside of a <a href="forms.html#edef-FORM" class=
"noxref"><samp class="einst">FORM</samp></a> element declaration when they are
used to build user interfaces. This is discussed in the section on <a href=
"./scripts.html#events">intrinsic events.</a> Note that controls outside a form
cannot be <a href="#successful-controls">successful controls</a>.</p>
<h2><a name="h-17.3">17.3</a> The <a name="edef-FORM"><samp class="edef">
FORM</samp></a> element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-FORM" class="noxref"><samp class=
"einst">FORM</samp></a> - - (<a href=
"../sgml/dtd.html#block">%block;</a>|SCRIPT)+ -(FORM) -- interactive form -->
<!ATTLIST FORM
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-action" class="noxref"><samp class=
"ainst-FORM">action</samp></a> <a href=
"../sgml/dtd.html#URI">%URI;</a> #REQUIRED -- server-side form handler --
<a href="forms.html#adef-method" class="noxref"><samp class=
"ainst-FORM">method</samp></a> (GET|POST) GET -- HTTP method used to submit the form--
<a href="forms.html#adef-enctype" class="noxref"><samp class=
"ainst-FORM">enctype</samp></a> <a href=
"../sgml/dtd.html#ContentType">%ContentType;</a> "application/x-www-form-urlencoded"
<a href="forms.html#adef-accept" class="noxref"><samp class=
"ainst">accept</samp></a> <a href=
"../sgml/dtd.html#ContentTypes">%ContentTypes;</a> #IMPLIED -- list of MIME types for file upload --
<a href="forms.html#adef-name-FORM" class="noxref"><samp class=
"ainst-FORM">name</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- name of form for scripting --
<a href="scripts.html#adef-onsubmit" class="noxref"><samp class=
"ainst-FORM">onsubmit</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the form was submitted --
<a href="scripts.html#adef-onreset" class="noxref"><samp class=
"ainst-FORM">onreset</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the form was reset --
<a href="forms.html#adef-accept-charset" class="noxref"><samp class=
"ainst-FORM">accept-charset</samp></a> <a href=
"../sgml/dtd.html#Charsets">%Charsets;</a> #IMPLIED -- list of supported charsets --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-action"><samp class="adef">action</samp></a> = <a href=
"../types.html#type-uri"><em>uri</em></a> <a href=
"../types.html#see-type-for-case">[CT]</a></dt>
<dd>This attribute specifies a form processing agent. User agent behavior for a
value other than an HTTP URI is undefined.</dd>
<dt><a name="adef-method"><samp class="adef">method</samp></a> = <samp>
get|post</samp> <a href="../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute specifies which HTTP method will be used to submit the <a
href="#form-data-set">form data set</a>. Possible (case-insensitive) values are
"get" (the default) and "post". See the section on <a href="#submit-format">
form submission</a> for usage information.</dd>
<dt><a name="adef-enctype"><samp class="adef">enctype</samp></a> = <a href=
"../types.html#type-content-type"><em>content-type</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute specifies the <a href="#form-content-type">content type</a>
used to submit the form to the server (when the value of <a href=
"forms.html#adef-method" class="noxref"><samp class="ainst">method</samp></a>
is "post"). The default value for this attribute is <span class="index-inst"
title="application/x-www-form-urlencoded"><a name=
"idx-applicationx-www-form-urlencoded-1">
"application/x-www-form-urlencoded"</a></span>. The value <span class=
"index-inst" title="multipart/form-data"><a name="idx-multipartform-data-1">
"multipart/form-data"</a></span> should be used in combination with the <a
href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a> element, <samp class="ainst">type</samp>="file".</dd>
<dt><a name="adef-accept-charset"><samp class="adef">accept-charset</samp></a>
= <a href="../types.html#type-charset"><em>charset list</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute specifies the list of <span class="index-inst" title=
"character encoding::for form submission"><a name="idx-character_encoding"
href="../charset.html#doc-char-set">character encodings</a></span> for input
data that is accepted by the server processing this form. The value is a space-
and/or comma-delimited list of <a href="../types.html#type-charset">charset</a>
values. The client must interpret this list as an exclusive-or list, i.e., the
server is able to accept any single character encoding per entity received.
<p>The default value for this attribute is the reserved string "UNKNOWN". User
agents may interpret this value as the character encoding that was used to
transmit the document containing this <a href="forms.html#edef-FORM" class=
"noxref"><samp class="einst">FORM</samp></a> element.</p>
</dd>
<dt><a name="adef-accept"><samp class="adef">accept</samp></a> = <a href=
"../types.html#type-content-type"><em>content-type-list</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute specifies a comma-separated list of content types that a
server processing this form will handle correctly. User agents may use this
information to filter out non-conforming files when prompting a user to select
files to be sent to the server (cf. the <a href="forms.html#edef-INPUT" class=
"noxref"><samp class="einst">INPUT</samp></a> element when <a href=
"forms.html#adef-type-INPUT" class="noxref"><samp class="ainst-INPUT">
type</samp></a>="file").</dd>
<dt><a name="adef-name-FORM"><samp class="adef">name</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute names the element so that it may be referred to from style
sheets or scripts. <strong>Note.</strong> This attribute has been included for
backwards compatibility. Applications should use the <a href=
"../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a> attribute to identify elements.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/frames.html#adef-target" class="noxref"><samp class=
"ainst">target</samp></a> (<a href="../present/frames.html#target-info">target
frame information</a>)</li>
<li><a href="scripts.html#adef-onsubmit" class="noxref"><samp class="ainst">
onsubmit</samp></a>, <a href="scripts.html#adef-onreset" class="noxref"><samp
class="ainst">onreset</samp></a>, <a href="scripts.html#adef-onclick" class=
"noxref"><samp class="ainst">onclick</samp></a>, <a href=
"scripts.html#adef-ondblclick" class="noxref"><samp class="ainst">
ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown" class="noxref">
<samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p>The <a href="forms.html#edef-FORM" class="noxref"><samp class="einst">
FORM</samp></a> element acts as a container for <a href="#form-controls">
controls</a>. It specifies:</p>
<ul>
<li>The layout of the form (given by the contents of the element).</li>
<li>The program that will handle the completed and submitted form (the <a href=
"forms.html#adef-action" class="noxref"><samp class="ainst">action</samp></a>
attribute). The receiving program must be able to parse name/value pairs in
order to make use of them.</li>
<li>The method by which user data will be sent to the server (the <a href=
"forms.html#adef-method" class="noxref"><samp class="ainst">method</samp></a>
attribute).</li>
<li>A character encoding that must be accepted by the server in order to handle
this form (the <a href="forms.html#adef-accept-charset" class="noxref"><samp
class="ainst">accept-charset</samp></a> attribute). User agents may advise the
user of the value of the <a href="forms.html#adef-accept-charset" class=
"noxref"><samp class="ainst">accept-charset</samp></a> attribute and/or
restrict the user's ability to enter unrecognized characters.</li>
</ul>
<p>A form can contain text and markup (paragraphs, lists, etc.) in addition to
<a href="#form-controls">form controls.</a></p>
<div class="example">
<p>The following example shows a form that is to be processed by the "adduser"
program when submitted. The form will be sent to the program using the HTTP
"post" method.</p>
<pre>
<FORM action="http://somesite.com/prog/adduser" method="post">
<em>...form contents...</em>
</FORM>
</pre>
</div>
<p>Please consult the section on <a href="#submit-format">form submission</a>
for information about how user agents must prepare form data for servers and
how user agents should handle expected responses.</p>
<div class="note">
<p><em><strong>Note.</strong> Further discussion on the behavior of servers
that receive form data is beyond the scope of this specification.</em></p>
</div>
<h2><a name="h-17.4">17.4</a> The <a name="edef-INPUT"><samp class="edef">
INPUT</samp></a> element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ENTITY % InputType
"(TEXT | PASSWORD | CHECKBOX |
RADIO | SUBMIT | RESET |
FILE | HIDDEN | IMAGE | BUTTON)"
>
<!-- attribute name required for all but submit and reset -->
<!ELEMENT <a href="forms.html#edef-INPUT" class="noxref"><samp class=
"einst">INPUT</samp></a> - O EMPTY -- form control -->
<!ATTLIST INPUT
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-type-INPUT" class="noxref"><samp class=
"ainst-INPUT">type</samp></a> <a href=
"../sgml/dtd.html#InputType">%InputType;</a> TEXT -- what kind of widget is needed --
<a href="forms.html#adef-name-INPUT" class="noxref"><samp class=
"ainst-INPUT">name</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- submit as part of form --
<a href="forms.html#adef-value-INPUT" class="noxref"><samp class=
"ainst-INPUT">value</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- Specify for radio buttons and checkboxes --
<a href="forms.html#adef-checked" class="noxref"><samp class=
"ainst-INPUT">checked</samp></a> (checked) #IMPLIED -- for radio buttons and check boxes --
<a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst-INPUT">disabled</samp></a> (disabled) #IMPLIED -- unavailable in this context --
<a href="forms.html#adef-readonly" class="noxref"><samp class=
"ainst-INPUT">readonly</samp></a> (readonly) #IMPLIED -- for text and passwd --
<a href="forms.html#adef-size-INPUT" class="noxref"><samp class=
"ainst-INPUT">size</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- specific to each type of field --
<a href="forms.html#adef-maxlength" class="noxref"><samp class=
"ainst-INPUT">maxlength</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #IMPLIED -- max chars for text fields --
<a href="forms.html#adef-src" class="noxref"><samp class=
"ainst-INPUT">src</samp></a> <a href=
"../sgml/dtd.html#URI">%URI;</a> #IMPLIED -- for fields with images --
<a href="../struct/objects.html#adef-alt" class="noxref"><samp class=
"ainst-INPUT">alt</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- short description --
<a href="../struct/objects.html#adef-usemap" class="noxref"><samp class=
"ainst-INPUT">usemap</samp></a> <a href=
"../sgml/dtd.html#URI">%URI;</a> #IMPLIED -- use client-side image map --
<a href="../struct/objects.html#adef-ismap" class="noxref"><samp class=
"ainst">ismap</samp></a> (ismap) #IMPLIED -- use server-side image map --
<a href="forms.html#adef-tabindex" class="noxref"><samp class=
"ainst-INPUT">tabindex</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #IMPLIED -- position in tabbing order --
<a href="forms.html#adef-accesskey" class="noxref"><samp class=
"ainst-INPUT">accesskey</samp></a> <a href=
"../sgml/dtd.html#Character">%Character;</a> #IMPLIED -- accessibility key character --
<a href="scripts.html#adef-onfocus" class="noxref"><samp class=
"ainst-INPUT">onfocus</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element got the focus --
<a href="scripts.html#adef-onblur" class="noxref"><samp class=
"ainst-INPUT">onblur</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element lost the focus --
<a href="scripts.html#adef-onselect" class="noxref"><samp class=
"ainst-INPUT">onselect</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- some text was selected --
<a href="scripts.html#adef-onchange" class="noxref"><samp class=
"ainst-INPUT">onchange</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element value was changed --
<a href="forms.html#adef-accept" class="noxref"><samp class=
"ainst">accept</samp></a> <a href=
"../sgml/dtd.html#ContentTypes">%ContentTypes;</a> #IMPLIED -- list of MIME types for file upload --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
forbidden</strong></em></p>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-type-INPUT"><samp class="adef">type</samp></a> = <samp>
text|password|checkbox|radio|submit|reset|file|hidden|image|button</samp> <a
href="../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute specifies the <a href="#input-control-types">type of
control</a> to create. The default value for this attribute is "text".</dd>
<dt><a name="adef-name-INPUT"><samp class="adef">name</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute assigns the <a href="#control-name">control name</a>.</dd>
<dt><a name="adef-value-INPUT"><samp class="adef">value</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-attribute">[CA]</a></dt>
<dd>This attribute specifies the <a href="#initial-value">initial value</a> of
the control. It is optional except when the <a href=
"forms.html#adef-type-INPUT" class="noxref"><samp class="ainst-INPUT">
type</samp></a> attribute has the value "radio" or "checkbox".</dd>
<dt><a name="adef-size-INPUT"><samp class="adef">size</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>This attribute tells the user agent the initial width of the control. The
width is given in <a href="../types.html#type-pixels">pixels</a> except when <a
href="forms.html#adef-type-INPUT" class="noxref"><samp class="ainst-INPUT">
type</samp></a> attribute has the value "text" or "password". In that case, its
value refers to the (integer) number of characters.</dd>
<dt><a name="adef-maxlength"><samp class="adef">maxlength</samp></a> = <a href=
"../types.html#type-number"><em>number</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>When the <a href="forms.html#adef-type-INPUT" class="noxref"><samp class=
"ainst-INPUT">type</samp></a> attribute has the value "text" or "password",
this attribute specifies the maximum number of characters the user may enter.
This number may exceed the specified <a href="forms.html#adef-size-INPUT"
class="noxref"><samp class="ainst-INPUT">size</samp></a>, in which case the
user agent should offer a scrolling mechanism. The default value for this
attribute is an unlimited number.</dd>
<dt><a name="adef-checked"><samp class="adef">checked</samp></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>When the <a href="forms.html#adef-type-INPUT" class="noxref"><samp class=
"ainst-INPUT">type</samp></a> attribute has the value "radio" or "checkbox",
this boolean attribute specifies that the button is on. User agents must ignore
this attribute for other control types.</dd>
<dt><a name="adef-src"><samp class="adef">src</samp></a> = <a href=
"../types.html#type-uri"><em>uri</em></a> <a href=
"../types.html#see-type-for-case">[CT]</a></dt>
<dd>When the <a href="forms.html#adef-type-INPUT" class="noxref"><samp class=
"ainst-INPUT">type</samp></a> attribute has the value "image", this attribute
specifies the location of the image to be used to decorate the graphical submit
button.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="../struct/objects.html#adef-alt" class="noxref"><samp class=
"ainst">alt</samp></a> (<a href=
"../struct/objects.html#alternate-text">alternate text</a>)</li>
<li><a href="../present/graphics.html#adef-align" class="noxref"><samp class=
"ainst">align</samp></a> (<a href=
"../present/graphics.html#alignment">alignment</a>)</li>
<li><a href="forms.html#adef-accept" class="noxref"><samp class="ainst">
accept</samp></a> (<a href="#edef-FORM">legal content types for a
server</a>)</li>
<li><a href="forms.html#adef-readonly" class="noxref"><samp class="ainst">
readonly</samp></a> (<a href="#read-only">read-only input controls</a>)</li>
<li><a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> (<a href="#disabled">disabled input controls</a>)</li>
<li><a href="forms.html#adef-tabindex" class="noxref"><samp class="ainst">
tabindex</samp></a> (<a href=
"../interact/forms.html#tabbing-navigation">tabbing navigation</a>)</li>
<li><a href="forms.html#adef-accesskey" class="noxref"><samp class="ainst">
accesskey</samp></a> (<a href="../interact/forms.html#access-keys">access
keys</a>)</li>
<li><a href="../struct/objects.html#adef-usemap" class="noxref"><samp class=
"ainst">usemap</samp></a> (<a href=
"../struct/objects.html#edef-MAP">client-side image maps</a>)</li>
<li><a href="../struct/objects.html#adef-ismap" class="noxref"><samp class=
"ainst">ismap</samp></a> (<a href=
"../struct/objects.html#server-side">server-side image maps</a>)</li>
<li><a href="scripts.html#adef-onfocus" class="noxref"><samp class="ainst">
onfocus</samp></a>, <a href="scripts.html#adef-onblur" class="noxref"><samp
class="ainst">onblur</samp></a>, <a href="scripts.html#adef-onselect" class=
"noxref"><samp class="ainst">onselect</samp></a>, <a href=
"scripts.html#adef-onchange" class="noxref"><samp class="ainst">
onchange</samp></a>, <a href="scripts.html#adef-onclick" class="noxref"><samp
class="ainst">onclick</samp></a>, <a href="scripts.html#adef-ondblclick" class=
"noxref"><samp class="ainst">ondblclick</samp></a>, <a href=
"scripts.html#adef-onmousedown" class="noxref"><samp class="ainst">
onmousedown</samp></a>, <a href="scripts.html#adef-onmouseup" class="noxref">
<samp class="ainst">onmouseup</samp></a>, <a href=
"scripts.html#adef-onmouseover" class="noxref"><samp class="ainst">
onmouseover</samp></a>, <a href="scripts.html#adef-onmousemove" class="noxref">
<samp class="ainst">onmousemove</samp></a>, <a href=
"scripts.html#adef-onmouseout" class="noxref"><samp class="ainst">
onmouseout</samp></a>, <a href="scripts.html#adef-onkeypress" class="noxref">
<samp class="ainst">onkeypress</samp></a>, <a href=
"scripts.html#adef-onkeydown" class="noxref"><samp class="ainst">
onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup" class="noxref"><samp
class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<h3><a name="h-17.4.1">17.4.1</a> <a name="input-control-types">Control types
created with INPUT</a></h3>
<p>The <a href="#form-controls">control type</a> defined by the <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
element depends on the value of the <a href="forms.html#adef-type-INPUT" class=
"noxref"><samp class="ainst-INPUT">type</samp></a> attribute:</p>
<dl>
<dt><strong>text</strong></dt>
<dd><span class="index-inst" title="text input control::single-line">Creates a
single-line <a name="idx-text_input_control-1" href="#text-input">text
input</a> control.</span></dd>
<dt><strong>password</strong></dt>
<dd><span class="index-inst" title="password input control"><a name=
"idx-password_input_control">Like "text",</a></span> but the input text is
rendered in such a way as to hide the characters (e.g., a series of asterisks).
This control type is often used for sensitive input such as passwords. Note
that the <a href="#current-value">current value</a> is the text <em>
entered</em> by the user, not the text rendered by the user agent.
<div class="note">
<p><em><span class="index-inst" title="security::of password control"><a name=
"idx-security"><strong>Note.</strong></a></span> Application designers should
note that this mechanism affords only light security protection. Although the
password is masked by user agents from casual observers, it is transmitted to
the server in clear text, and may be read by anyone with low-level access to
the network.</em></p>
</div>
</dd>
<dt><strong>checkbox</strong></dt>
<dd>Creates a <a href="#checkbox">checkbox.</a></dd>
<dt><strong>radio</strong></dt>
<dd>Creates a <a href="#radio">radio button.</a></dd>
<dt><strong>submit</strong></dt>
<dd>Creates a <a href="#submit-button">submit button.</a></dd>
<dt><strong>image</strong></dt>
<dd>Creates a graphical <a href="#submit-button">submit button.</a> The value
of the <a href="forms.html#adef-src" class="noxref"><samp class="ainst">
src</samp></a> attribute specifies the URI of the image that will decorate the
button. For accessibility reasons, authors should provide <a href=
"../struct/objects.html#alternate-text">alternate text</a> for the image via
the <a href="../struct/objects.html#adef-alt" class="noxref"><samp class=
"ainst">alt</samp></a> attribute.
<p><span class="index-inst" title="coordinates::of form submit click"><a name=
"idx-coordinates">When a pointing device is used to click on the
image,</a></span> the form is submitted and the click coordinates passed to the
server. The x value is measured in <a href="../types.html#type-pixels">
pixels</a> from the left of the image, and the y value in <a href=
"../types.html#type-pixels">pixels</a> from the top of the image. The submitted
data includes <em>name</em>.x=<em>x-value</em> and <em>
name</em>.y=<em>y-value</em> where <em>"name"</em> is the value of the <samp
class="ainst">name</samp> attribute, and <em>x-value</em> and <em>y-value</em>
are the x and y coordinate values, respectively.</p>
<p>If the server takes different actions depending on the location clicked,
users of non-graphical browsers will be disadvantaged. For this reason, authors
should consider alternate approaches:</p>
<ul>
<li>Use multiple submit buttons (each with its own image) in place of a single
graphical submit button. Authors may use style sheets to control the
positioning of these buttons.</li>
<li>Use a <a href="../struct/objects.html#include-maps">client-side image
map</a> together with scripting.</li>
</ul>
</dd>
<dt><strong>reset</strong></dt>
<dd>Creates a <a href="#reset-button">reset button.</a></dd>
<dt><strong>button</strong></dt>
<dd>Creates a <a href="#push-button">push button.</a> User agents should use
the value of the <samp class="ainst">value</samp> attribute as the button's
label.</dd>
<dt><strong>hidden</strong></dt>
<dd>Creates a <a href="#hidden-control">hidden control.</a></dd>
<dt><strong>file</strong></dt>
<dd>Creates a <a href="#file-select">file select</a> control. User agents may
use the value of the <a href="forms.html#adef-value-INPUT" class="noxref"><samp
class="ainst-INPUT">value</samp></a> attribute as the initial file name.</dd>
</dl>
<h3><a name="h-17.4.2">17.4.2</a> Examples of forms containing INPUT
controls</h3>
<div class="example">
<p>The following sample HTML fragment defines a simple form that allows the
user to enter a first name, last name, email address, and gender. When the
submit button is activated, the form will be sent to the program specified by
the <a href="forms.html#adef-action" class="noxref"><samp class="ainst">
action</samp></a> attribute.</p>
<pre>
<FORM action="http://somesite.com/prog/adduser" method="post">
<P>
First name: <INPUT type="text" name="firstname"><BR>
Last name: <INPUT type="text" name="lastname"><BR>
email: <INPUT type="text" name="email"><BR>
<INPUT type="radio" name="sex" value="Male"> Male<BR>
<INPUT type="radio" name="sex" value="Female"> Female<BR>
<INPUT type="submit" value="Send"> <INPUT type="reset">
</P>
</FORM>
</pre>
<p>This form might be rendered as follows:</p>
<p><img src="../images/form_exmpl.gif" alt="An example form rendering."></p>
<p>In the section on the <a href="forms.html#edef-LABEL" class="noxref"><samp
class="einst">LABEL</samp></a> element, we discuss marking up labels such as
"First name".</p>
</div>
<div class="example">
<p>In this next example, the JavaScript function name <tt>verify</tt> is
triggered when the "onclick" event occurs:</p>
<pre>
<HEAD>
<META http-equiv="Content-Script-Type" content="text/javascript">
</HEAD>
<BODY>
<FORM action="..." method="post">
<P>
<INPUT type="button" value="Click Me" onclick="verify()">
</FORM>
</BODY>
</pre>
<p>Please consult the section on <a href="./scripts.html#events">intrinsic
events</a> for more information about scripting and events.</p>
</div>
<div class="example">
<p>The following example shows how the contents of a user-specified file may be
submitted with a form. The user is prompted for his or her name and a list of
file names whose contents should be submitted with the form. By specifying the
<a href="forms.html#adef-enctype" class="noxref"><samp class="ainst">
enctype</samp></a> value of "multipart/form-data", each file's contents will be
packaged for submission in a separate section of a multipart document.</p>
<pre>
<FORM action="http://server.dom/cgi/handle"
enctype="multipart/form-data"
method="post">
<P>
What is your name? <INPUT type="text" name="name_of_sender">
What files are you sending? <INPUT type="file" name="name_of_files">
</P>
</FORM>
</pre>
</div>
<h2><a name="h-17.5">17.5</a> The <a name="edef-BUTTON"><samp class="edef">
BUTTON</samp></a> element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-BUTTON" class="noxref"><samp class=
"einst">BUTTON</samp></a> - -
(<a href="../sgml/dtd.html#flow">%flow;</a>)* -(A|<a href=
"../sgml/dtd.html#formctrl">%formctrl;</a>|FORM|FIELDSET)
-- push button -->
<!ATTLIST BUTTON
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-name-BUTTON" class="noxref"><samp class=
"ainst-BUTTON">name</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED
<a href="forms.html#adef-value-BUTTON" class="noxref"><samp class=
"ainst-BUTTON">value</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- sent to server when submitted --
<a href="forms.html#adef-type-BUTTON" class="noxref"><samp class=
"ainst-BUTTON">type</samp></a> (button|submit|reset) submit -- for use as form button --
<a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst-BUTTON">disabled</samp></a> (disabled) #IMPLIED -- unavailable in this context --
<a href="forms.html#adef-tabindex" class="noxref"><samp class=
"ainst-BUTTON">tabindex</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #IMPLIED -- position in tabbing order --
<a href="forms.html#adef-accesskey" class="noxref"><samp class=
"ainst-BUTTON">accesskey</samp></a> <a href=
"../sgml/dtd.html#Character">%Character;</a> #IMPLIED -- accessibility key character --
<a href="scripts.html#adef-onfocus" class="noxref"><samp class=
"ainst-BUTTON">onfocus</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element got the focus --
<a href="scripts.html#adef-onblur" class="noxref"><samp class=
"ainst-BUTTON">onblur</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element lost the focus --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-name-BUTTON"><samp class="adef">name</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute assigns the <a href="#control-name">control name.</a></dd>
<dt><a name="adef-value-BUTTON"><samp class="adef">value</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-sensitive">[CS]</a></dt>
<dd>This attribute assigns the <a href="#initial-value">initial value</a> to
the button.</dd>
<dt><a name="adef-type-BUTTON"><samp class="adef">type</samp></a> = <samp>
submit|button|reset</samp> <a href="../types.html#case-insensitive">
[CI]</a></dt>
<dd>This attribute declares the type of the button. Possible values:
<ul>
<li><samp>submit:</samp> Creates a <a href="#submit-button">submit button.</a>
This is the default value.</li>
<li><samp>reset:</samp> Creates a <a href="#reset-button">reset
button.</a></li>
<li><samp>button:</samp> Creates a <a href="#push-button">push button.</a></li>
</ul>
</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> (<a href="#disabled">disabled input controls</a>)</li>
<li><a href="forms.html#adef-accesskey" class="noxref"><samp class="ainst">
accesskey</samp></a> (<a href="../interact/forms.html#access-keys">access
keys</a>)</li>
<li><a href="forms.html#adef-tabindex" class="noxref"><samp class="ainst">
tabindex</samp></a> (<a href=
"../interact/forms.html#tabbing-navigation">tabbing navigation</a>)</li>
<li><a href="scripts.html#adef-onfocus" class="noxref"><samp class="ainst">
onfocus</samp></a>, <a href="scripts.html#adef-onblur" class="noxref"><samp
class="ainst">onblur</samp></a>, <a href="scripts.html#adef-onclick" class=
"noxref"><samp class="ainst">onclick</samp></a>, <a href=
"scripts.html#adef-ondblclick" class="noxref"><samp class="ainst">
ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown" class="noxref">
<samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p>Buttons created with the <a href="forms.html#edef-BUTTON" class="noxref">
<samp class="einst">BUTTON</samp></a> element function just like buttons
created with the <a href="forms.html#edef-INPUT" class="noxref"><samp class=
"einst">INPUT</samp></a> element, but they offer richer rendering
possibilities: the <a href="forms.html#edef-BUTTON" class="noxref"><samp class=
"einst">BUTTON</samp></a> element may have content. For example, a <a href=
"forms.html#edef-BUTTON" class="noxref"><samp class="einst">BUTTON</samp></a>
element that contains an image functions like and may resemble an <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
element whose <a href="forms.html#adef-type-INPUT" class="noxref"><samp class=
"ainst-INPUT">type</samp></a> is set to "image", but the <a href=
"forms.html#edef-BUTTON" class="noxref"><samp class="einst">BUTTON</samp></a>
element type allows content.</p>
<p>Visual user agents may render <a href="forms.html#edef-BUTTON" class=
"noxref"><samp class="einst">BUTTON</samp></a> buttons with relief and an
up/down motion when clicked, while they may render <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
buttons as "flat" images.</p>
<div class="example">
<p>The following example expands a previous example, but creates <a href=
"#submit-button">submit</a> and <a href="#reset-button">reset</a> buttons with
<a href="forms.html#edef-BUTTON" class="noxref"><samp class="einst">
BUTTON</samp></a> instead of <a href="forms.html#edef-INPUT" class="noxref">
<samp class="einst">INPUT</samp></a>. The buttons contain images by way of the
<a href="../struct/objects.html#edef-IMG" class="noxref"><samp class="einst">
IMG</samp></a> element.</p>
<pre>
<FORM action="http://somesite.com/prog/adduser" method="post">
<P>
First name: <INPUT type="text" name="firstname"><BR>
Last name: <INPUT type="text" name="lastname"><BR>
email: <INPUT type="text" name="email"><BR>
<INPUT type="radio" name="sex" value="Male"> Male<BR>
<INPUT type="radio" name="sex" value="Female"> Female<BR>
<BUTTON name="submit" value="submit" type="submit">
Send<IMG src="/icons/wow.gif" alt="wow"></BUTTON>
<BUTTON name="reset" type="reset">
Reset<IMG src="/icons/oops.gif" alt="oops"></BUTTON>
</P>
</FORM>
</pre>
</div>
<p>Recall that authors must provide <a href=
"../struct/objects.html#alternate-text">alternate text</a> for an <a href=
"../struct/objects.html#edef-IMG" class="noxref"><samp class="einst">
IMG</samp></a> element.</p>
<p><span class="index-inst" title="error::image map with IMG in BUTTON|image
map::illegal for IMG in BUTTON"><a name="idx-error">It is illegal</a></span> to
associate an image map with an <a href="../struct/objects.html#edef-IMG" class=
"noxref"><samp class="einst">IMG</samp></a> that appears as the contents of a
<a href="forms.html#edef-BUTTON" class="noxref"><samp class="einst">
BUTTON</samp></a> element.</p>
<div class="illegal-example">
<p><span class="example-title">ILLEGAL EXAMPLE:</span>
<br>
The following is not legal HTML.</p>
<pre>
<BUTTON>
<IMG src="foo.gif" usemap="...">
</BUTTON>
</pre>
</div>
<h2><a name="h-17.6">17.6</a> The <a name="edef-SELECT"><samp class="edef">
SELECT</samp></a>, <a name="edef-OPTGROUP"><samp class="edef">
OPTGROUP</samp></a>, and <a name="edef-OPTION"><samp class="edef">
OPTION</samp></a> elements</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-SELECT" class="noxref"><samp class=
"einst">SELECT</samp></a> - - (OPTGROUP|OPTION)+ -- option selector -->
<!ATTLIST SELECT
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-name-SELECT" class="noxref"><samp class=
"ainst-SELECT">name</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- field name --
<a href="forms.html#adef-size-SELECT" class="noxref"><samp class=
"ainst-SELECT">size</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #IMPLIED -- rows visible --
<a href="forms.html#adef-multiple" class="noxref"><samp class=
"ainst-SELECT">multiple</samp></a> (multiple) #IMPLIED -- default is single selection --
<a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst-SELECT">disabled</samp></a> (disabled) #IMPLIED -- unavailable in this context --
<a href="forms.html#adef-tabindex" class="noxref"><samp class=
"ainst-SELECT">tabindex</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #IMPLIED -- position in tabbing order --
<a href="scripts.html#adef-onfocus" class="noxref"><samp class=
"ainst-SELECT">onfocus</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element got the focus --
<a href="scripts.html#adef-onblur" class="noxref"><samp class=
"ainst-SELECT">onblur</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element lost the focus --
<a href="scripts.html#adef-onchange" class="noxref"><samp class=
"ainst-SELECT">onchange</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element value was changed --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>SELECT Attribute definitions</em></p>
<dl>
<dt><a name="adef-name-SELECT"><samp class="adef">name</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute assigns the <a href="#control-name">control name.</a></dd>
<dt><a name="adef-size-SELECT"><samp class="adef">size</samp></a> = <a href=
"../types.html#type-number"><em>number</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>If a <a href="forms.html#edef-SELECT" class="noxref"><samp class="einst">
SELECT</samp></a> element is presented as a scrolled list box, this attribute
specifies the number of rows in the list that should be visible at the same
time. Visual user agents are not required to present a <a href=
"forms.html#edef-SELECT" class="noxref"><samp class="einst">SELECT</samp></a>
element as a list box; they may use any other mechanism, such as a drop-down
menu.</dd>
<dt><a name="adef-multiple"><samp class="adef">multiple</samp></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>If set, this boolean attribute allows multiple selections. If not set, the
<a href="forms.html#edef-SELECT" class="noxref"><samp class="einst">
SELECT</samp></a> element only permits single selections.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> (<a href="#disabled">disabled input controls</a>)</li>
<li><a href="forms.html#adef-tabindex" class="noxref"><samp class="ainst">
tabindex</samp></a> (<a href=
"../interact/forms.html#tabbing-navigation">tabbing navigation</a>)</li>
<li><a href="scripts.html#adef-onclick" class="noxref"><samp class="ainst">
onclick</samp></a>, <a href="scripts.html#adef-ondblclick" class="noxref"><samp
class="ainst">ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown"
class="noxref"><samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p>The <a href="forms.html#edef-SELECT" class="noxref"><samp class="einst">
SELECT</samp></a> element creates a <a href="#menu">menu</a>. Each choice
offered by the menu is represented by an <a href="forms.html#edef-OPTION"
class="noxref"><samp class="einst">OPTION</samp></a> element. A <a href=
"forms.html#edef-SELECT" class="noxref"><samp class="einst">SELECT</samp></a>
element must contain at least one <a href="forms.html#edef-OPTION" class=
"noxref"><samp class="einst">OPTION</samp></a> element.</p>
<p><span class="index-inst" title="menu::grouping of choices">The <a name=
"idx-menu-1" href="forms.html#edef-OPTGROUP" class="noxref"><samp class=
"einst">OPTGROUP</samp></a> element</span> allows authors to group choices
logically. This is particularly helpful when the user must choose from a long
list of options; groups of related choices are easier to grasp and remember
than a single long list of options. In HTML 4, all <a href=
"forms.html#edef-OPTGROUP" class="noxref"><samp class="einst">
OPTGROUP</samp></a> elements must be specified directly within a <a href=
"forms.html#edef-SELECT" class="noxref"><samp class="einst">SELECT</samp></a>
element (i.e., groups may not be nested).</p>
<h3><a name="h-17.6.1">17.6.1</a> <span class="index-inst" title=
"menu::preselected options"><a name="idx-menu-2">Pre-selected
options</a></span></h3>
<p>Zero or more choices may be pre-selected for the user. User agents should
determine which choices are pre-selected as follows:</p>
<ul>
<li>If no <a href="forms.html#edef-OPTION" class="noxref"><samp class="einst">
OPTION</samp></a> element has the <a href="forms.html#adef-selected" class=
"noxref"><samp class="ainst">selected</samp></a> attribute set, user agent
behavior for choosing which option is initially selected is undefined. <strong>
Note.</strong> Since existing implementations handle this case differently, the
current specification differs from RFC 1866 (<a rel="biblioentry" href=
"../references.html#ref-RFC1866" class="normref">[RFC1866]</a> section 8.1.3),
which states:
<blockquote>The initial state has the first option selected, unless a SELECTED
attribute is present on any of the <OPTION> elements.</blockquote>
<p>Since user agent behavior differs, authors should ensure that each menu
includes a default pre-selected <a href="forms.html#edef-OPTION" class=
"noxref"><samp class="einst">OPTION</samp></a>.</p>
</li>
<li>If one <a href="forms.html#edef-OPTION" class="noxref"><samp class="einst">
OPTION</samp></a> element has the <a href="forms.html#adef-selected" class=
"noxref"><samp class="ainst">selected</samp></a> attribute set, it should be
pre-selected.</li>
<li>If the <a href="forms.html#edef-SELECT" class="noxref"><samp class="einst">
SELECT</samp></a> element has the <a href="forms.html#adef-multiple" class=
"noxref"><samp class="ainst">multiple</samp></a> attribute set and more than
one <a href="forms.html#edef-OPTION" class="noxref"><samp class="einst">
OPTION</samp></a> element has the <a href="forms.html#adef-selected" class=
"noxref"><samp class="ainst">selected</samp></a> attribute set, they should all
be pre-selected.</li>
<li>It is considered an error if more than one <a href="forms.html#edef-OPTION"
class="noxref"><samp class="einst">OPTION</samp></a> element has the <a href=
"forms.html#adef-selected" class="noxref"><samp class="ainst">
selected</samp></a> attribute set and the <a href="forms.html#edef-SELECT"
class="noxref"><samp class="einst">SELECT</samp></a> element does not have the
<a href="forms.html#adef-multiple" class="noxref"><samp class="ainst">
multiple</samp></a> attribute set. User agents may vary in how they handle this
error, but should not pre-select more than one choice.</li>
</ul>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-OPTGROUP" class="noxref"><samp class=
"einst">OPTGROUP</samp></a> - - (OPTION)+ -- option group -->
<!ATTLIST OPTGROUP
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst-OPTION">disabled</samp></a> (disabled) #IMPLIED -- unavailable in this context --
<a href="forms.html#adef-label-OPTGROUP" class="noxref"><samp class=
"ainst-OPTGROUP">label</samp></a> <a href=
"../sgml/dtd.html#Text">%Text;</a> #REQUIRED -- for use in hierarchical menus --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>OPTGROUP Attribute definitions</em></p>
<dl>
<dt><a name="adef-label-OPTGROUP"><samp class="adef">label</samp></a> = <a
href="../types.html#type-text"><em>text</em></a> <a href=
"../types.html#case-sensitive">[CS]</a></dt>
<dd>This attribute specifies the label for the option group.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> (<a href="#disabled">disabled input controls</a>)</li>
<li><a href="scripts.html#adef-onclick" class="noxref"><samp class="ainst">
onclick</samp></a>, <a href="scripts.html#adef-ondblclick" class="noxref"><samp
class="ainst">ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown"
class="noxref"><samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<div class="note">
<p><em><strong>Note.</strong> Implementors are advised that future versions of
HTML may extend the grouping mechanism to allow for nested groups (i.e., <a
href="forms.html#edef-OPTGROUP" class="noxref"><samp class="einst">
OPTGROUP</samp></a> elements may nest). This will allow authors to represent a
richer hierarchy of choices.</em></p>
</div>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-OPTION" class="noxref"><samp class=
"einst">OPTION</samp></a> - O (#PCDATA) -- selectable choice -->
<!ATTLIST OPTION
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-selected" class="noxref"><samp class=
"ainst-OPTION">selected</samp></a> (selected) #IMPLIED
<a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst-OPTION">disabled</samp></a> (disabled) #IMPLIED -- unavailable in this context --
<a href="forms.html#adef-label-OPTION" class="noxref"><samp class=
"ainst-OPTION">label</samp></a> <a href=
"../sgml/dtd.html#Text">%Text;</a> #IMPLIED -- for use in hierarchical menus --
<a href="forms.html#adef-value-OPTION" class="noxref"><samp class=
"ainst-OPTION">value</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED -- defaults to element content --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
optional</strong></em></p>
<div class="adef-list">
<p><em>OPTION Attribute definitions</em></p>
<dl>
<dt><a name="adef-selected"><samp class="adef">selected</samp></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>When set, this boolean attribute specifies that this option is
pre-selected.</dd>
<dt><a name="adef-value-OPTION"><samp class="adef">value</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-sensitive">[CS]</a></dt>
<dd>This attribute specifies the <a href="#initial-value">initial value</a> of
the control. If this attribute is not set, the <a href="#initial-value">initial
value</a> is set to the contents of the <a href="forms.html#edef-OPTION" class=
"noxref"><samp class="einst">OPTION</samp></a> element.</dd>
<dt><a name="adef-label-OPTION"><samp class="adef">label</samp></a> = <a href=
"../types.html#type-text"><em>text</em></a> <a href=
"../types.html#case-sensitive">[CS]</a></dt>
<dd>This attribute allows authors to specify a shorter label for an option than
the content of the <a href="forms.html#edef-OPTION" class="noxref"><samp class=
"einst">OPTION</samp></a> element. When specified, user agents should use the
value of this attribute rather than the content of the <a href=
"forms.html#edef-OPTION" class="noxref"><samp class="einst">OPTION</samp></a>
element as the option label.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> (<a href="#disabled">disabled input controls</a>)</li>
<li><a href="scripts.html#adef-onclick" class="noxref"><samp class="ainst">
onclick</samp></a>, <a href="scripts.html#adef-ondblclick" class="noxref"><samp
class="ainst">ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown"
class="noxref"><samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p><span class="index-inst" title="menu::rendering of choices"><a name=
"idx-menu-3">When rendering a menu choice</a></span>, user agents should use
the value of the <a href="forms.html#adef-label-OPTION" class="noxref"><samp
class="ainst-OPTION">label</samp></a> attribute of the <a href=
"forms.html#edef-OPTION" class="noxref"><samp class="einst">OPTION</samp></a>
element as the choice. If this attribute is not specified, user agents should
use the contents of the <a href="forms.html#edef-OPTION" class="noxref"><samp
class="einst">OPTION</samp></a> element.</p>
<p>The <a href="forms.html#adef-label-OPTGROUP" class="noxref"><samp class=
"ainst-OPTGROUP">label</samp></a> attribute of the <a href=
"forms.html#edef-OPTGROUP" class="noxref"><samp class="einst">
OPTGROUP</samp></a> element specifies the label for a group of choices.</p>
<div class="example">
<p>In this example, we create a menu that allows the user to select which of
seven software components to install. The first and second components are
pre-selected but may be deselected by the user. The remaining components are
not pre-selected. The <a href="forms.html#adef-size-SELECT" class="noxref">
<samp class="ainst-SELECT">size</samp></a> attribute states that the menu
should only have 4 rows even though the user may select from among 7 options.
The other options should be made available through a scrolling mechanism.</p>
<p>The <a href="forms.html#edef-SELECT" class="noxref"><samp class="einst">
SELECT</samp></a> is followed by submit and reset buttons.</p>
<pre>
<FORM action="http://somesite.com/prog/component-select" method="post">
<P>
<SELECT multiple size="4" name="component-select">
<OPTION selected value="Component_1_a">Component_1</OPTION>
<OPTION selected value="Component_1_b">Component_2</OPTION>
<OPTION>Component_3</OPTION>
<OPTION>Component_4</OPTION>
<OPTION>Component_5</OPTION>
<OPTION>Component_6</OPTION>
<OPTION>Component_7</OPTION>
</SELECT>
<INPUT type="submit" value="Send"><INPUT type="reset">
</P>
</FORM>
</pre>
<p>Only selected options will be <a href="#successful-controls">successful</a>
(using the <a href="#control-name">control name</a> "component-select"). When
no options are selected, the control is not successful and neither the name nor
any values are submitted to the server when the form is submitted. Note that
where the <a href="forms.html#adef-value-OPTION" class="noxref"><samp class=
"ainst-OPTION">value</samp></a> attribute is set, it determines the control's
<a href="#initial-value">initial value</a>, otherwise it's the element's
contents.</p>
</div>
<div class="example">
<p>In this example we use the <a href="forms.html#edef-OPTGROUP" class=
"noxref"><samp class="einst">OPTGROUP</samp></a> element to group choices. The
following markup:</p>
<pre>
<FORM action="http://somesite.com/prog/someprog" method="post">
<P>
<SELECT name="ComOS">
<OPTION selected label="none" value="none">None</OPTION>
<OPTGROUP label="PortMaster 3">
<OPTION label="3.7.1" value="pm3_3.7.1">PortMaster 3 with ComOS 3.7.1</OPTION>
<OPTION label="3.7" value="pm3_3.7">PortMaster 3 with ComOS 3.7</OPTION>
<OPTION label="3.5" value="pm3_3.5">PortMaster 3 with ComOS 3.5</OPTION>
</OPTGROUP>
<OPTGROUP label="PortMaster 2">
<OPTION label="3.7" value="pm2_3.7">PortMaster 2 with ComOS 3.7</OPTION>
<OPTION label="3.5" value="pm2_3.5">PortMaster 2 with ComOS 3.5</OPTION>
</OPTGROUP>
<OPTGROUP label="IRX">
<OPTION label="3.7R" value="IRX_3.7R">IRX with ComOS 3.7R</OPTION>
<OPTION label="3.5R" value="IRX_3.5R">IRX with ComOS 3.5R</OPTION>
</OPTGROUP>
</SELECT>
</FORM>
</pre>
<p>represents the following grouping:</p>
<pre>
None
PortMaster 3
3.7.1
3.7
3.5
PortMaster 2
3.7
3.5
IRX
3.7R
3.5R
</pre>
<p><span class="index-inst" title="menu::visual rendering of grouped options">
<a name="idx-menu-4">Visual user agents</a></span> may allow users to select
from option groups through a hierarchical menu or some other mechanism that
reflects the structure of choices.</p>
<p>A graphical user agent might render this as:</p>
<p><img src="../images/optgroup_exmpl.gif" alt=
"A possible rendering of OPTGROUP"></p>
<p>This image shows a <a href="forms.html#edef-SELECT" class="noxref"><samp
class="einst">SELECT</samp></a> element rendered as cascading menus. The top
label of the menu displays the currently selected value (PortMaster 3, 3.7.1).
The user has unfurled two cascading menus, but has not yet selected the new
value (PortMaster 2, 3.7). Note that each cascading menu displays the label of
an <a href="forms.html#edef-OPTGROUP" class="noxref"><samp class="einst">
OPTGROUP</samp></a> or <a href="forms.html#edef-OPTION" class="noxref"><samp
class="einst">OPTION</samp></a> element.</p>
</div>
<h2><a name="h-17.7">17.7</a> The <a name="edef-TEXTAREA"><samp class="edef">
TEXTAREA</samp></a> element</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-TEXTAREA" class="noxref"><samp class=
"einst">TEXTAREA</samp></a> - - (#PCDATA) -- multi-line text field -->
<!ATTLIST TEXTAREA
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-name-TEXTAREA" class="noxref"><samp class=
"ainst-TEXTAREA">name</samp></a> <a href=
"../types.html#type-cdata">CDATA</a> #IMPLIED
<a href="forms.html#adef-rows-TEXTAREA" class="noxref"><samp class=
"ainst-TEXTAREA">rows</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #REQUIRED
<a href="forms.html#adef-cols-TEXTAREA" class="noxref"><samp class=
"ainst-TEXTAREA">cols</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #REQUIRED
<a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst-TEXTAREA">disabled</samp></a> (disabled) #IMPLIED -- unavailable in this context --
<a href="forms.html#adef-readonly" class="noxref"><samp class=
"ainst-TEXTAREA">readonly</samp></a> (readonly) #IMPLIED
<a href="forms.html#adef-tabindex" class="noxref"><samp class=
"ainst-TEXTAREA">tabindex</samp></a> <a href=
"../types.html#type-number">NUMBER</a> #IMPLIED -- position in tabbing order --
<a href="forms.html#adef-accesskey" class="noxref"><samp class=
"ainst-TEXTAREA">accesskey</samp></a> <a href=
"../sgml/dtd.html#Character">%Character;</a> #IMPLIED -- accessibility key character --
<a href="scripts.html#adef-onfocus" class="noxref"><samp class=
"ainst-TEXTAREA">onfocus</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element got the focus --
<a href="scripts.html#adef-onblur" class="noxref"><samp class=
"ainst-TEXTAREA">onblur</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element lost the focus --
<a href="scripts.html#adef-onselect" class="noxref"><samp class=
"ainst-TEXTAREA">onselect</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- some text was selected --
<a href="scripts.html#adef-onchange" class="noxref"><samp class=
"ainst-TEXTAREA">onchange</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element value was changed --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-name-TEXTAREA"><samp class="adef">name</samp></a> = <a href=
"../types.html#type-cdata"><em>cdata</em></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>This attribute assigns the <a href="#control-name">control name.</a></dd>
<dt><a name="adef-rows-TEXTAREA"><samp class="adef">rows</samp></a> = <a href=
"../types.html#type-number"><em>number</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>This attribute specifies the number of visible text lines. Users should be
able to enter more lines than this, so user agents should provide some means to
scroll through the contents of the control when the contents extend beyond the
visible area.</dd>
<dt><a name="adef-cols-TEXTAREA"><samp class="adef">cols</samp></a> = <a href=
"../types.html#type-number"><em>number</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>This attribute specifies the visible width in average character widths.
Users should be able to enter longer lines than this, so user agents should
provide some means to scroll through the contents of the control when the
contents extend beyond the visible area. User agents may wrap visible text
lines to keep long lines visible without the need for scrolling.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-readonly" class="noxref"><samp class="ainst">
readonly</samp></a> (<a href="#read-only">read-only input controls</a>)</li>
<li><a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> (<a href="#disabled">disabled input controls</a>)</li>
<li><a href="forms.html#adef-tabindex" class="noxref"><samp class="ainst">
tabindex</samp></a> (<a href=
"../interact/forms.html#tabbing-navigation">tabbing navigation</a>)</li>
<li><a href="scripts.html#adef-onfocus" class="noxref"><samp class="ainst">
onfocus</samp></a>, <a href="scripts.html#adef-onblur" class="noxref"><samp
class="ainst">onblur</samp></a>, <a href="scripts.html#adef-onselect" class=
"noxref"><samp class="ainst">onselect</samp></a>, <a href=
"scripts.html#adef-onchange" class="noxref"><samp class="ainst">
onchange</samp></a>, <a href="scripts.html#adef-onclick" class="noxref"><samp
class="ainst">onclick</samp></a>, <a href="scripts.html#adef-ondblclick" class=
"noxref"><samp class="ainst">ondblclick</samp></a>, <a href=
"scripts.html#adef-onmousedown" class="noxref"><samp class="ainst">
onmousedown</samp></a>, <a href="scripts.html#adef-onmouseup" class="noxref">
<samp class="ainst">onmouseup</samp></a>, <a href=
"scripts.html#adef-onmouseover" class="noxref"><samp class="ainst">
onmouseover</samp></a>, <a href="scripts.html#adef-onmousemove" class="noxref">
<samp class="ainst">onmousemove</samp></a>, <a href=
"scripts.html#adef-onmouseout" class="noxref"><samp class="ainst">
onmouseout</samp></a>, <a href="scripts.html#adef-onkeypress" class="noxref">
<samp class="ainst">onkeypress</samp></a>, <a href=
"scripts.html#adef-onkeydown" class="noxref"><samp class="ainst">
onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup" class="noxref"><samp
class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p>The <a href="forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a> element creates a <span class="index-inst" title="text
input control::multi-line"><a name="idx-text_input_control-2">
multi-line</a></span> <a href="#text-input">text input</a> control. User agents
should use the contents of this element as the <a href="#initial-value">initial
value</a> of the control and should render this text initially.</p>
<div class="example">
<p>This example creates a <a href="forms.html#edef-TEXTAREA" class="noxref">
<samp class="einst">TEXTAREA</samp></a> control that is 20 rows by 80 columns
and contains two lines of text initially. The <a href=
"forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a> is followed by submit and reset buttons.</p>
<pre>
<FORM action="http://somesite.com/prog/text-read" method="post">
<P>
<TEXTAREA name="thetext" rows="20" cols="80">
First line of initial text.
Second line of initial text.
</TEXTAREA>
<INPUT type="submit" value="Send"><INPUT type="reset">
</P>
</FORM>
</pre>
<p>Setting the <a href="forms.html#adef-readonly" class="noxref"><samp class=
"ainst">readonly</samp></a> attribute allows authors to display unmodifiable
text in a <a href="forms.html#edef-TEXTAREA" class="noxref"><samp class=
"einst">TEXTAREA</samp></a>. This differs from using standard marked-up text in
a document because the value of <a href="forms.html#edef-TEXTAREA" class=
"noxref"><samp class="einst">TEXTAREA</samp></a> is submitted with the
form.</p>
</div>
<h2><a name="h-17.8">17.8</a> The <a name="edef-ISINDEX"><samp class="edef">
ISINDEX</samp></a> element</h2>
<p><strong>ISINDEX is <a href="../conform.html#deprecated">
deprecated</a>.</strong> This element creates a single-line <a href=
"#text-input">text input</a> control. Authors should use the <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a>
element to create <a href="#text-input">text input</a> controls.</p>
<p>See the <a href="../sgml/loosedtd.html#isindex">Transitional DTD</a> for the
formal definition.</p>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-prompt"><samp class="adef">prompt</samp></a> = <a href=
"../types.html#type-text"><em>text</em></a> <a href=
"../types.html#case-sensitive">[CS]</a></dt>
<dd><a href="../conform.html#deprecated"><strong>Deprecated.</strong></a> This
attribute specifies a prompt string for the input field.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
</ul>
</div>
<p>The <a href="forms.html#edef-ISINDEX" class="noxref"><samp class="einst">
ISINDEX</samp></a> element creates a single-line <a href="#text-input">text
input</a> control that allows any number of characters. User agents may use the
value of the <a href="forms.html#adef-prompt" class="noxref"><samp class=
"ainst">prompt</samp></a> attribute as a title for the prompt.</p>
<div class="deprecated-example">
<p><span class="example-title">DEPRECATED EXAMPLE:</span>
<br>
The following <a href="forms.html#edef-ISINDEX" class="noxref"><samp class=
"einst">ISINDEX</samp></a> declaration:</p>
<pre>
<ISINDEX prompt="Enter your search phrase: ">
</pre>
<p>could be rewritten with <a href="forms.html#edef-INPUT" class="noxref"><samp
class="einst">INPUT</samp></a> as follows:</p>
<pre>
<FORM action="..." method="post">
<P>Enter your search phrase: <INPUT type="text"></P>
</FORM>
</pre>
</div>
<div class="note">
<p><em><strong>Semantics of <samp class="einst">ISINDEX.</samp></strong>
Currently, the semantics for <a href="forms.html#edef-ISINDEX" class="noxref">
<samp class="einst">ISINDEX</samp></a> are only well-defined when the base URI
for the enclosing document is an HTTP URI. In practice, the input string is
restricted to Latin-1 as there is no mechanism for the URI to specify a
different character set.</em></p>
</div>
<h2><a name="h-17.9">17.9</a> <span class="index-inst" title="form::adding
labels to"><a name="form-labels">Labels</a></span></h2>
<p>Some form controls automatically have labels associated with them (press
buttons) while most do not (text fields, checkboxes and radio buttons, and
menus).</p>
<p>For those controls that have implicit labels, user agents should use the
value of the <samp class="ainst">value</samp> attribute as the label
string.</p>
<p>The <a href="forms.html#edef-LABEL" class="noxref"><samp class="einst">
LABEL</samp></a> element is used to specify labels for controls that do not
have implicit labels,</p>
<h3><a name="h-17.9.1">17.9.1</a> The <a name="edef-LABEL"><samp class="edef">
LABEL</samp></a> element</h3>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!ELEMENT <a href="forms.html#edef-LABEL" class="noxref"><samp class=
"einst">LABEL</samp></a> - - (<a href=
"../sgml/dtd.html#inline">%inline;</a>)* -(LABEL) -- form field label text -->
<!ATTLIST LABEL
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-for" class="noxref"><samp class=
"ainst-LABEL">for</samp></a> <a href=
"../types.html#type-idref">IDREF</a> #IMPLIED -- matches field ID value --
<a href="forms.html#adef-accesskey" class="noxref"><samp class=
"ainst-LABEL">accesskey</samp></a> <a href=
"../sgml/dtd.html#Character">%Character;</a> #IMPLIED -- accessibility key character --
<a href="scripts.html#adef-onfocus" class="noxref"><samp class=
"ainst-LABEL">onfocus</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element got the focus --
<a href="scripts.html#adef-onblur" class="noxref"><samp class=
"ainst-LABEL">onblur</samp></a> <a href=
"../sgml/dtd.html#Script">%Script;</a> #IMPLIED -- the element lost the focus --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-for"><samp class="adef">for</samp></a> = <a href=
"../types.html#type-idref"><em>idref</em></a> <a href=
"../types.html#case-sensitive">[CS]</a></dt>
<dd>This attribute explicitly associates the label being defined with another
control. When present, the value of this attribute must be the same as the
value of the <a href="../struct/global.html#adef-id" class="noxref"><samp
class="ainst">id</samp></a> attribute of some other control in the same
document. When absent, the label being defined is associated with the element's
contents.</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-accesskey" class="noxref"><samp class="ainst">
accesskey</samp></a> (<a href="../interact/forms.html#access-keys">access
keys</a>)</li>
<li><a href="scripts.html#adef-onfocus" class="noxref"><samp class="ainst">
onfocus</samp></a>, <a href="scripts.html#adef-onblur" class="noxref"><samp
class="ainst">onblur</samp></a>, <a href="scripts.html#adef-onclick" class=
"noxref"><samp class="ainst">onclick</samp></a>, <a href=
"scripts.html#adef-ondblclick" class="noxref"><samp class="ainst">
ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown" class="noxref">
<samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p>The <a href="forms.html#edef-LABEL" class="noxref"><samp class="einst">
LABEL</samp></a> element may be used to attach information to controls. Each <a
href="forms.html#edef-LABEL" class="noxref"><samp class="einst">
LABEL</samp></a> element is associated with exactly one form control.</p>
<p><span class="index-inst" title="label::explicit association with control">
The <a name="idx-label" href="forms.html#adef-for" class="noxref"><samp class=
"ainst">for</samp></a> attribute associates</span> a label with another control
explicitly: the value of the <a href="forms.html#adef-for" class="noxref"><samp
class="ainst">for</samp></a> attribute must be the same as the value of the <a
href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a> attribute of the associated control element. More than one <a
href="forms.html#edef-LABEL" class="noxref"><samp class="einst">
LABEL</samp></a> may be associated with the same control by creating multiple
references via the <a href="forms.html#adef-for" class="noxref"><samp class=
"ainst">for</samp></a> attribute.</p>
<div class="example">
<p>This example creates a table that is used to align two <a href=
"#text-input">text input</a> controls and their associated labels. Each label
is associated explicitly with one <a href="#text-input">text input</a>:</p>
<pre>
<FORM action="..." method="post">
<TABLE>
<TR>
<TD><LABEL for="fname">First Name</LABEL>
<TD><INPUT type="text" name="firstname" id="fname">
<TR>
<TD><LABEL for="lname">Last Name</LABEL>
<TD><INPUT type="text" name="lastname" id="lname">
</TABLE>
</FORM>
</pre>
</div>
<div class="example">
<p>This example extends a previous example form to include <a href=
"forms.html#edef-LABEL" class="noxref"><samp class="einst">LABEL</samp></a>
elements.</p>
<pre>
<FORM action="http://somesite.com/prog/adduser" method="post">
<P>
<LABEL for="firstname">First name: </LABEL>
<INPUT type="text" id="firstname"><BR>
<LABEL for="lastname">Last name: </LABEL>
<INPUT type="text" id="lastname"><BR>
<LABEL for="email">email: </LABEL>
<INPUT type="text" id="email"><BR>
<INPUT type="radio" name="sex" value="Male"> Male<BR>
<INPUT type="radio" name="sex" value="Female"> Female<BR>
<INPUT type="submit" value="Send"> <INPUT type="reset">
</P>
</FORM>
</pre>
</div>
<p><span class="index-inst" title="label::implicit association with control"><a
name="idx-label-1">To associate a label</a></span> with another control
implicitly, the control element must be within the contents of the <a href=
"forms.html#edef-LABEL" class="noxref"><samp class="einst">LABEL</samp></a>
element. In this case, the <a href="forms.html#edef-LABEL" class="noxref"><samp
class="einst">LABEL</samp></a> may only contain one control element. The label
itself may be positioned before or after the associated control.</p>
<div class="example">
<p>In this example, we implicitly associate two labels with two <a href=
"#text-input">text input</a> controls:</p>
<pre>
<FORM action="..." method="post">
<P>
<LABEL>
First Name
<INPUT type="text" name="firstname">
</LABEL>
<LABEL>
<INPUT type="text" name="lastname">
Last Name
</LABEL>
</P>
</FORM>
</pre>
<p>Note that this technique cannot be used when a table is being used for
layout, with the label in one cell and its associated control in another
cell.</p>
</div>
<p><span class="index-inst" title="label::and focus|focus::label gives to
control">When a <a name="idx-label-2" href="forms.html#edef-LABEL" class=
"noxref"><samp class="einst">LABEL</samp></a> element</span> receives <a href=
"#focus">focus</a>, it passes the focus on to its associated control. See the
section below on <a href="#access-keys">access keys</a> for examples.</p>
<p>Labels may be rendered by user agents in a number of ways (e.g., visually,
read by speech synthesizers, etc.)</p>
<h2><a name="h-17.10">17.10</a> <a name="form-structure">Adding structure to
forms:</a> the <a name="edef-FIELDSET"><samp class="edef">FIELDSET</samp></a>
and <a name="edef-LEGEND"><samp class="edef">LEGEND</samp></a> elements</h2>
<div class="dtd-fragment">
<pre class="dtd-fragment">
<!--
#PCDATA is to solve the mixed content problem,
per specification only whitespace is allowed there!
-->
<!ELEMENT <a href="forms.html#edef-FIELDSET" class="noxref"><samp class=
"einst">FIELDSET</samp></a> - - (#PCDATA,LEGEND,(<a href=
"../sgml/dtd.html#flow">%flow;</a>)*) -- form control group -->
<!ATTLIST FIELDSET
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
>
<!ELEMENT <a href="forms.html#edef-LEGEND" class="noxref"><samp class=
"einst">LEGEND</samp></a> - - (<a href=
"../sgml/dtd.html#inline">%inline;</a>)* -- fieldset legend -->
<!ATTLIST LEGEND
<a href=
"../sgml/dtd.html#attrs">%attrs;</a> -- <a href=
"../sgml/dtd.html#coreattrs">%coreattrs</a>, <a href=
"../sgml/dtd.html#i18n">%i18n</a>, <a href=
"../sgml/dtd.html#events">%events</a> --
<a href="forms.html#adef-accesskey" class="noxref"><samp class=
"ainst-LEGEND">accesskey</samp></a> <a href=
"../sgml/dtd.html#Character">%Character;</a> #IMPLIED -- accessibility key character --
>
</pre>
</div>
<p><em>Start tag: <strong>required</strong>, End tag: <strong>
required</strong></em></p>
<div class="adef-list">
<p><em>LEGEND Attribute definitions</em></p>
<dl>
<dt><a name="adef-align-LEGEND"><samp class="adef">align</samp></a> = <samp>
top|bottom|left|right</samp> <a href="../types.html#case-insensitive">
[CI]</a></dt>
<dd><a href="../conform.html#deprecated"><strong>Deprecated.</strong></a> This
attribute specifies the position of the legend with respect to the fieldset.
Possible values:
<ul>
<li><samp>top:</samp> The legend is at the top of the fieldset. This is the
default value.</li>
<li><samp>bottom:</samp> The legend is at the bottom of the fieldset.</li>
<li><samp>left:</samp> The legend is at the left side of the fieldset.</li>
<li><samp>right:</samp> The legend is at the right side of the fieldset.</li>
</ul>
</dd>
</dl>
</div>
<div class="aref-list">
<p><em>Attributes defined elsewhere</em></p>
<ul>
<li><a href="../struct/global.html#adef-id" class="noxref"><samp class="ainst">
id</samp></a>, <a href="../struct/global.html#adef-class" class="noxref"><samp
class="ainst">class</samp></a> (<a href=
"../struct/global.html#id-and-class">document-wide identifiers</a>)</li>
<li><a href="../struct/dirlang.html#adef-lang" class="noxref"><samp class=
"ainst">lang</samp></a> (<a href=
"../struct/dirlang.html#language-info">language information</a>), <a href=
"../struct/dirlang.html#adef-dir" class="noxref"><samp class="ainst">
dir</samp></a> (<a href="../struct/dirlang.html#bidirection">text
direction</a>)</li>
<li><a href="../struct/global.html#adef-title" class="noxref"><samp class=
"ainst">title</samp></a> (<a href="../struct/global.html#title">element
title</a>)</li>
<li><a href="../present/styles.html#adef-style" class="noxref"><samp class=
"ainst">style</samp></a> (<a href="../present/styles.html#style-element">inline
style information</a>)</li>
<li><a href="forms.html#adef-accesskey" class="noxref"><samp class="ainst">
accesskey</samp></a> (<a href="../interact/forms.html#access-keys">access
keys</a>)</li>
<li><a href="scripts.html#adef-onclick" class="noxref"><samp class="ainst">
onclick</samp></a>, <a href="scripts.html#adef-ondblclick" class="noxref"><samp
class="ainst">ondblclick</samp></a>, <a href="scripts.html#adef-onmousedown"
class="noxref"><samp class="ainst">onmousedown</samp></a>, <a href=
"scripts.html#adef-onmouseup" class="noxref"><samp class="ainst">
onmouseup</samp></a>, <a href="scripts.html#adef-onmouseover" class="noxref">
<samp class="ainst">onmouseover</samp></a>, <a href=
"scripts.html#adef-onmousemove" class="noxref"><samp class="ainst">
onmousemove</samp></a>, <a href="scripts.html#adef-onmouseout" class="noxref">
<samp class="ainst">onmouseout</samp></a>, <a href=
"scripts.html#adef-onkeypress" class="noxref"><samp class="ainst">
onkeypress</samp></a>, <a href="scripts.html#adef-onkeydown" class="noxref">
<samp class="ainst">onkeydown</samp></a>, <a href="scripts.html#adef-onkeyup"
class="noxref"><samp class="ainst">onkeyup</samp></a> (<a href=
"../interact/scripts.html#events">intrinsic events</a>)</li>
</ul>
</div>
<p><span class="index-inst" title="form::structuring controls in">The <a name=
"idx-form-6" href="forms.html#edef-FIELDSET" class="noxref"><samp class=
"einst">FIELDSET</samp></a> element</span> allows authors to group thematically
related controls and labels. Grouping controls makes it easier for users to
understand their purpose while simultaneously facilitating tabbing navigation
for visual user agents and speech navigation for speech-oriented user agents.
The proper use of this element makes documents more accessible.</p>
<p>The <a href="forms.html#edef-LEGEND" class="noxref"><samp class="einst">
LEGEND</samp></a> element allows authors to assign a caption to a <a href=
"forms.html#edef-FIELDSET" class="noxref"><samp class="einst">
FIELDSET</samp></a>. The legend improves accessibility when the <a href=
"forms.html#edef-FIELDSET" class="noxref"><samp class="einst">
FIELDSET</samp></a> is rendered non-visually.</p>
<div class="example">
<p>In this example, we create a form that one might fill out at the doctor's
office. It is divided into three sections: personal information, medical
history, and current medication. Each section contains controls for inputting
the appropriate information.</p>
<pre>
<FORM action="..." method="post">
<P>
<FIELDSET>
<LEGEND>Personal Information</LEGEND>
Last Name: <INPUT name="personal_lastname" type="text" tabindex="1">
First Name: <INPUT name="personal_firstname" type="text" tabindex="2">
Address: <INPUT name="personal_address" type="text" tabindex="3">
<em>...more personal information...</em>
</FIELDSET>
<FIELDSET>
<LEGEND>Medical History</LEGEND>
<INPUT name="history_illness"
type="checkbox"
value="Smallpox" tabindex="20"> Smallpox
<INPUT name="history_illness"
type="checkbox"
value="Mumps" tabindex="21"> Mumps
<INPUT name="history_illness"
type="checkbox"
value="Dizziness" tabindex="22"> Dizziness
<INPUT name="history_illness"
type="checkbox"
value="Sneezing" tabindex="23"> Sneezing
<em>...more medical history...</em>
</FIELDSET>
<FIELDSET>
<LEGEND>Current Medication</LEGEND>
Are you currently taking any medication?
<INPUT name="medication_now"
type="radio"
value="Yes" tabindex="35">Yes
<INPUT name="medication_now"
type="radio"
value="No" tabindex="35">No
If you are currently taking medication, please indicate
it in the space below:
<TEXTAREA name="current_medication"
rows="20" cols="50"
tabindex="40">
</TEXTAREA>
</FIELDSET>
</FORM>
</pre>
<p>Note that in this example, we might improve the visual presentation of the
form by aligning elements within each <a href="forms.html#edef-FIELDSET" class=
"noxref"><samp class="einst">FIELDSET</samp></a> (with style sheets), adding
color and font information (with style sheets), adding scripting (say, to only
open the "current medication" text area if the user indicates he or she is
currently on medication), etc.</p>
</div>
<h2><a name="h-17.11">17.11</a> <span class="index-def" title=
"focus|control::giving focus to"><a name="focus">Giving focus to an
element</a></span></h2>
<p>In an HTML document, an element must receive <dfn>focus</dfn> from the user
in order to become active and perform its tasks. For example, users must
activate a link specified by the <a href="../struct/links.html#edef-A" class=
"noxref"><samp class="einst">A</samp></a> element in order to follow the
specified link. Similarly, users must give a <a href="forms.html#edef-TEXTAREA"
class="noxref"><samp class="einst">TEXTAREA</samp></a> focus in order to enter
text into it.</p>
<p>There are several ways to give focus to an element:</p>
<ul>
<li>Designate the element with a pointing device.</li>
<li>Navigate from one element to the next with the keyboard. The document's
author may define a <em>tabbing order</em> that specifies the order in which
elements will receive focus if the user navigates the document with the
keyboard (see <a href="#tabbing-navigation">tabbing navigation</a>). Once
selected, an element may be activated by some other key sequence.</li>
<li>Select an element through an <a href="#access-keys"><em>access key</em></a>
(sometimes called "keyboard shortcut" or "keyboard accelerator").</li>
</ul>
<h3><a name="h-17.11.1">17.11.1</a> <span class="index-def" title=
"control::tabbing navigation|tabbing navigation|form::navigating through
controls"><a name="tabbing-navigation">Tabbing navigation</a></span></h3>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-tabindex"><samp class="adef">tabindex</samp></a> = <a href=
"../types.html#type-number"><em>number</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>This attribute specifies the position of the current element in the tabbing
order for the current document. This value must be a number between 0 and
32767. User agents should ignore leading zeros.</dd>
</dl>
</div>
<p><span class="index-def" title="tabbing order|form::tabbing order of
controls"><a name="didx-tabbing_order">The <dfn>tabbing order</dfn></a></span>
defines the order in which elements will receive focus when navigated by the
user via the keyboard. The tabbing order may include elements nested within
other elements.</p>
<p>Elements that may receive focus should be navigated by user agents according
to the following rules:</p>
<ol>
<li>Those elements that support the <a href="forms.html#adef-tabindex" class=
"noxref"><samp class="ainst">tabindex</samp></a> attribute and assign a
positive value to it are navigated first. Navigation proceeds from the element
with the lowest <a href="forms.html#adef-tabindex" class="noxref"><samp class=
"ainst">tabindex</samp></a> value to the element with the highest value. Values
need not be sequential nor must they begin with any particular value. Elements
that have identical <a href="forms.html#adef-tabindex" class="noxref"><samp
class="ainst">tabindex</samp></a> values should be navigated in the order they
appear in the character stream.</li>
<li>Those elements that do not support the <a href="forms.html#adef-tabindex"
class="noxref"><samp class="ainst">tabindex</samp></a> attribute or support it
and assign it a value of "0" are navigated next. These elements are navigated
in the order they appear in the character stream.</li>
<li>Elements that are <a href="#disabled">disabled</a> do not participate in
the tabbing order.</li>
</ol>
<p>The following elements support the <a href="forms.html#adef-tabindex" class=
"noxref"><samp class="ainst">tabindex</samp></a> attribute: <a href=
"../struct/links.html#edef-A" class="noxref"><samp class="einst">A</samp></a>,
<a href="../struct/objects.html#edef-AREA" class="noxref"><samp class="einst">
AREA</samp></a>, <a href="forms.html#edef-BUTTON" class="noxref"><samp class=
"einst">BUTTON</samp></a>, <a href="forms.html#edef-INPUT" class="noxref"><samp
class="einst">INPUT</samp></a>, <a href="../struct/objects.html#edef-OBJECT"
class="noxref"><samp class="einst">OBJECT</samp></a>, <a href=
"forms.html#edef-SELECT" class="noxref"><samp class="einst">SELECT</samp></a>,
and <a href="forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a>.</p>
<div class="example">
<p>In this example, the tabbing order will be the <a href=
"forms.html#edef-BUTTON" class="noxref"><samp class="einst">BUTTON</samp></a>,
the <a href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a> elements in order (note that "field1" and the button share the
same tabindex, but "field1" appears later in the character stream), and finally
the link created by the <a href="../struct/links.html#edef-A" class="noxref">
<samp class="einst">A</samp></a> element.</p>
<pre>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<TITLE>A document with FORM</TITLE>
</HEAD>
<BODY>
<em>...some text...</em>
<P>Go to the
<A tabindex="10" href="http://www.w3.org/">W3C Web site.</A>
<em>...some more...</em>
<BUTTON type="button" name="get-database"
tabindex="1" onclick="get-database">
Get the current database.
</BUTTON>
<em>...some more...</em>
<FORM action="..." method="post">
<P>
<INPUT tabindex="1" type="text" name="field1">
<INPUT tabindex="2" type="text" name="field2">
<INPUT tabindex="3" type="submit" name="submit">
</P>
</FORM>
</BODY>
</HTML>
</pre>
</div>
<div class="note">
<p><em><strong>Tabbing keys.</strong> The actual key sequence that causes
tabbing navigation or element activation depends on the configuration of the
user agent (e.g., the "tab" key is used for navigation and the "enter" key is
used to activate a selected element).</em></p>
<p><em>User agents may also define key sequences to navigate the tabbing order
in reverse. When the end (or beginning) of the tabbing order is reached, user
agents may circle back to the beginning (or end).</em></p>
</div>
<h3><a name="h-17.11.2">17.11.2</a> <span class="index-def" title="access
key|control::access key for|accessibility::access keys"><a name="access-keys">
Access keys</a></span></h3>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-accesskey"><samp class="adef">accesskey</samp></a> = <a href=
"../types.html#type-character"><em>character</em></a> <a href=
"../types.html#case-neutral">[CN]</a></dt>
<dd>This attribute assigns an access key to an element. <span class=
"index-inst" title="characters::access key"><a name="idx-characters">An access
key</a></span> is a single character from the document character set. <strong>
Note.</strong> Authors should consider the input method of the expected reader
when specifying an accesskey.</dd>
</dl>
</div>
<p><span class="index-inst" title="focus::and access key"><a name=
"idx-focus-2">Pressing an access key assigned to an element gives focus to the
element.</a></span> The action that occurs when an element receives focus
depends on the element. For example, when a user activates a link defined by
the <a href="../struct/links.html#edef-A" class="noxref"><samp class="einst">
A</samp></a> element, the user agent generally follows the link. When a user
activates a radio button, the user agent changes the value of the radio button.
When the user activates a text field, it allows input, etc.</p>
<p>The following elements support the <a href="forms.html#adef-accesskey"
class="noxref"><samp class="ainst">accesskey</samp></a> attribute: <a href=
"../struct/links.html#edef-A" class="noxref"><samp class="einst">A</samp></a>,
<a href="../struct/objects.html#edef-AREA" class="noxref"><samp class="einst">
AREA</samp></a>, <a href="forms.html#edef-BUTTON" class="noxref"><samp class=
"einst">BUTTON</samp></a>, <a href="forms.html#edef-INPUT" class="noxref"><samp
class="einst">INPUT</samp></a>, <a href="forms.html#edef-LABEL" class="noxref">
<samp class="einst">LABEL</samp></a>, and <a href="forms.html#edef-LEGEND"
class="noxref"><samp class="einst">LEGEND</samp></a>, and <a href=
"forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a>.</p>
<div class="example">
<p>This example assigns the access key "U" to a label associated with an <a
href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a> control. Typing the access key gives focus to the label which
in turn gives it to the associated control. The user may then enter text into
the <a href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a> area.</p>
<pre>
<FORM action="..." method="post">
<P>
<LABEL for="fuser" accesskey="U">
User Name
</LABEL>
<INPUT type="text" name="user" id="fuser">
</P>
</FORM>
</pre>
</div>
<div class="example">
<p>In this example, we assign an access key to a link defined by the <a href=
"../struct/links.html#edef-A" class="noxref"><samp class="einst">A</samp></a>
element. Typing this access key takes the user to another document, in this
case, a table of contents.</p>
<pre>
<P><A accesskey="C"
rel="contents"
href="http://someplace.com/specification/contents.html">
Table of Contents</A>
</pre>
</div>
<p>The invocation of access keys depends on the underlying system. For
instance, on machines running MS Windows, one generally has to press the "alt"
key in addition to the access key. On Apple systems, one generally has to press
the "cmd" key in addition to the access key.</p>
<p>The rendering of access keys depends on the user agent. We recommend that
authors include the access key in label text or wherever the access key is to
apply. User agents should render the value of an access key in such a way as to
emphasize its role and to distinguish it from other characters (e.g., by
underlining it).</p>
<h2><a name="h-17.12">17.12</a> <a name="disabled-read-only">Disabled and
read-only controls</a></h2>
<p>In contexts where user input is either undesirable or irrelevant, it is
important to be able to disable a control or render it read-only. For example,
one may want to disable a form's submit button until the user has entered some
required data. Similarly, an author may want to include a piece of read-only
text that must be submitted as a value along with the form. The following
sections describe disabled and read-only controls.</p>
<h3><a name="h-17.12.1">17.12.1</a> <span class="index-inst" title=
"control::disabled|disabled controls"><a name="disabled">Disabled
controls</a></span></h3>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-disabled"><samp class="adef">disabled</samp></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>When set for a form control, this boolean attribute disables the control
for user input.</dd>
</dl>
</div>
<p>When set, the <a href="forms.html#adef-disabled" class="noxref"><samp class=
"ainst">disabled</samp></a> attribute has the following effects on an
element:</p>
<ul>
<li>Disabled controls do not receive <a href="#focus">focus</a>.</li>
<li>Disabled controls are skipped in <a href="#tabbing-navigation">tabbing
navigation</a>.</li>
<li>Disabled controls cannot be <a href="#successful-controls">
successful</a>.</li>
</ul>
<p>The following elements support the <a href="forms.html#adef-disabled" class=
"noxref"><samp class="ainst">disabled</samp></a> attribute: <a href=
"forms.html#edef-BUTTON" class="noxref"><samp class="einst">BUTTON</samp></a>,
<a href="forms.html#edef-INPUT" class="noxref"><samp class="einst">
INPUT</samp></a>, <a href="forms.html#edef-OPTGROUP" class="noxref"><samp
class="einst">OPTGROUP</samp></a>, <a href="forms.html#edef-OPTION" class=
"noxref"><samp class="einst">OPTION</samp></a>, <a href=
"forms.html#edef-SELECT" class="noxref"><samp class="einst">SELECT</samp></a>,
and <a href="forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a>.</p>
<p>This attribute is inherited but local declarations override the inherited
value.</p>
<p>How disabled elements are rendered depends on the user agent. For example,
some user agents "gray out" disabled menu items, button labels, etc.</p>
<div class="example">
<p>In this example, the <a href="forms.html#edef-INPUT" class="noxref"><samp
class="einst">INPUT</samp></a> element is disabled. Therefore, it cannot
receive user input nor will its value be submitted with the form.</p>
<pre>
<INPUT disabled name="fred" value="stone">
</pre>
</div>
<div class="note">
<p><em><strong>Note.</strong> The only way to modify dynamically the value of
the <a href="forms.html#adef-disabled" class="noxref"><samp class="ainst">
disabled</samp></a> attribute is through a <a href="scripts.html">
script.</a></em></p>
</div>
<h3><a name="h-17.12.2">17.12.2</a> <span class="index-inst" title=
"control::read only|read only controls"><a name="read-only">Read-only
controls</a></span></h3>
<div class="adef-list">
<p><em>Attribute definitions</em></p>
<dl>
<dt><a name="adef-readonly"><samp class="adef">readonly</samp></a> <a href=
"../types.html#case-insensitive">[CI]</a></dt>
<dd>When set for a form control, this boolean attribute prohibits changes to
the control.</dd>
</dl>
</div>
<p>The <a href="forms.html#adef-readonly" class="noxref"><samp class="ainst">
readonly</samp></a> attribute specifies whether the control may be modified by
the user.</p>
<p>When set, the <a href="forms.html#adef-readonly" class="noxref"><samp class=
"ainst">readonly</samp></a> attribute has the following effects on an
element:</p>
<ul>
<li>Read-only elements receive <a href="#focus">focus</a> but cannot be
modified by the user.</li>
<li>Read-only elements are included in <a href="#tabbing-navigation">tabbing
navigation</a>.</li>
<li>Read-only elements may be <a href="#successful-controls">
successful</a>.</li>
</ul>
<p>The following elements support the <a href="forms.html#adef-readonly" class=
"noxref"><samp class="ainst">readonly</samp></a> attribute: <a href=
"forms.html#edef-INPUT" class="noxref"><samp class="einst">INPUT</samp></a> and
<a href="forms.html#edef-TEXTAREA" class="noxref"><samp class="einst">
TEXTAREA</samp></a>.</p>
<p>How read-only elements are rendered depends on the user agent.</p>
<div class="note">
<p><em><strong>Note.</strong> The only way to modify dynamically the value of
the <a href="forms.html#adef-readonly" class="noxref"><samp class="ainst">
readonly</samp></a> attribute is through a <a href="scripts.html">
script.</a></em></p>
</div>
<h2><a name="h-17.13">17.13</a> <span class="index-inst" title=
"form::submission of"><a name="submit-format">Form submission</a></span></h2>
<p>The following sections explain how user agents submit form data to form
processing agents.</p>
<h3><a name="h-17.13.1">17.13.1</a> <span class="index-inst" title=
"form::submission method of|GET::and form submission|POST::and form
submission|HTTP::GET and POST with forms"><a name="idx-form-8">Form submission
method</a></span></h3>
<p>The <a href="forms.html#adef-method" class="noxref"><samp class="ainst">
method</samp></a> attribute of the <a href="forms.html#edef-FORM" class=
"noxref"><samp class="einst">FORM</samp></a> element specifies the HTTP method
used to send the form to the processing agent. This attribute may take two
values:</p>
<ul>
<li><samp>get:</samp> With the HTTP "get" method, the <a href="#form-data-set">
form data set</a> is appended to the URI specified by the <a href=
"forms.html#adef-action" class="noxref"><samp class="ainst">action</samp></a>
attribute (with a question-mark ("?") as separator) and this new URI is sent to
the processing agent.</li>
<li><samp>post:</samp> With the HTTP "post" method, the <a href=
"#form-data-set">form data set</a> is included in the body of the form and sent
to the processing agent.</li>
</ul>
<p>The "get" method should be used when the form is idempotent (i.e., causes no
side-effects). Many database searches have no visible side-effects and make
ideal applications for the "get" method.</p>
<p>If the service associated with the processing of a form causes side effects
(for example, if the form modifies a database or subscription to a service),
the "post" method should be used.</p>
<div class="note">
<p><em><span class="index-inst" title="POST::for non-ASCII form data"><a name=
"idx-POST-1"><strong>Note.</strong></a></span> The "get" method restricts <a
href="#form-data-set">form data set</a> values to ASCII characters. Only the
"post" method (with <a href="forms.html#adef-enctype" class="noxref"><samp
class="ainst">enctype</samp></a>="multipart/form-data") is specified to cover
the entire <a rel="biblioentry" href="../references.html#ref-ISO10646" class=
"normref">[ISO10646]</a> character set.</em></p>
</div>
<h3><a name="h-17.13.2">17.13.2</a> <span class="index-inst" title=
"control::successful|successful control|form::values submitted"><a name=
"successful-controls">Successful controls</a></span></h3>
<p>A <dfn>successful control</dfn> is "valid" for submission. Every successful
control has its <a href="#control-name">control name</a> paired with its <a
href="#current-value">current value</a> as part of the submitted <a href=
"#form-data-set">form data set</a>. A successful control must be defined within
a <a href="forms.html#edef-FORM" class="noxref"><samp class="einst">
FORM</samp></a> element and must have a <a href="#control-name">control
name.</a></p>
<p>However:</p>
<ul>
<li><span class="index-inst" title="disabled controls::not successful"><a name=
"idx-disabled_controls-1">Controls</a></span> that are <a href="#disabled">
disabled</a> cannot be successful.</li>
<li>If a form contains more than one <a href="#buttons">submit button</a>, only
the activated submit button is successful.</li>
<li>All "on" <a href="#checkbox">checkboxes</a> may be successful.</li>
<li>For <a href="#radio">radio buttons</a> that share the same value of the <a
href="forms.html#adef-name-INPUT" class="noxref"><samp class="ainst-INPUT">
name</samp></a> attribute, only the "on" radio button may be successful.</li>
<li>For <a href="#menu">menus</a>, the <a href="#control-name">control name</a>
is provided by a <a href="forms.html#edef-SELECT" class="noxref"><samp class=
"einst">SELECT</samp></a> element and values are provided by <a href=
"forms.html#edef-OPTION" class="noxref"><samp class="einst">OPTION</samp></a>
elements. Only selected options may be successful. When no options are
selected, the control is not successful and neither the name nor any values are
submitted to the server when the form is submitted.</li>
<li><span class="index-inst" title="file select control::submission of">The <a
name="idx-file_select_control-1" href="#current-value">current value</a></span>
of a <a href="#file-select">file select</a> is a list of one or more file
names. Upon submission of the form, the <em>contents</em> of each file are
submitted with the rest of the form data. The file contents are packaged
according to the form's <a href="#form-content-type">content type</a>.</li>
<li>The current value of an object control is determined by the object's
implementation.</li>
</ul>
<p>If a control doesn't have a <a href="#current-value">current value</a> when
the form is submitted, user agents are not required to treat it as a successful
control.</p>
<p>Furthermore, user agents should not consider the following controls
successful:</p>
<ul>
<li><a href="#reset-button">Reset buttons.</a></li>
<li><span class="index-inst" title="object control"><a name=
"idx-object_control-1" href="../struct/objects.html#edef-OBJECT" class=
"noxref"><samp class="einst">OBJECT</samp></a> elements</span> whose <a href=
"../struct/objects.html#adef-declare" class="noxref"><samp class="ainst">
declare</samp></a> attribute has been set.</li>
</ul>
<p><span class="index-inst" title="hidden control"><a name=
"idx-hidden_control-1" href="#hidden-control">Hidden controls</a></span> and
controls that are not rendered because of <a href="../present/styles.html">
style sheet</a> settings may still be successful. For example:</p>
<div class="example">
<pre>
<FORM action="..." method="post">
<P>
<INPUT type="password" style="display:none"
name="invisible-password"
value="mypassword">
</FORM>
</pre>
<p>will still cause a value to be paired with the name "invisible-password" and
submitted with the form.</p>
</div>
<h3><a name="h-17.13.3">17.13.3</a> <span class="index-inst" title=
"form::processing controls of"><a name="form-data-processing">Processing form
data</a></span></h3>
<p>When the user submits a form (e.g., by activating a <a href=
"#submit-button">submit button</a>), the user agent processes it as
follows.</p>
<h4>Step one: Identify the <a href="#successful-controls">successful
controls</a><a name="h-17.13.3.1"> </a></h4>
<h4>Step two: Build a <a name="form-data-set">form data set</a><a name=
"h-17.13.3.2"> </a></h4>
<p><span class="index-def" title="form data set"><a name="didx-form_data_set">A
<dfn>form data set</dfn></a></span> is a sequence of <a href="#control-name">
control-name</a>/<a href="#current-value">current-value</a> pairs constructed
from <a href="#successful-controls">successful controls</a></p>
<h4><span class="index-inst" title="form::encoding data of|form data
set::encoding"><a name="idx-form-11">Step three: Encode the form data
set</a></span><a name="h-17.13.3.3"> </a></h4>
<p>The form data set is then encoded according to the <a href=
"#form-content-type">content type</a> specified by the <a href=
"forms.html#adef-enctype" class="noxref"><samp class="ainst">enctype</samp></a>
attribute of the <a href="forms.html#edef-FORM" class="noxref"><samp class=
"einst">FORM</samp></a> element.</p>
<h4><span class="index-inst" title="form::methods and actions"><a name=
"idx-form-12">Step four: Submit the encoded form data set</a></span><a name=
"h-17.13.3.4"> </a></h4>
<p>Finally, the encoded data is sent to the processing agent designated by the
<a href="forms.html#adef-action" class="noxref"><samp class="ainst">
action</samp></a> attribute using the protocol specified by the <a href=
"forms.html#adef-method" class="noxref"><samp class="ainst">method</samp></a>
attribute.</p>
<p>This specification does not specify all valid submission methods or <a href=
"#form-content-type">content types</a> that may be used with forms. However,
HTML 4 user agents must support the established conventions in the following
cases:</p>
<ul>
<li>If the <a href="forms.html#adef-method" class="noxref"><samp class="ainst">
method</samp></a> is "get" and the <a href="forms.html#adef-action" class=
"noxref"><samp class="ainst">action</samp></a> is an HTTP URI, the user agent
takes the value of <a href="forms.html#adef-action" class="noxref"><samp class=
"ainst">action</samp></a>, appends a <samp>`?'</samp> to it, then appends the
<a href="#form-data-set">form data set</a>, encoded using the
"application/x-www-form-urlencoded" <a href="#form-content-type">content
type</a>. The user agent then traverses the link to this URI. In this scenario,
form data are restricted to ASCII codes.</li>
<li>If the <a href="forms.html#adef-method" class="noxref"><samp class="ainst">
method</samp></a> is "post" and the <a href="forms.html#adef-action" class=
"noxref"><samp class="ainst">action</samp></a> is an HTTP URI, the user agent
conducts an HTTP "post" transaction using the value of the <a href=
"forms.html#adef-action" class="noxref"><samp class="ainst">action</samp></a>
attribute and a message created according to the <a href="#form-content-type">
content type</a> specified by the <a href="forms.html#adef-enctype" class=
"noxref"><samp class="ainst">enctype</samp></a> attribute.</li>
</ul>
<p>For any other value of <a href="forms.html#adef-action" class="noxref"><samp
class="ainst">action</samp></a> or <a href="forms.html#adef-method" class=
"noxref"><samp class="ainst">method</samp></a>, behavior is unspecified.</p>
<p>User agents should render the response from the HTTP "get" and "post"
transactions.</p>
<h3><a name="h-17.13.4">17.13.4</a> <span class="index-inst" title=
"form::content types for encoding|content types::for encoding form data"><a
name="form-content-type">Form content types</a></span></h3>
<p>The <a href="forms.html#adef-enctype" class="noxref"><samp class="ainst">
enctype</samp></a> attribute of the <a href="forms.html#edef-FORM" class=
"noxref"><samp class="einst">FORM</samp></a> element specifies the <a href=
"../types.html#type-content-type">content type</a> used to encode the <a href=
"#form-data-set">form data set</a> for submission to the server. User agents
must support the content types listed below. Behavior for other content types
is unspecified.</p>
<p>Please also consult the section on <a href=
"../appendix/notes.html#ampersands-in-uris">escaping ampersands in URI
attribute values</a>.</p>
<h4><span class="index-def" title="application/x-www-form-urlencoded|content
type::application/x-www-form-urlencoded"><a name=
"didx-applicationx-www-form-urlencoded">
application/x-www-form-urlencoded</a></span> <a name="h-17.13.4.1">
</a></h4>
<p>This is the default content type. Forms submitted with this content type
must be encoded as follows:</p>
<ol>
<li>Control names and values are escaped. Space characters are replaced by
<samp>`+'</samp>, and then reserved characters are escaped as described in <a
rel="biblioentry" href="../references.html#ref-RFC1738" class="normref">
[RFC1738]</a>, section 2.2: Non-alphanumeric characters are replaced by <samp>
`%HH'</samp>, a percent sign and two hexadecimal digits representing the ASCII
code of the character. Line breaks are represented as "CR LF" pairs (i.e.,
<samp>`%0D%0A'</samp>).</li>
<li>The control names/values are listed in the order they appear in the
document. The name is separated from the value by <samp>`='</samp> and
name/value pairs are separated from each other by <samp>`&'</samp>.</li>
</ol>
<h4><span class="index-def" title="multipart/form-data|content
type::multipart/form-data"><a name="didx-multipartform-data">
multipart/form-data</a></span> <a name="h-17.13.4.2"> </a></h4>
<div class="note">
<p><em><strong>Note.</strong> Please consult <a rel="biblioentry" href=
"../references.html#ref-RFC2388" class="informref">[RFC2388]</a> for additional
information about file uploads, including backwards compatibility issues, the
relationship between "multipart/form-data" and other content types, performance
issues, etc.</em></p>
<p><em>Please consult the appendix for information about <a href=
"../appendix/notes.html#forms-security">security issues for forms</a>.</em></p>
</div>
<p>The content type "application/x-www-form-urlencoded" is inefficient for
sending large quantities of binary data or text containing non-ASCII
characters. The content type "multipart/form-data" should be used for
submitting forms that contain files, non-ASCII data, and binary data.</p>
<p>The content "multipart/form-data" follows the rules of all multipart MIME
data streams as outlined in <a rel="biblioentry" href=
"../references.html#ref-RFC2045" class="normref">[RFC2045]</a>. The definition
of "multipart/form-data" is available at the <a rel="biblioentry" href=
"../references.html#ref-IANA">[IANA]</a> registry.</p>
<p>A "multipart/form-data" message contains a series of parts, each
representing a <a href="#successful-controls">successful control</a>. The parts
are sent to the processing agent in the same order the corresponding controls
appear in the document stream. Part boundaries should not occur in any of the
data; how this is done lies outside the scope of this specification.</p>
<p>As with all multipart MIME types, each part has an optional "Content-Type"
header that defaults to "text/plain". User agents should supply the
"Content-Type" header, accompanied by a "charset" parameter.</p>
<p>Each part is expected to contain:</p>
<ol>
<li>a "Content-Disposition" header whose value is "form-data".</li>
<li>a name attribute specifying the <a href="#control-name">control name</a> of
the corresponding control. Control names originally encoded in non-ASCII <a
href="../charset.html">character sets</a> may be encoded using the method
outlined in <a rel="biblioentry" href="../references.html#ref-RFC2045" class=
"normref">[RFC2045]</a>.</li>
</ol>
<p>Thus, for example, for a control named "mycontrol", the corresponding part
would be specified:</p>
<pre>
Content-Disposition: form-data; name="mycontrol"
</pre>
<p>As with all MIME transmissions, "CR LF" (i.e., <samp>`%0D%0A'</samp>) is
used to separate lines of data.</p>
<p>Each part may be encoded and the "Content-Transfer-Encoding" header supplied
if the value of that part does not conform to the default (7BIT) encoding (see
<a rel="biblioentry" href="../references.html#ref-RFC2045" class="normref">
[RFC2045]</a>, section 6)</p>
<p>If the contents of a file are submitted with a form, the file input should
be identified by the appropriate <a href="../types.html#type-content-type">
content type</a> (e.g., "application/octet-stream"). If multiple files are to
be returned as the result of a single form entry, they should be returned as
"multipart/mixed" embedded within the "multipart/form-data".</p>
<p>The user agent should attempt to supply a file name for each submitted file.
The file name may be specified with the "filename" parameter of the
'Content-Disposition: form-data' header, or, in the case of multiple files, in
a 'Content-Disposition: file' header of the subpart. If the file name of the
client's operating system is not in US-ASCII, the file name might be
approximated or encoded using the method of <a rel="biblioentry" href=
"../references.html#ref-RFC2045" class="normref">[RFC2045]</a>. This is
convenient for those cases where, for example, the uploaded files might contain
references to each other (e.g., a TeX file and its ".sty" auxiliary style
description).</p>
<p>The following example illustrates "multipart/form-data" encoding. Suppose we
have the following form:</p>
<div class="example">
<pre>
<FORM action="http://server.com/cgi/handle"
enctype="multipart/form-data"
method="post">
<P>
What is your name? <INPUT type="text" name="submit-name"><BR>
What files are you sending? <INPUT type="file" name="files"><BR>
<INPUT type="submit" value="Send"> <INPUT type="reset">
</FORM>
</pre>
</div>
<p>If the user enters "Larry" in the text input, and selects the text file
"file1.txt", the user agent might send back the following data:</p>
<pre>
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="submit-name"
Larry
--AaB03x
Content-Disposition: form-data; name="files"; filename="file1.txt"
Content-Type: text/plain
... contents of file1.txt ...
--AaB03x--
</pre>
<p>If the user selected a second (image) file "file2.gif", the user agent might
construct the parts as follows:</p>
<pre>
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="submit-name"
Larry
--AaB03x
Content-Disposition: form-data; name="files"
Content-Type: multipart/mixed; boundary=BbC04y
--BbC04y
Content-Disposition: file; filename="file1.txt"
Content-Type: text/plain
... contents of file1.txt ...
--BbC04y
Content-Disposition: file; filename="file2.gif"
Content-Type: image/gif
Content-Transfer-Encoding: binary
...contents of file2.gif...
--BbC04y--
--AaB03x--
</pre>
<div class="navbar" align="center">
<hr><a href="../present/frames.html">previous</a> <a href=
"scripts.html">next</a> <a href="../cover.html#minitoc">contents</a>
<a href="../index/elements.html">elements</a> <a href=
"../index/attributes.html">attributes</a> <a href="../index/list.html">
index</a></div>
</body>
</html>