This is an update to the forms features found in HTML4's Forms chapter, which are informally referred to as Web Forms 1.0.
Authors have long requested enhancements to HTML4 to support some of their more common needs. Such requests in mailing lists and other forums were examined, and from these sources a set of requirements and design goals were derived:
Not all the desired features have been included in this specification. Future versions may be introduced to address further needs.
This specification does not describe the complete behaviour of an HTML or XHTML user agent. Readers are expected to refer to the existing specifications for the definitions of features that this specification does not change.
This specification is limited specifically to incremental improvements to existing wide-spread technologies, namely HTML4 and the DOM, as implemented by browsers prevalent in 2004. It is also intended to be a small step, implementable without overwhelming effort.
Large sweeping changes or new markup languages are therefore out of scope for this specification.
This specification clarifies and extends the semantics put forth in [HTML4] for form controls and form submission. It is expected to be implemented in ordinary HTML user agents alongside existing forms technology, and indeed, some of the features described in this draft have been implemented by user agents as ad-hoc, non-standard extensions for many years due to strong market demand.
This specification can also be viewed as an extension to [XHTML1]. In particular, some of the features added in this module only apply to XHTML documents; for example, features allowing mixed namespaces.
This specification is a prototype for what will become HTML5. It will eventually be merged with other proposals, such as those in the WHATWG Web Applications 1.0 draft, to form the HTML5 and XHTML5 languages.
This specification is written as a set of "patches" to the existing HTML4 and DOM2 specifications. This is not a particularly effective model for a specification. However, rather than rewrite this specification to address this, the intention is to wait until the features are merged into HTML5 before addressing problems that arise from the current frankensteinesque style. [HTML5]
This specification clarifies and extends the semantics put forth in [DOM2HTML] for the form control interfaces. These extensions are expected to be implemented in HTML and XHTML user agents that support the DOM.
This section is aimed at XForms authors and implementors. If you do not plan to use XForms, you may prefer to skip ahead to the next section. Knowledge of XForms is not required to use Web Forms.
This specification is in no way aimed at replacing XForms 1.0 [XForms], nor is it a subset of XForms 1.0.
XForms 1.0 is well suited for describing business logic and data constraints. Web Forms 2.0 aims to simplify the task of transforming XForms 1.0 systems into documents that can be rendered on HTML Web browsers that do not support XForms.
In this transformation model, the XForms processor is a server-side process that converts XForms and XML Schema documents, according to the XForms specification, into HTML and Web Forms documents, which are then processed by the client side Web Forms processor, along with a style sheet for presentation.
The structured XML instance data stored on the server side (e.g. in a database) is converted by the XForms processor into name/value pairs that are then used by the UA to prefill the form. Submission follows the opposite path, with the UA generating name/value pairs and sending them to the XForms processor on the server, which converts them back into structured XML for storage or further processing.
In order to simplify this transformation process, this specification attempts to add some of the functionality of XForms with a minimum impact on the existing, widely implemented forms model. Where appropriate, backwards compatibility, ease of authoring, and ease of implementation have been given priority over theoretical purity.
The following features of XForms have not been addressed:
Many of the less-used features that XForms supports using declarative syntax are, in this specification, handled by using scripting. Some new interfaces are introduced to simplify some of the more tedious tasks.
This specification does not extend CSS, but it does attempt to clarify some of the interactions between HTML's form features and CSS.
This draft does not address all needs. In addition to the features of XForms that have not been addressed (see above), the following features were considered but rejected for this version of the specification:
Conformance to this specification is defined for user agents (UAs, implementations) and documents (authors, authoring tools, markup generators). Clauses specify whether they apply to user agents or documents.
User agents could include graphical Web browsers, voice-based
mobile devices, automated agents, content indexing robots, and
inference tools. In certain user agents, it may be impossible to
determine whether a particular conformance criteria is followed or
not. For instance, whether indexing robots mark the first option in
a select element as selected or not is not detectable.
When it is impossible to tell if a UA complies with a particular
conformance requirement, that UA is exempt from conforming to that
requirement.
Authoring tools and markup generators are conformant if they only produce conformant documents.
As well as sections marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
This specification includes by reference the form-related parts of the HTML4, XHTML1.1, DOM2 HTML, DOM3 Core, and DOM3 Events specifications ([HTML4], [XHTML1], [DOM2HTML], [DOM3CORE], [DOM3EVENTS]). Compliant UAs must implement all the forms-related requirements of those specifications, except those modified by this specification, to claim compliance with this one. Implementations may optionally implement only one of HTML4 and XHTML1.1.
Implementations and documents must comply to the W3C Character Model specification. [CHARMOD]
Implementations that do not support scripting (or which have their scripting features disabled) are exempt from supporting the events and DOM interfaces mentioned in this specification. For the parts of this specification that are defined in terms of an events model or in terms of the DOM, such user agents must still act as if events and the DOM were supported.
Scripting can form an integral part of an application. User agents that do not support scripting, or that have scripting disabled, might be unable to fully convey the author's intent.
This specification introduces attributes for setting the maximum size or range of certain values. While user agents should support all possible values, there may be implementation-specific limits.
HTML documents that use the new features described in this
specification and that are served over HTTP must be sent as
text/html and must use the following DOCTYPE:
<!DOCTYPE html>.
XML documents using elements from the XHTML namespace that use
the new features described in this specification and that are served
over HTTP must be sent using an XML MIME type such as
application/xml or application/xhtml+xml
and must not be served as text/html. [RFC3023]
These XML documents may contain a DOCTYPE if
desired, but this is not required.
Documents that use the new features described in this specification cannot be strictly conforming XHTML1.1 or HTML4 documents, since they contain features not defined in those specifications.
This specification refers to both HTML and XML attributes and DOM attributes, often in the same context. When it is not clear which is being referred to, they are referred to as content attributes for HTML and XML attributes, and DOM attributes for those from the DOM. Similarly, the term "properties" is used for both ECMAScript object properties and CSS properties. When these are ambiguous they are simply qualified as object properties and CSS properties respectively.
Generally, when the specification states that a feature applies to HTML or XHTML, it also includes the other. When a feature specifically only applies to one of the two languages, it is called out explicitly, as in:
Similarly,
formelements in XHTML may now be nested (this does not apply to HTML).
Unless otherwise stated, all XML elements defined or mentioned in
this specification are in the
http://www.w3.org/1999/xhtml namespace, and all
attributes defined or mentioned in this specification have no
namespace (they are in the per-element partition).
(There are elements from other namespaces in this specification,
in particular the XML submission format uses the
http://n.whatwg.org/formdata namespace.)
The term form control refers to input,
output, select, textarea and
button elements. It does not include form,
label, datalist, option,
optgroup, or fieldset elements.
Form controls are valid when they comply with their
constraints, and invalid when they don't. This is
distinct from whether form controls have their
willValidate attribute set to true, which
relates to whether they will be validated, or whether they are successful, which relates
to whether they will be submitted.
The terms URI and IRI in normative contexts are used as defined by [RFC3986] and [RFC3987].
When a comparison is said to be case-insensitive, the comparison must be performed using case folding, as described in Unicode. See Unicode 4.0, section 5.18 "Case Mappings", subsection "Caseless Matching". [UNICODE]
Vendor-specific proprietary extensions to this specification are strongly discouraged. Documents must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.
If markup extensions are needed, they should be done using XML, with elements or attributes from custom namespaces. If DOM extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions does not contradict nor cause the non-conformance of functionality defined in the specification.
For example, while strongly discouraged to do so, an
implementation "Foo Browser" could add a new DOM attribute
"fooTypeTime" to a control's DOM interface that returned the time
it took the user to select the current value of a control (say). On
the other hand, defining a new control that appears in a form's
elements array would be in violation of the above
requirement, as it would violate the definition of
elements given in this specification.
User agents must treat elements and attributes that they do not understand as semantically neutral; leaving them in the DOM (for DOM processors), and styling them according to CSS (for CSS processors), but not inferring any meaning from them.
The delivery of Web Forms 2 documents to the user from a remote host and the submission of data from the user to a remote host may be performed using a number of different protocols, and therefore no specific statements can be made regarding the security of those operations.
In general, authors are urged to use a secure transport layer such as TLS when information of a confidential nature is to be transmitted.
On the client side, implementors must be aware of a number of potential attacks. Since it is relatively easy for a hostile Web site to trick users into loading hostile content, for example by sending e-mails claiming to include links to photos of naked girls, users must be confident that a hostile site cannot access confidential information, perform denial-of-service attacks, or hijack the client's host to perform actions on behalf of the user that the user may not approve of.
Confidential information can be stored in several places. Documents from other servers loaded into other browsing contexts (e.g. other windows), documents from other servers that the hostile page has caused to be loaded (of particular concern being pages that include user-specific information using out-of-band authentication and/or authorisation information such as HTTP cookies, HTTP authentication, or the origin host), files on the local system, as well as details of the user's configuration are all potential sources of confidential information.
User agents must therefore implement security mechanisms to block cross-domain accesses (where local files are considered a separate domain). Such mechanisms are referred to as cross-domain scripting security mechanisms. Unfortunately, since it is difficult to predict exactly what attack vectors may exist in such a complex system, and in particular because it depends on the exact feature set of the implementation, this specification does not define the exact mechanism that must be implemented.
In practice user agents implement quite comprehensive cross-domain scripting security mechanisms. Implementation experience has shown that such security mechanisms must, at a minimum, prevent scripts originating from a site at one domain from accessing the properties and methods of any object (in particular, DOM nodes) associated with a page from another domain. Typically, such an access would cause an exception to be raised.
Denial of service attacks are naturally hard to prevent, since
they frequently are hard to distinguish from legitimate behaviour.
Implementors are encouraged to set arbitrary (although high) limits
on what an author can do. For instance, user agents might place a
limit on the length of the regular expression pattern allowed in the
pattern attribute, if a long expression could be made
to take unacceptably long to execute.
Implementations are also asked to consider how
otherwise-legitimate UI could be abused by a hostile page.
Naturally, since implementations are not restricted in how they
implement their interface, no specific guidelines can be given. One
example, however, would be the mailto: submission
feature. Since a script can artificially submit a form, it is
important that the UA not cause each submission to create a new mail
window, since this would allow authors to overwhelm the user with
windows containing author-specified text, which could act as both a
denial-of-service attack, and an annoying advertising technique.
Finally, user agent implementors should prevent pages and scripts in those pages from performing potentially harmful or embarassing actions on behalf of the user without the user's knowledge.
For example, it is recommended that user agents limit the ports to which forms may be submitted, excluding, in particular, ports of well-known protocols like SMTP or telnet. The SMTP port in particular has been used by hostile pages in the past as a target of form submissions for the relaying of spam by unsuspecting users.
Certain actions, including submitting a form to a third-party site and making HTTP GET requests to remote sites (both of which would be blind attacks, assuming the UA implements a cross-domain scripting security mechanism) have been historically allowed, and many sites depend on these features for quite legitimate uses. User agents should allow them.
Servers therefore must also consider security. Servers should
never perform non-idempotent actions in response to GET requests, as
discussed by the HTTP specification. Servers should also check the
Referer header to ensure that only requests from
trusted hosts are honoured.
Servers should also consider the client to be untrusted, since in most scenarios requests can be made to hosts by hostile parties directly, bypassing any security logic included in the page nominally intended to perform the submission. Thus servers should perform validation on all submitted data, whether such validation is expected to be performed on the client or not.
Further specific securiy considerations are called out where relevant.
This section describes how Web Forms 2.0 expands the traditional HTML form model to support new types and features.
This subsection is not normative.
One of the big additions to the Web Forms model introduced with this specification is primitive type and validity checking.
Authors can use these new features in various ways. To indicate
that a form control expects a particular type of input, authors can
specify the types using the type attribute:
<label>E-mail address: <input type="email" name="addr"></label> <label>Start date: <input type="date" name="start"></label>
To mark a control as required, the required attribute
can be used:
<label>Quantity: <input type="number" required="required" name="qty"></label>
To set the range of values that are allowed, the min
and max attributes can be used:
<label>Meeting time: <input type="time" min="09:00" max="17:00" name="mt"></label>
Once such constraints have been specified, the user agent will automatically guide the user through any errors he may have made before allowing the form to be submitted.
Authors can hook into this validation system with their scripts. There are several ways to do this.
At any point, scripts can check a control's validity
DOM attribute for up to date information on whether a control is
valid:
with (document.forms[0]) {
if (qty.validity.valueMissing) {
// the quantity control is required but not filled in
} else if (qty.validity.typeMismatch) {
// the quantity control is filled in, but it is not a number
}
}
An author can explicitly set a control as being invalid ("invalid" means that the control's value is not acceptable):
var myControl = document.forms[0].addr;
if (myControl.value == 'a@b.c') {
myControl.setCustomValidity('You must enter your real address.');
}
Authors can also override the normal user agent error reporting
behaviour by hooking into the invalid event:
<label>Home page: <input type="url" name="hp" required="required"
oninvalid="alert('You must enter a valid home page address.'); return false;">
</label>
HTML input elements use the type
attribute to specify the data type. In [HTML4], the types (as seen by the server) are
as follows:
textpasswordcheckboxradiosubmitfileimagehiddenIn addition, HTML also provides a few alternate elements that convey typing semantics similar to the above types, but use different content models:
selectradio type.select multiplecheckbox type.textareabuttonsubmit type but with a richer content model.The difference between the checkbox and
radio types and their select and
select multiple counterparts is that for the
select variants the values are only available through a
single composite control, whereas for the checkbox and
radio types the controls representing each value may be
individually placed around the document.
There are also two button types (available on both
input and button elements) that are never
submitted: button and reset.
This specification includes all of these types, their semantics, and their processing rules, by reference, for backwards compatibility.
These types are useful, but limited. This specification expands the list to cover more specific data types, and introduces attributes that are designed to constrain data entry or other aspects of the UA's behaviour.
In addition to the attributes described
below, some changes are made to the content model of HTML form
elements to take into account scripting needs. Specifically, the
form, legend,
select, and optgroup elements may now be
empty. However, with the exception of the form element, authors
should avoid allowing any of these elements to be both empty and
visible for any noticable period, as it is likely to confuse
users. In HTML4, those elements always required
at least one element child, or, in the case of legend,
at least one character of text.
Also, as controls no longer need to be
contained within their form element to be
associated with it, authors may prefer to declare their forms in
advance, at the top of their documents. The form element is
therefore allowed in the head element of XHTML
documents, although only when the form element is
empty. (This does not apply to HTML, where a
<form> tag has always implied the end of any
unclosed head element and the beginning of the
body.)
Similarly, form elements
in XHTML may now be nested (this does not apply to HTML, where a
<form> start tag nested in a form
element is typically ignored by UAs). Form controls by default
associate with their nearest form ancestor. Forms are not
semantically related to ancestor forms in any way, and do not share
attributes or form controls or events (except insofar as events
bubble up the DOM).
The children of a form
element must be block-level elements, unless one of the ancestors of
the form element is an element other than
div whose content model includes both block- and
inline-level content, in which case either block-level or
inline-level content is allowed (but not both). input
elements of type hidden may be placed anywhere (both in
inline contexts and block contexts).
The form and select elements are
extended with data
attributes for fetching values and options from external
resources.
Radio buttons in sets where none of the buttons are marked as checked must all be initially left unchecked by the UA (which differs from the behavior described in [RFC1866], but more accurately represents common implementation and author needs). Authors are recommended to always have one radio button selected. Having no radio buttons selected is considered very poor UI.
Radio buttons in sets where more than one button is marked as checked must all be initially left unchecked by the UA except for the last radio button marked as checked. Each time a checked radio button is inserted into the document, the UA must uncheck all the other radio buttons in that set in the document. Authors must not mark more than one radio button per set as being checked.
Previous versions of Web Forms were
inconsistent about whether the first option element of
a single-select select element with no
otherwise-selected items should be automatically selected. According
to [RFC1866], it should be, and according
to [HTML4] it was undefined. User agents
implementing this specification must select the first (non-disabled)
option element of a single-select select
element with no otherwise-selected items. (If all the items are
disabled or there are no items, then no item will be selected.)
The optgroup element may now be
nested inside other optgroup elements.
The label element's exact default
presentation and behaviour should match the platform's label
behaviour. For example, on platforms where clicking a checkbox label
checks the checkbox, clicking a label element should
cause a click event to be synthesised and fired at the
checkbox. In any case, events targeted at form controls (or other
interactive elements, e.g. links) within a label must not be handled
by the label itself.
User agents may establish a button in each form
as being the form's default button. (This should be the first submit
button in the form, but UAs may pick another button if another would
be more appropriate for the platform.) If the platform supports
letting the user submit a form implicitly (for example, on some
platforms hitting the "enter" key while a text field is focused
implicitly submits the form), then when doing so the form's default
submit button must be the one used to initiate form submission (and
it will therefore probably be successful).
To initiate for submission in such a case, the user agent must fire
a click event at the button's element, as if the user
had clicked the button himself.
Consequently, if the default button is disabled, the form must not be submitted when such an implicit submission mechanism is used. (The default action of a click on a disabled button is to do nothing.)
If there is no submit button, then the implicit submission
mechanism must submit the form as if there was an enabled, unnamed,
default button. No click event is fired in this
case.
Submit buttons can be associated with multiple forms, but only ever submit to the first form they are associated with. A default button for one form, therefore, could submit a different form when implicitly invoked than the form for which it is a default button. (This, however, is an edge case.)
For checkbox and radio form controls,
the value attribute defaults to the literal string
on, so that if the value content attribute
is not specified then the value DOM attribute (and the
value used for submission when the controls are checked) is
"on". For other controls the default is the empty
string.
The attributes defined in this specification as accepting a fixed
set of values (e.g. type) must be compared to those
values using a case-insensitive literal comparison.
Whitespace must not be trimmed from attribute values to make that
comparison.
Whitespace must also not be trimmed from any other attributes
(e.g. the value attribute).
Whitespace can get trimmed by the parser for other reasons; e.g. if an XML DTD is used, the XML specification can require certain attributes to have whitespace trimmed.
input elementSeveral new values are introduced for the type
attribute. As with the older types, UAs are recommended to show
specialized widgets for these types, instead of requiring that the
user enter the data into a text field.
The formats described below are those that UAs must use in the DOM and when submitting the data. They do not necessarily represent what the user is expected to type. User agents are expected to show suitable user interfaces for each of these types (e.g. using the user's locale settings). It is the UA's responsibility to convert the user's input into the specified format.
For most of these types, min, max and
step attributes can be applied to restrict the range of
numbers that apply.
datetimestep attribute specifies the precision in seconds,
defaulting to 60 (one minute).
User agents are expected to show an appropriate widget. UAs may display the time in whatever time zone is appropriate for the user, but should be clear to the user that the time is globally defined, not time-zone dependent. The submitted date and time must be in the UTC time zone.
datetime-localstep attribute specifies the precision in seconds,
defaulting to 60 (one minute).datestep attribute specifies
the precision in days, defaulting to 1. User agents are expected to
show an appropriate widget, such as a datepicker.monthstep
attribute specifies the precision in months, defaulting to 1. This
type is used most frequently for credit card expiry dates.weekstep attribute specifies the
precision in weeks, defaulting to 1. This type is used most
frequently for dates in European industry.timestep attribute specifies the precision in seconds,
defaulting to 60. Times must be greater than or equal to 0 and must
be less than 24 hours, in addition to any tighter restrictions
placed on the control by the min and max
attributes. Note that this type is not an elapsed time data type.
User agents are expected to show an appropriate widget, such as a clock. UAs should make it clear to the user that the time does not carry any time zone information.
numberA numerical value. The step attribute specifies
the precision, defaulting to 1.
Numbers must be submitted as a significand followed by an optional exponent. The significand is an optional minus sign (U+002D, "-"), an integer, and optionally a decimal point (U+002E, ".") and an integer representing the fractional part. The exponent is a lowercase literal letter "e", an optional minus sign, and an integer representing the index of a power of ten with which to multiply the significand to get the actual number. Integers are one or more decimal digits. If the exponent part is omitted its index of a power of ten must be assumed to be zero.
For example, negative-root-two, to 32 significant figures, would be -1.4142135623730950488016887242097e0, the radius of the earth given in furlongs, to an arbitrary precision, would be 3.17e4, and the answer to the life, the universe and everything could be any of (amongst others) 42, 0042.000, 42e0, 4.2e1, or 420e-1.
This format is designed to be compatible with
scanf(3)'s %f format, ECMAScript's
parseFloat, and similar parsers while being easier to
parse than some other floating point syntaxes that are also
compatible with those parsers.
The strings +0, 0e+0, and
+1e+3 are all invalid numbers (the minus sign cannot
be replaced by a plus sign for non-negative numbers, it must
simply be omitted). Similarly, .42e2 is invalid
(there must be at least one digit before the decimal point). UAs
must not submit numbers in invalid formats (whatever the user
might enter).
The submission format is not intended to be the format seen and used by users. UAs may use whatever format and UI is appropriate for user interaction; the description above is simply the submission format.
This input type is not appropriate for things like
telephone numbers or credit card numbers. Despite their names,
those aren't really numbers — the telephone number "65000"
is not equivalent to "65e3", but "65000", "65e3", "6.5e4",
"65000.00", etc, are all possible ways that a browser would submit
that number. For "numbers" that are really specially formatted
strings, like telephone numbers, social security numbers, credit
card numbers, etc, authors should use the "text"
input type, possibly with an appropriate pattern.
rangeSame as number, but indicates that the exact value
is not important, letting UAs provide a simpler interface than
they do for number. For instance, visual UAs may use
a slider control. The step, min, and
max attributes still apply. For this type,
step defaults to 1, min defaults to 0,
max defaults to 100, and value defaults
to the min value.
Volume controls and brightness controls would be good examples of "range" data controls.
emailaddr-spec token defined in RFC 2822 section 3.4.1 [RFC2822], but excluding the
CFWS subtoken everywhere, and excluding the
FWS subtoken everywhere except in the
quoted-string subtoken. UAs could, for example, offer
e-mail addresses from the user's address book. (See below for notes on IDN.)urlIRI token, defined in RFC 3987 section 2.2). UAs could,
for example, offer the user URIs from his bookmarks. (See below for notes on IDN.) The value is called
url (as opposed to iri or
uri) for consistency with CSS syntax and because it
is generally felt authors are more familiar with the term "URL"
than the other, more technically correct terms.
Relative URIs and IRIs do not match the
IRI token mentioned above. Only absolute addresses
(potentially with fragment identifiers) are valid values for this
input type. Of course, this does not prevent a user agent from
allowing users to enter relative or incomplete values, but such
values would have to be expanded to complete addresses before the
control's isTypeMismatch flag is cleared.
Any string that matches the IRI token must be accepted as a valid value by user agents. For example, user agents are not required to check that given values are in full logical order.
Four other new types, add,
remove, move-up and
move-down, have been introduced. They are defined as
part of the repeating form controls model.
The email and url controls may
contain IDN domains. [RFC3490] These
should be sent in their original (full-Unicode) characters, not
IDNA-encoded. (Authors can use the pattern
pattern="[\x00-\x7F]+" to indicate that
only ASCII-based domain names are to be allowed.) Time-related
controls must ignore leap seconds. Date-related controls must submit
dates according to the proleptic Gregorian calendar, and must
support dates according to this calendar starting at
0001-01-01. (This does not preclude user agents using more
historically appropriate calendars for past dates, e.g. switching to
the Julian calendar before the mid-18th century, nor does it
preclude them from using calendars more appropriate to the user's
locale, e.g. using the Chinese calendar.)
A control is said to have no value selected if its value is the empty string. File controls are said to have no value selected if no files have been selected.
By default, all of these new types (except range),
just like the types from HTML4, must have no value
selected unless a default value in a valid format is provided
using the value attribute. For all controls, if a value
is specified but it is not in a format that is valid for the type
(where the valid types are the same as the valid submission types
described above) then the defaultValue DOM attribute has
the specified value, and the control is left with the value it would
have had if the value attribute had not been specified
(namely, no value selected, except for
range controls, which have the min value
selected).
User agents may allow users to set a control to its "no value selected" state, but are not required to do so.
Controls with no value selected do not need to match the format appropriate for their type. (Although if they are required controls, they will stop submission for that reason instead.)
If a control has its type attribute changed to
another type, then the user agent must reinterpret the current value
(given by the value DOM attribute) and the default
value (given by the value content attribute and the
defaultValue DOM attribute) in light of the new type.
Values that no longer match the format allowed for the control must
be handled as described in the error handling section.
The following form uses some of the types described above:
<form action="..." method="post" onsubmit="verify(event)">
<p>
<label>
Quantity:
<input name="count" type="number" min="0" max="99" value="1" />
</label>
</p>
<p>
<label for="time1"> Preferred delivery time: </label>
<input id="time1" name="time1" type="time" min="08:00" max="17:00" value="08:00" /> —
<input id="time2" name="time2" type="time" min="08:00" max="17:00" value="17:00" />
</p>
<script type="text/javascript">
function verify(event) {
// check that time1 is smaller than time2, otherwise, swap them
if (event.target.time1.value >= event.target.time2.value) { // ISO 8601 times are string-comparison safe.
var time2Value = event.target.time2.value;
event.target.time2.value = event.target.time1.value;
event.target.time1.value = time2Value;
}
}
</script>
</form>
If in this example the "time1" control was changed to be of type
date, the current value (as picked by the user or as
initialised by the value attribute), the default value
(given by the value attribute in the markup and the
defaultValue attribute in the DOM) and the various
constraints (min and max here) would all
be found to be invalid and the control would therefore become a
date control with no minimum or maximum, and with no value
selected.
Servers should still perform type-checking on submitted data, as malicious users or rogue user agents might submit data intended to bypass this client-side type-checking. Validation done via script may also be easily bypassed if the user has disabled scripting. Additionally, legacy user agents do not support the validation features described in this specification and will therefore submit data that has not been checked.
The size attribute of the
input element is deprecated in favor of using CSS to
specify the layout of the form.
To limit the range of values allowed by some of the above types, two new attributes are introduced, which apply to the date-related, time-related, numeric, and file upload types:
minrangeUnderflow). If
absent, or if the minimum value is not in exactly the expected
format, there is no minimum restriction, except for the
range and file types, where the default
is zero.maxrangeOverflow). If
absent, or if the maximum value is not in exactly the expected
format, there is no maximum restriction (beyond those intrinsic to
the type), except for the range type, where the
default is 100, and the file type, where the default
is 1.For date, time and numeric controls, the values indicate the allowed range. For file upload controls, the values indicate the allowed number of files.
The typeMismatch flag is used for controls whose
values do not match their types, and the rangeUnderflow
and rangeOverflow flags are used for controls whose
values are outside the allowed range.
A control with a max less than its min
can never fulfill both conditions when it has a value (since that
value will always either underflow or overflow the allowed range)
and thus must block its forms from being submitted. This does not
make the document non-conformant.
The exact values allowed by min and max
depend on the type attribute. For numeric types
(number and range) the value must exactly
match the number type described above. For
file types it must be a sequence of digits 0-9, treated
as a base ten integer. For date and time types it must match the
relevant format mentioned for that type, all fields having the right
number of digits, with the right separating punctuation.
If a control has its type attribute changed to
another type, then the user agent must reinterpret the
min and max attributes. If an attribute
has an invalid value according to the new type, then the appropriate
default must be used (and not, e.g., the default appropriate for the
previous type). Control values that no longer match the range
allowed for the control must be handled as described in the error handling section.
For example, 50.00 does not match the allowed value
of time, so the following control has no artificial
restrictions on its values:
<input type="time" min="50.00">
Similarly, the value 2000 is not a valid value for
datetime, date, or any of the other date
or time types.
The following cases would work, though;
<input type="time" min="22:00"> <input type="time" min="22:00:50.0001">
The step attribute controls the precision
allowed for the date-related, time-related, and numeric types.
For the control to be valid, the control's value must be an
integral number of steps from the min value, or, if
there is no min attribute, the max value,
or if there is neither attribute, from the zero point.
The zero point for datetime controls is
1970-01-01T00:00:00.0Z, for datetime-local is
1970-01-01T00:00:00.0, for date controls is 1970-01-01,
for month controls is 1970-01, for week
controls is 1970-W01 (the week starting 1969-12-29 and containing
1970-01-01), and for time controls is 00:00.
For time controls, the value of the step attribute
is in seconds, although it may be a fractional number as well to
allow fractional times. The format of the step
attribute is the number format described
above, except that the value must be greater than zero. The default
value of the step attribute for datetime,
datetime-local and time controls is 60
(one minute).
For the following control, the allowed values are any day of any year, with the times restricted to even minutes:
<input type="datetime" step="120" name="start">
For the following control, the allowed values are fifteen seconds and two tenths of a second past the minute, any minute of the day, i.e. 00:00:15.2, 00:01:15.2, 00:02:15.2 ... 23:59:15.2:
<input type="time" min="00:00:15.20" name="t">
This is because the default step for
time controls is 60 (one minute).
How the step attribute affects the UI is not
defined by this specification. For example, for a
datetime control with step="1", the UI
could look like this:
For date controls, the value of the step attribute
is in days, weeks, or months, for the date,
week, and month types respectively. The
format is a non-negative integer; one or more digits 0-9 interpreted
as base ten. If the step is zero, it is interpreted as the default.
The default for the step attribute for these control
types is 1.
The following control would only allow selection of any Sunday in any year from 1900 onward:
<input type="date" min="1900-01-07" step="7" name="sunday">
For numeric controls (number and
range), the format of the step attribute
is the number format described above, except
that the value must be greater than zero. For numeric controls, the
default value of the step attribute is 1.
If the step is 25e-2 (or
0.25, which is equivalent), and if max
is -1.1, then the allowed values would be -1.1,
-1.35, -1.60, -1.85, -2.1, ...
If you wanted a range control that allowed only even numbers, you could set:
<input type="range" step="2" name="evenN">
The following control would have a step of 1, the default,
because the given value for the step attribute does
not match the allowed values for numbers as defined above (it would
need a leading zero before the decimal point):
<input type="range" step=".1" name="n">
In addition, for any of the types, the literal value any may be used as the value of
the step attribute. This keyword indicates that any
value may be used (within the bounds of other restrictions placed on
the control).
The following control would allow any floating point number:
<input type="number" step="any" name="n">
The stepMismatch flag is used for controls whose
values are not one of the values allowed by the step
attribute. However, UAs may silently round the number to the nearest
value allowed by the step attribute instead of
reporting a stepMismatch validation error. (Such
rounding may make the value out of range, causing, for instance, a
rangeOverflow validation error.)
If the author specified step is too small for the UA to handle
(for example, 1e-9999999 would probably underflow most
implementations) then the UA should treat the value as any. If the given step value is
not one of the allowed values, then the default is used.
User agents are recommended to never convert user- and author-supplied values to their binary numeric representation, keeping the values in string form at all times and performing comparisons in that form. This ensures that UAs are able to handle arbitrarily large numbers without risking data loss due to rounding in the decimal-to-binary conversion.
If a UA needs to round a number to its nearest binary equivalent, as, for example, when converting a user-supplied decimal number and an author-supplied minimum in order to compare them to establish validity (ignoring the suggestion above to do these comparisons in string form), algorithms equivalent to those specified in ECMA262 sections 9.3.1 ("ToNumber Applied to the String Type") and 8.5 ("The Number type") should be used (possibly after suitably altering the algorithms to handle numbers of the range that the UA can support). [ECMA262]
If a control has its type attribute changed to
another type, then the user agent must reinterpret the
step attribute. If it has an invalid value according to
the new type, then the new appropriate default must be used. Control
values that no longer match the precision allowed for the control
must be handled as described in the error
handling section.
In addition to the new attributes given in this section, some existing attributes from [HTML4] are clarified and extended below. These, and other attributes from HTML4, continue having the same semantics as described in HTML4 unless specified otherwise.
accesskeyUAs may now support the
accesskey attribute on select elements
(and must at a minimum support the relevant DOM attribute).
The accesskey attribute on label
elements must act the same way as it would if specified on the
associated element directly.
disabledThe disabled attribute applies to all form
controls except the output element, and also to the
fieldset, option, and
optgroup elements. In HTML4 the
disabled attribute did not apply to the
fieldset element.
When applied to a fieldset element it overrides
the disabled attributes of any descendent form
controls (regardless of whether they are associated with the same
form). In other words, a form control shall be disabled if it has
its disabled attribute set, or if any of its ancestor
fieldset elements have their
disabled attribute set.
maxlengthThis attribute applies to text,
password, url, and email input types, and
textarea elements. In particular, it does not apply
to the date-related, time-related, and numeric control types. In HTML4, this attribute only applied to the
text and password types.
For text input controls it specifies the maximum length of the input, in terms of numbers of code points. [CHARMOD].
A newline in a
textarea's value must count as two code points for
maxlength processing (because newlines in
textareas are
submitted as U+000D U+000A). This includes the implied
newlines that are added for submission when the wrap
attribute has the value hard.
Authors are discouraged from using maxlength on
url and email controls unless the server side processor
actually has a limit on the size of data fields it can usefully
process. Valid URIs and e-mail addresses in particular can often
be surprisingly long.
The tooLong flag is used when this attribute is
specified on a text, password,
url, email or
textarea control and the control has more than the
specified number of code points and the value doesn't match
the control's default value.
Servers should still expect to receive, and must be able to
cope with, content larger than allowed by the
maxlength attribute, in order to deal with malicious
or non-conforming clients.
This attribute must not affect the initial value (the DOM defaultValue attribute). It
must only affect what the user may enter and whether a validity
error is flagged during validation.
If the maxlength attribute has a value that is
less than the length required for a valid value of the given type,
for example:
<input type="email" maxlength="1" name="test"/>
...then the control can only be valid if it is has no
value selected (unless, of course, it is a
required control, in which case it can never be
valid).
nameEcom_")
are reserved by [RFC3106]. Authors must
not use names starting with the string "Ecom_" in ways
that conflict with RFC3106.readonlytext,
password, email, url, date-related, time-related,
and number input types, as well as the
textarea element. Specifically, it does not apply to
radio buttons, checkboxes, file upload controls, range
controls, select elements, or any of the button types;
the interface concept of "readonly" values does not apply to
button-like user interfaces.Other attributes not listed in this specification retain the same semantics as in [HTML4].
pattern attributeFor the text, password,
email, and url
types of the input element,
and for the textarea element, the
pattern attribute specifies a pattern that
the control value must match.
When specified, the pattern attribute contains a
regular expression that the control's value must match before the form
may be submitted (patternMismatch).
<label> Credit Card Number:
<input type="text" pattern="[0-9]{13,16}" name="cc" />
</label>
The regular expression language used for this attribute is the
same as that defined in [ECMA262], except
that the pattern attribute must match the entire value,
not just any subset (somewhat as if it implied a ^(?:
at the start of the pattern and a )$ at the end). The
pattern must be compiled with the global,
ignoreCase, and multiline flags disabled
(see ECMA262, sections 15.10.7.2 through 15.10.7.4). If the
attribute is omitted then the control has no pattern
restriction.
The requirement that the pattern match the entire string is present because it is expected that the overwhelming majority of use cases will be to require that user input exactly match the given pattern. Authors who forget that these characters are implied will immediately realise their mistake during testing. Had the characters not been implied, requiring most authors to insert them themselves, it is likely that authors who forgot them would not catch their mistake as easily.
Authors who wish to allow for any input so long as a particular
string occurs somewhere in the input should put
.* at the start and end of their pattern. If the input
is expected to allow newlines, then [\s\S]* or some
equivalent should be used instead, since the dot character in
JavaScript regular expressions does not include newlines.
The / character is not special in the
pattern attribute. The two attributes
pattern="/etc/.+" and pattern="\/etc\/.+"
are therefore equivalent.
In the case of the email
and url types, the pattern attribute
specifies a pattern that must be matched in addition to the
value matching the generic pattern relevant for the control. If the
pattern given by the attribute specifies a pattern that is
incompatible with the grammar of the control type, as in the example
below, then the control could never be satisfied. (A document
containing such a situation is not technically non-conformant, but
it is of dubious semantic use.)
<form> <p> This form could never be submitted, as the following required control can never be satisfied: <input type="url" pattern="[^:]+" required="required" name="test"/> </p> </form>
When the value doesn't match the control's type, the
typeMismatch flag must be set; when the value doesn't
match the pattern, the patternMismatch flag must be
set. If the value matches neither the control's type nor the control's
pattern, both flags must be set.
When the pattern is not a valid regular expression, it is ignored for the purposes of validation, as if it wasn't specified.
Controls with no value selected do not need to match their pattern. (Although if they are required controls, they will stop submission for that reason anyway.)
If the pattern attribute is present but empty, it
doesn't match any value, and thus the patternMismatch
flag shall be set whenever the control's value isn't empty.
Authors should include a description of the
pattern in the title attribute. User agents may use the
contents of this attribute when informing the user that the pattern
is not matched, or at any other suitable time, such as in a tooltip
or read out by assistive technology when the control gains
focus.
For example, the following snippet:
<label> Part number:
<input pattern="[0-9][A-Z]{3}" name="part"
title="A part number is a digit followed by three uppercase letters."/>
</label>
...could cause the UA to display an alert such as:
A part number is a digit followed by three uppercase letters.
You cannot complete this form until the field is correct.
When a control has a pattern attribute, the
title attribute, if used, must describe the pattern.
Additional information could also be included, so long as it assists
the user in filling in the control. Otherwise, assistive technology
would be impaired.
For instance, if the title attribute contained the caption of the control, assistive technology could end up saying something like The text you have entered does not match the required pattern. Birthday, which is not useful.
UAs may still show the title in non-error situations
(for example, as a tooltip when hovering over the control), so
authors should be careful not to word titles as if an
error has necessarily occurred.
required attributeForm controls can have the required
attribute specified, to indicate that the user must enter a value
into the form control before submitting the form.
The required attribute applies to all form controls
except controls with the type hidden, image inputs,
buttons (submit, move-up, etc), and
select and output elements. For
disabled or readonly controls, the attribute has no effect.
The valueMissing flag is
used for form controls marked as required that do not have
values.
For checkboxes, the required attribute shall only be
satisfied when one or more of the checkboxes with that name in that
form are checked.
For radio buttons, the required attribute shall only
be satisfied when exactly one of the radio buttons in that radio
group is checked.
For file upload controls, the
required attribute shall only be satisfied if at least
one valid file is selected, regardless of the min and
max attributes.
Here is a form fragment showing one required control and one optional control. A user agent would not allow the user to submit the form until the "name" control was filled in.
<ul> <li><label> Name: <input type="text" name="name" required="required" /></label></li> <li><label> Comment: <input type="text" name="comment" /></label></li> </ul>
For other controls, any non-empty value shall satisfy the required
condition, including a simple whitespace character.
form attributeAll form controls as well as the fieldset element
may have the form attribute specified. The
form attribute gives a space-separated list of IDs of
form elements that the form control is to be associated
with, and overrides the relationship between the form control and
any ancestor form element.
Any of the IDs in the space-separated list that do not identify
an element in the document, or that identify an element that is not
an HTML form element, must be ignored. Setting an
element's form attribute to the empty string (or to a
string consisting only of IDs that do not correctly identify
form elements) just disassociates the form control from
its form, leaving it unassociated with any form.
When set on a fieldset element, this attribute also
changes the association of any descendent form controls, unless they
have form attributes of their own or are contained
inside forms that are themselves descendants of the
fieldset element.
In other words, user agents must
associated form controls and fieldsets with the forms
given in their form attribute,
or, if they don't have one, with the nearest ancestor
form element or the forms given in the form attribute of the nearest
fieldset element with a form attribute, whichever is the
nearest. If none of those apply, the element is not associated with
any form.
When forms are submitted, are reset, or have their form controls enumerated through the DOM, only those controls associated with the form are taken into account. A control can be associated with more than one form at a time. Submit buttons and image controls must only submit the first form they are associated with. Reset buttons must reset all the forms they are associated with.
A form attribute that specifies an ID that occurs
multiple times in a document must select the same form as would be
selected by the getElementById() method for that ID ([DOM3CORE]). (That is, the exact behaviour
is undefined, but must be the same as if the
getElementById() method was used.)
If a form is specified multiple times in the form
attribute, all occurrences but the first must be ignored. (An
element can only be associated with a form once.) A form must not be
specified more than once in a form attribute.
In this example, each row contains one form. Without the "form" attribute, it would not be possible to have more than one form per table if any of them spanned cells.
<table>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<form id="edit1" action="/edit" method="post">
<input type="hidden" name="id" value="1"/>
<input type="text" name="name" value="First Row"/>
</form>
</td>
<td>
<input form="edit1" type="text" name="value"/>
</td>
<td>
<input form="edit1" type="submit" name="Edit"/>
</td>
</tr>
<tr>
<td>
<form id="edit2" action="/edit" method="post">
<input type="hidden" name="id" value="2"/>
<input type="text" name="name" value="Second Row"/>
</form>
</td>
<td>
<input form="edit2" type="text" name="value"/>
</td>
<td>
<input form="edit2" type="submit" name="Edit"/>
</td>
</tr>
</tbody>
</table>
In the following example, the text control is associated with two forms.
<form action="test.cgi"> <input type="text" name="q" form="fg fy"> <input type="submit" name="t" value="Test"> </form> <form id="fg" action="google.cgi"><input type="submit" value="Google"></form> <form id="fy" action="yahoo.cgi"><input type="submit" value="Yahoo"></form>
There are three submit buttons. The first, "Test", submits just
the "Test" button, and submits it to test.cgi. The
text control is not submitted with that form in Web Forms 2 compliant
UAs. (It is submitted in legacy UAs, which can be used for
implementing fallback behaviour.)
The second button submits the text control to
google.cgi, the third button submits the same text
control to yahoo.cgi.
autocomplete attributeThe autocomplete attribute applies to the
text, password, date-related, time-related,
numeric, email, and url controls. The
attribute takes two values, on and off.
The default, when the attribute is not specified, is
on.
The off value means that the control's input data is
either particularily sensitive (for example the activation code for
a nuclear weapon) or that it is a value that will never be reused
(for example a one-time-key for a bank login) and indicates that the
user should therefore explicitly enter the data each time, instead
of being able to rely on the UA to prefill the value for him. The
on value indicates that the value is not particularily
sensitive and the user should expect to be able to rely on his UA to
remember values he has entered for that control.
When a control has its autocomplete attribute set to
a value other than off, or when the attribute is
omitted, the UA may store the value entered by the user so that if
the user returns to the page, the UA can prefill the form. When a
control has its autocomplete attribute set to
off, the UA should not remember that control's value.
This specification does not define the autocompletion mechanism. UAs may implement any system within the conformance criteria of this specification, taking into account security and privacy concerns.
Banks frequently do not want UAs to prefill login information:
<p>Account: <input type="text" name="ac" autocomplete="off" /></p> <p>PIN: <input type="text" name="pin" autocomplete="off" /></p>
A UA may allow the user to disable support for this attribute. Support for the attribute should be enabled by default, and the ability to disable support should not be trivially accessible, as there are significant security implications for the user if support for this attribute is disabled.
In practice, this attribute is required by many banking institutions, who insist that UAs with auto-complete features implement it before supporting them on their Web sites. For this reason, it is implemented by most major Web browsers already, and has been for many years.
autofocus attributeAny form control (except hidden and
output controls) can have an autofocus
attribute specified.
When a form control is inserted into a document, the UA must
check to see if it has this attribute set. If it does, and the
control is not disabled, and it is of a type normally
focusable in the user's operating environment, then the UA should
focus the control, as if the control's focus() method
was invoked. UAs with a viewport should also scroll the document
enough to make the control visible, even if it is not of a type
normally focusable.
Authors must not set the autofocus attribute
on multiple enabled elements in a document. If multiple elements
with the autofocus attribute set are inserted
into a document, each one will be processed as described above, as
they are inserted. This means that during document load, for
example, the last focusable form control in document order with the
attribute set will end up with the focus.
UAs may ignore this attribute if the user has indicated (for example, by starting to type in a form control) that he does not wish focus to be changed.
The value of the attribute, if set, should be autofocus. The autofocus DOM attribute must return true when
the content attribute is present (regardless of its value, even if it is the
empty string), and false when it is absent. Setting the DOM
attribute to true must set the content attribute to the value autofocus. Setting the DOM attribute to false must
remove the content attribute.
In the following snippet, the text control would be focused when the document was loaded.
<input maxlength="256" name="q" value="" autofocus="autofocus"> <input type="submit" value="Search">
In HTML, the minimised form may be used (just
autofocus instead of
autofocus="autofocus").
The following would cause the autofocus
attribute to be set to autofocus:
<input autofocus>
Focusing the control does not imply that the UA must focus the browser window if it has lost focus.
inputmode attributeThe inputmode attribute applies to the
input element when it has a type attribute
of text, password, email, or url, and
to the textarea element.
This attribute is defined to be exactly equivalent to the inputmode attribute defined in the XForms
1.0 specification (sections E1 through E3.2) [XForms].
datalist element and the list
attributeFor the text, email,
url, date-related,
time-related, and numeric types of the input element, a
new attribute list is introduced to point to
a list of values that the UA should offer to the user in addition to
allowing the user to pick an arbitrary value.
To complement the new list attribute, a
datalist element is introduced. This element
has two roles: it provides a list of data values, in the form of a
list of option elements, and it may be used to provide
fallback content for user agents that do not support this
specification.
If the UA supports this element, it should not be displayed. In CSS-aware user agents, this should be achieved by including the following rules, or their equivalent, in the UA's user agent style sheet:
@namespace xh url(http://www.w3.org/1999/xhtml);
xh|datalist { display: none; }
When a control has a list attribute, it specifies an
element from which to derive the list of author-specified
autocompletion values for the control.
The element specified is the one that would be returned when
calling getElementById() with the value of the
list attribute as the argument, if the returned value
is an element node with either the local name datalist
or the local name select, and (for XHTML) with the
XHTML namespace. If the attribute is present but either specifies an
ID that is not in the document, or specifies an element that is not
an (X)HTML datalist or select, then it
must be ignored.
The list of autocompletion values shall be given by the list of
elements that would be found by calling
getElementsByTagName() with the local name
option on the element specified, if any (or, in XHTML
documents, the list of elements that would be found by calling
getElementsByTagNameNS() with the same local
name and the XHTML namespace).
For each element in this list, if the element is not marked as
disabled, the autocompletion value is either the value
of its value content attribute, or, if that attribute
is absent, the value of its text DOM attribute. The UA
may use the label attribute to annotate the value in
its interface. If the element is marked as disabled, if
the autocompletion value is the empty string, or if the
autocompletion value is not a valid value for the control's type
(for example, 20 is not a valid value for a
datetime control) then it must be ignored.
The author-specified list of predefined values may be augmented by the UA's own autocompletion logic. For example, the UA may remember previous values that the user has entered.
UAs are encouraged to filter the autocomplete list and only show
values that would pass validation (e.g. if the form control has a
pattern attribute, only showing autocomplete values
that match the pattern).
Authors must only use empty option elements or
elements that would be allowed in the datalist
element's parent as children of datalist elements.
datalist elements may be used wherever block-level
elements are allowed and wherever select elements are
allowed.
Controls inside datalist elements must never be successful. (They must still, however, be associated with their
form.)
The datalist element may be prefilled from an
external file with the data
attribute.
The selected content attribute and the
form, selected,
defaultSelected, and index DOM attributes
on option elements must have no effect on the
input and datalist elements when
option elements are used in this context.
If a document contained the following markup:
<input type="url" name="location" list="urls"> <datalist id="urls"> <option label="MIME: Format of Internet Message Bodies" value="http://www.ietf.org/rfc/rfc2045"> <option label="HTML 4.01 Specification" value="http://www.w3.org/TR/html4/"> <option label="Form Controls" value="http://www.w3.org/TR/xforms/slice8.html#ui-commonelems-hint"> <option label="Scalable Vector Graphics (SVG) 1.1 Specification" value="http://www.w3.org/TR/SVG/"> <option label="Feature Sets - SVG 1.1 - 20030114" value="http://www.w3.org/TR/SVG/feature.html"> <option label="The Single UNIX Specification, Version 3" value="http://www.unix-systems.org/version3/"> </datalist>
...and the user had typed "www.w3", and the user
agent had also found that the user had visited
http://www.w3.org/Consortium/#membership and
http://www.w3.org/TR/XForms/ in the recent past, then
the rendering might look like this:
The first four URIs in this sample consist of the four URIs in the author-specified list that match the text the user has entered, sorted lexically. Note how the UA is using the knowledge that the values are URIs to allow the user to omit the scheme part and perform intelligent matching on the domain name.
The last two URIs (and probably many more, given the scrollbar's indications of more values being available) are the matches from the user agent's session history data. This data is not made available to the page DOM. In this particular case, the UA has no titles to provide for those values.
This example demonstrates how to design a form that uses the autocompletion list feature while still degrading usefully in legacy user agents.
If the autocompletion list is merely an aid, and is not
important to the content, then simply using a datalist
element with children option elements is enough. To
prevent the values from being rendered in legacy user agents, they
should be placed inside the value attribute instead
of inline.
<p> <label> Enter a breed: <input type="text" name="breed" list="breeds"> <datalist id="breeds"> <option value="Abyssinian"> <option value="Alpaca"> <!-- ... --> </datalist> </label> </p>
However, if the values need to be shown in legacy UAs, then
fallback content can be placed inside the datalist
element, as follows:
<p>
<label>
Enter a breed:
<input type="text" name="breed" list="breeds">
</label>
<datalist id="breeds">
<label>
or select one from the list:
<select name="breed">
<option value=""> (none selected)
<option>Abyssinian
<option>Alpaca
<!-- ... -->
</select>
</label>
</datalist>
</p>
The fallback content will only be shown in UAs that don't
support datalist. The options, on the other hand, will
be detected by all UAs, even though they are not direct children of
the datalist element.
Note that if an option element used in a
datalist is selected, it will be selected
by default by legacy UAs (because it affects the
select), but it will not have any effect on the
input element in UAs that support
datalist.
Here is another example, this time with a range control. This could be useful if there are values along the full range of the control that are especially important, such as preconfigured light levels or typical speed limits in a range control used as a speed control. The following markup fragment:
<input type="range" min="-100" max="100" value="0" step="10" name="power" list="powers"> <datalist id="powers"> <option value="0"> <option value="-30"> <option value="30"> <option value="+50"> </datalist>
...with the following style sheet applied:
input { height: 75px; width: 49px; background: #D5CCBB; color: black; }
...might render as:
Note how the UA determined the orientation of the control from
the ratio of the style-sheet-specified height and width properties.
The colours were similiarly derived from the style sheet. The tick
marks, however, were derived from the markup. In particular, the
step attribute has not affected the placement of tick
marks, the UA deciding to only use the author-specified completion
values and then adding longer tick marks at the extremes.
Note also how the invalid value +50 was completely
ignored.
This specification does not mandate a particular interface. The UA could have used a rotary control, a combo box, a voice-driven text box, or any other widget or interface while still being compliant with this specification.
output elementThe output element acts very much like a
span element, except that it is considered to be a form
control for the purposes of the DOM. Its namespace (in XML) is the
same as for the other form control elements,
http://www.w3.org/1999/xhtml.
The output element may have any of the common
attributes, the form and name
attributes, the for attribute (defined below), and the
onchange, onforminput and
onformchange attributes.
Its current value is given by its contents, which may
be any inline content (like the span element).
The current value can be set and retrieved dynamically using the
mutable value DOM
attribute of type DOMString. This attribute is defined
to be identical to the DOM3 Core textContent attribute.
[DOM3CORE]
The initial value of the output control is
stored in a mutable defaultValue DOM
attribute of type DOMString. See [HTML4] section 17.2 for the
definiton of the term "initial value". (In brief, it is the
value used when the form is reset.)
The defaultValue DOM attribute of
an output control must initially be set to the empty
string. If an output element is added to the document
at parse time, its defaultValue DOM attribute
must be set to the value of its textContent attribute
after all its children nodes were parsed. (If the value of defaultValue is queried
before the entire element's contents have been parsed, or if the
element was created dynamically (as opposed to being inserted into
the DOM by the UA's parser), then defaultValue must return the
empty string.)
The output element is never successful for form submission. Resetting a
form does reset its output elements (using the
defaultValue DOM
attribute — note that if the element originally contained
elements as children, they will be removed when the form is
reset).
Unless the value attribute is directly
manipulated or the form is reset, elements that are children of the
output element when the document was parsed are not
flattened away.
The following example shows two input controls. Changing either
control updates an output element containing the product
of both controls.
<form> <p> <input name="a" type="number" step="any" value="0"> * <input name="b" type="number" step="any" value="0"> = <output name="result" onforminput="value = a.value * b.value">0</output> </p> </form>
This would work something like the following:
The forminput event is defined in the
section on new events.
Authors may provide a list of space-separated IDs in a
for attribute that represents the list of
elements that control the value of the output element.
User agents may use this list to suggest to users the relevant parts
of the document with which the user should interact to change the
value.
In the following example, the output element is
used to indicate the relationship between the given value and the
later prose. The number cannot be changed directly by the user, but
the specified element describes the process through which the user
could change the value.
... <p>Your fax number is <output for="fax"><em>+1</em> 650 555 1234</output>.</p> ... <p id="fax">To change your fax number, you must send us a fax from your new number with a signed request that your fax number details be changed. We will then call you to confirm the change.</p>
Note the em element in the markup emphasising a
part of the number. Markup like this is allowed inside
output elements.
Whenever the value attribute changes (whether
directly or because the DOM under the element was mutated), a
change event must be fired on the output
element. The onchange attribute can therefore be used
with this element, in the same way as for other form controls.
Usage: The output element should be
used when the user will never directly manipulate the value, and
when the value can be derived from other values (e.g. a total), or,
when the value is a repetition of a value editable elsewhere (e.g. a
fax number that the user can edit on the site's preferences page).
Contrast this with the readonly attribute, which
should be used on controls that the user should not change, but
which need to be submitted to the server (such as an ID number when
editing a record), and the disabled attribute, which
should be used on controls that the user cannot change and that are
not to be submitted (controls that could be edited in some cases,
for instance if the user had more privileges, but that are
irrelevant at the current point in time).
textarea elementThe rows and cols attributes of the
textarea element are no longer required attributes.
When unspecified, CSS-compliant browsers should lay the element out
as specified by CSS, and non-CSS UAs may use UA-specific defaults,
such as, for visual UAs, using the available width on the page and a
height suitable for the device.
The textarea element may have a
wrap attribute specified. This attribute
controls the wrapping behaviour of submitted text.
softhardcols attribute. (These additional line breaks can't be
seen in the DOM.)Authors should always specify a cols attribute when
the wrap attribute is set to hard. When
wrap="hard" is specified without a cols
attribute, user agents should use the display width when wrapping
the text for submission. This will typically mean that different
users submit text at different wrapping widths, defeating much of
the purpose of client-side wrapping.
CSS UAs should render textarea elements as
specified by the 'white-space' property, although UAs
may have rules in their UA style sheet that set the default
'white-space' property values based on the wrap
attribute for textarea elements.
A newline in a textarea
submission must be delimited by the two code points U+000D U+000A
(CRLF). This includes the implied newlines that are added for
submission when the wrap attribute has the value
hard. This also affects how newlines are handled for the
maxlength attribute, which applies to
textarea controls.
Authors may include an accept attribute on
textarea elements to indicate the type of content
expected. User agents may use this attribute to provide more
appropriate editors, syntax highlighting, spelling checkers, etc.
The value of the attribute must be a single text-based MIME type
(for example, text/plain, message/news,
image/svg+xml), optionally with parameters. The
default, if the attribute is omitted or if the value is not
recognised by the UA, shall be text/plain. [RFC2046]
The accept
attribute on textarea elements is separate from the
accept attribute on file upload controls defined in the
next section.
The min and max attributes apply to
file upload controls (input elements of type
file) and specify (using non-negative
integers) how many files must be attached for the control to be
valid. They default to 0 and 1 respectively (and so limit the
default number of files to 1 optional file, as per most existing
implementations in early 2004). The defaults are used when the
attributes are omitted or have non-integer or negative integer
values. The rangeUnderflow and
rangeOverflow flags are used to indicate when controls do
not have the specified number of files selected.
There is currently no way to specify that an
unlimited number of files may be uploaded. Authors are encouraged to
consider what the practical limit actually is for their server-side
script. For example, if the server uses an unsigned 16 bit integer
to track file uploads, a suitable max value would be
65536.
The required attribute applies to file upload
controls; it is only satisfied when at least one valid file (that
is, one that will actually be uploaded if the form is submitted) is
selected, irrespective of the min and max
attributes.
Non-existent files and files the UA won't be able to upload (for
whatever reason), when specified in file upload controls, do not
count towards the number of files selected for the purposes of
min and max, and are not submitted. It is
recommended that user agents report problems of this nature to the
user. There is no way for scripts to detect this situation because
that would open the way for some privacy or security leaks.
The accept attribute may be used to
specify a comma-separated list of content types that a server
processing the form will handle correctly. [RFC2046] This attribute was specified in
HTML4. [HTML4] In this specification, this
attribute is extended as follows:
*, or where the whole
string is */*. For example: <input type="file" name="avatar"
accept="image/*"/> In this way, the
accept attribute may be used to specify that the
server is expecting (say) images or sound clips, without
specifying the exact list of types.
accept attribute must not have
any MIME type parameters. The syntax of the attribute, therefore,
is (in pseudo-BNF):
accept := space* range [ space* "," space* range]* space* range := "*/*" | type "/*" | type "/" subtype space := U+0020 | U+000A type := defined in RFC2045 [RFC2045] subtype := defined in RFC2045 [RFC2045]
accept attribute's MIME
type list to determine which application to use.
One recent use for sound file upload has been the concept of audio blogging. This is similar to straight-forward Web logging, or diary writing, but instead of submitting textual entries, one submits sound bites.
The submission interface to such a system could be written as follows:
<form action="/weblog/submit" method="post" enctype="multipart/form-data"> <label> Attach your audio-blog sound file: <input type="file" name="blog" accept="audio/*"/> </label> <input type="submit" value="Blog!"/> </form>
A compliant UA could, upon encountering this form, provide a "Record" button instead of, or in addition to, the more usual "Browse" button. Selecting this button could then bring up a sound recording application.
This is expected to be most useful on small devices that do not have file systems and for which the only way of handling file upload is to generate the content on the fly.
typeMismatch flag is used to indicate that at
least one of the selected files does not have a MIME type
conforming to one of the MIME types or MIME ranges listed as
acceptable. UAs may allow the user to override the MIME type to be
one of the allowable types if the file is originally incorrectly
labeled.accept attribute is set on a
form element, it sets the default for any file upload
controls in that form. If a file upload control has a valid
accept attribute, its value is used and the relevant
form element's accept attribute is ignored for that
control. If a file upload control has an accept
attribute but it is invalid, then the value */* is
assumed instead, and the form's accept attribute is
ignored.If the file upload process fails, UAs should report this failure to the user in a useful and accessible manner, as with any failed submission.
If a file selected for upload does not have an explicit file name (for example because the user agent allowed the user to create the submitted file on the fly) then the file name shall be the empty string for the purposes of submission.
form elementThe form element's
action attribute is no longer a required attribute.
Authors may omit it. When the attribute is absent, UAs must act as
if the action attribute was the empty string, which is
a relative URI reference, and would thus point to the current
document (or the specified base URI, if any).
In the following XML example, the form would submit to
http://search.example.com/, whatever the URI of the
current page.
<form xml:base="http://search.example.com/"> <p><input type="submit"/></p> </form>
To support incremental updates of forms, a new attribute is
introduced on the form element:
replace. This attribute takes two
values:
target attribute when the document uses frames or
windows) is replaced by the return value.These names, and their exact semantics, differ from
those of the equivalent attribute in XForms 1.0 (the
replace attribute on the submission element). The equivalent of
document in this specification is all in
XForms, and the equivalent of values is
instance. The equivalent of the XForms
none value is document with the server
returning an HTTP 204 No Content return code.
The exact semantics are described in detail in the section on submission, under step eight.
Normally, activating a submit button (an input or
button element with the type attribute set
to submit, or an input element with the
type attribute set to image) must submit
the first form the control is associated with, using the form's
submission details (action, method,
enctype, and replace attributes).
In some cases, authors would like to be able to submit a form to
different processors, using different submission methods, or not
replacing the form but just updating the details with new data. For
this reason, the following attributes may be used on submit buttons:
action, method, enctype,
replace, and target.
If a submit button is activated, then the submission must use the
values as given by the button that caused the activation. For
missing attributes, the values of the equivalent attributes on the
relevant form element, if any, are used instead.
If the submit button is not associated with any form, then no form is submitted.
There are several elements that are defined as expecting particular elements as children. Using the DOM, or in the markup, it is sometimes possible for authors to violate these expectations and place elements in unexpected places.
Similarly, attributes are defined to accept values that conform to certain syntaxes, but it is possible for authors to violate these constraints.
Authors must not do this. User agent implementors may curse authors who violate these rules, and may persecute them to the full extent allowed by applicable international law.
Upon encountering incorrect constructs, UAs must proceed as follows:
This document does not specify exact parsing semantics for ambiguous cases that are not covered by SGML. UA implementors should divine appropriate behaviour by reverse engineering existing products and attempting to emulate their behaviour. (This does not apply to XHTML, since the XML specification specifies mandatory formal error handling rules.)
form elements in head
elements in XHTMLTypically UAs are expected to hide all the contents of
head elements. No other special behaviour is required
to cope with this case; if the author overrides this hiding (e.g.
through CSS) then the form must behave like any other form. (This
does not apply to HTML, where a form in a
head would, per SGML parsing rules, imply a
body start tag.)
input elementsBy default, the form control must be rendered, and the contents of the element must not be. Using CSS3 Generated Content [CSS3CONTENT] or XBL [XBL2], however, it is possible for the author to override this behaviour.
output elements containing elements in the DOMThe defaultValue
DOM attribute must be initialized from
the DOM3 Core textContent attribute ([DOM3CORE]). Setting the element's value attribute must be
identical to setting the DOM3 Core textContent
attribute. While the element contains elements, they are rendered
according to the CSS rules.
textarea elements containing tags in HTMLThe tags should be parsed as character data, but entities and comments should be recognised and handled correctly. (This doesn't apply to XHTML, since it would contravene XML parsing rules.)
textarea elements containing elements in the DOMThe defaultValue
DOM attribute is identical to the textContent DOM
attribute both for reading and writing, and is used to set the
initial value. The rendering is based on the
value DOM attribute, not the contents of the element,
unless CSS is used to override this somehow.
select and optgroup elements
containing nodes other than option and
optgroup elementsOnly the option and optgroup elements
take part in the select semantics. Unless otherwise
forced to appear by a style sheet, other child nodes are never
visible.
option elements containing nodes other than
text nodesThe value of the control, if not specified explicitly, must be
initialized using the textContent DOM attribute's
value.
How such markup should be rendered is undefined. Two
possibilities are sensible: rendering the content normally, just as
it would have been outside the form control; and rendering the
initial value (the value stored in the DOM
defaultValue attribute) only, with the rest of the
content not displayed (unless forced to appear through some
CSS).
option and optgroup elements that
are not inside select elementsThe elements should be rendered much the same as
span elements.
accept attributes that are invalidThe given value is what must be used in the DOM and elsewhere,
but it must be interpreted as */* when doing
comparisons with actual MIME types, e.g. to filter a file list or
when validating the control prior to submission.
value attributes that are
invalid according to the type attributeThe attribute must be ignored. It will appear in the DOM for
the defaultValue
attribute, but will not be used as the value of the control. The
control will therefore initially have no value
selected.
value attributes that are
invalid according to the min, max,
step, maxlength, etc, attributesThe control must be set to that value. The form will not submit with that value, though. If the control cannot be set to that value (for example, a range control cannot represent values outside its range) then the value must be clamped to the nearest value that can be represented by the control. (This situation can also arise if these attributes are dynamically updated using the DOM.)
for) to elements
that are not form controlsThe attribute must be ignored. It will appear in the DOM
(including as the value of htmlFor) but the control DOM attribute must return null
and activating the label must not send focus to the associated
element.
for attributes and
containing more than one form controlThe control DOM attribute must
return, and activating the label, if supported, must transfer focus
to or activate, the first control in a depth-first search of the
label's children.
for attributes whose
value is the empty stringThis case must be treated as if the element had no for attribute.
As events bubble from the target node, user agents must make
the default action of the event be the action that would be
appropriate for the first label element that the event
bubbles through. In other respects, nested labels are oblivious to
each other. Note that in HTML, parsers typically treat a
<label> opening tag as implying a closing tag
for any already open label.
The attribute must be ignored. It will appear in the DOM, but
not affect the form semantics. For example, if a min
attribute on a datetime control is an integer instead
of a date and time string, then the range has no minimum. If the
type attribute is then changed to number,
then the attribute would take effect.
The user agent processing model is defined in terms of the DOM and is independent of whether content models are being violated or not. Behaviour is therefore fully defined even for invalid content.
Other invalid cases should be handled analogously.
Occasionally forms contain repeating sections. For example, an order form could have one row per item, with product, quantity, and subtotal controls. The repeating form controls model defines how such a form can be described without resorting to scripting.
The entire model can be emulated purely using JavaScript and the DOM. With such a library, this model could be used and down-level clients could be supported before user agents implemented it ubiquitously. Creating such a library is left as an exercise for the reader.
This subsection is not normative.
Occasionally, a form may need a section to be repeated an arbitrary number of times. For example, an order form could have one row per item. Traditionally, this has been implemented either by using complex client-side scripts or by sending a request to the server for every new row.
Using the mechanisms described in this section, the problem is reduced to describing a template in the markup, and then specifying where and when that template should be repeated.
To explain this, we will step through an example. Here is a sample form with three rows:
<!DOCTYPE html>
<html>
<head>
<title>Sample Order Form</title>
</head>
<body>
<form>
<table>
<thead>
<tr>
<th>Product</th>
<th>Quantity</th>
</tr>
</thead>
<tbody>
<tr>
<td><input type="text" name="row0.product" value=""></td>
<td><input type="text" name="row0.quantity" value="1"></td>
</tr>
<tr>
<td><input type="text" name="row1.product" value=""></td>
<td><input type="text" name="row1.quantity" value="1"></td>
</tr>
<tr>
<td><input type="text" name="row2.product" value=""></td>
<td><input type="text" name="row2.quantity" value="1"></td>
</tr>
</tbody>
</table>
<p><button type="submit">Submit</button></p>
</form>
</body>
</html>
The template for those rows could look something like:
<tr>
<td><input type="text" name="row0.product" value=""></td>
<td><input type="text" name="row0.quantity" value="1"></td>
</tr>
...except that then the names would all be the same — all rows would be "row0", so there would be no clear way of distinguishing which "quantity" went with which "product" except by the order in which they were submitted.
To get around this, the template is modified slightly:
<tr id="order">
<td><input