© Copyright 2003 Opera Software.
The HTML4 form semantics are extended with new types, new attributes for defining constraints, new DOM interfaces for validation, and new events for dependency tracking. A repeating model is introduced for declarative repeating of form sections. Mechanisms for XML submission and initialization of forms are added to the form submission model. HTML4, XHTML1.1 and the DOM are thus extended in a manner which has a clear migration path from existing HTML forms, leveraging the knowledge authors have built up with their experience with HTML so far.
This is a work in progress! This document is changing on a daily if not hourly basis in response to comments and as a general part of its development process. Comments are very welcome, please send them to htmlforms@damowmow.com and cc www-archive@w3.org. Thank you.
It is very wrong to cite this as anything other than a work in progress. Do not implement this in a production product. It is not ready yet! At all!
This document currently has no official standing within the W3C at all. It is the result of loose collaboration between interested parties over dinner, in various mailing lists, on IRC, and in private e-mail. To become involved in the development of this document, please send comments to the address given above. Your input will be taken into consideration.
This is a working draft and may therefore be updated, replaced or rendered obsolete by other documents at any time. It is inappropriate to use Working Drafts as reference material or to cite them as other than "work in progress".
To find the latest version of this working draft, please follow the "Latest version" link above.
input
element
select
element
textarea
element
pattern
attribute
required
attribute
form
attribute
autocomplete
attribute
inputmode
attribute
help
attribute
output
element
HTMLFormElement
interface
HTMLSelectElement
interface
HTMLOutputElement
interface
The following features are considered requirements for this specification:
This specification is not a subset of XForms 1.0.
This specification is an extension to [XHTML1]. It 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 need.
In general, [XForms] and this specification have different target audiences. XForms is aimed at the specialist form authoring world, for products that will not typically be sent over, or used as part of, the World Wide Web. On the other hand, this specification is expected to be implemented by general Web browsers, and used by Web authors targeting users that use those browsers. In addition, it is expected that this specification could be used to implement XForms 1.0 by transforming XForms documents into XHTML using this specification's features.
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:
The majority of the 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.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Diagrams, examples, and notes are non-normative. All other content in this specification is intended to be normative.
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 semantics of those specifications to claim compliance to this one.
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. CSS properties are just referred to as properties.
HTML input
elements use the type
attribute to
specify the data type. In [HTML4], the types are:
text
password
checkbox
radio
submit
file
image
Three other types, reset
, hidden
, and
button
, are also available, but are either not real data
types, or not modifiable by the user, and so are not considered here.
In addition, HTML also provides a few alternate elements that convey typing semantics similar to the above types, but use different data models:
select
radio
type.
select multiple
checkbox
type.
textarea
button
input
element button. (Can also be used for reset
and
button
buttons.)
This specification includes these types, their semantics, and their processing rules, by reference. Compliant UAs must follow all the guidelines given in the HTML4 specification except those modified by this specification.
These types are useful, but limited. This section 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 (in HTML4, those elements
always required at least one element child, or, in the case of
legend
, at least one character of text).
Similarly, as controls no longer need to be
contained within their form
element to be associated with
it, it is possible that authors would prefer to declare the page's forms
in advance, in the head
element of XHTML documents. This is
therefore allowed, although only when the form
element is
empty.
The form
element's action
attribute is no longer required, and there is now an implied form for orphaned form
controls. These changes are described in other parts of this
specification.
input
elementSeveral new types are introduced for the type
attribute. As
with the older types, UAs are encouraged 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 when submitting the data. They do not necessarily represent what the user is expected to type. It is the UA's responsibility to convert the user's input into the specified format.
datetime
This specification does not specify how the widget should appear. It could be something like this:
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 timezone.
date
expdate
time
number
scanf(3)
's
%f
format and similar parsers while being easier to parse
than required by some other floating point syntaxes. If the exponent part
is omitted it is assumed to be zero. Note that +0
,
0e+0
, +0e0
are invalid numbers (the minus sign
cannot be replaced by a plus sign for positive numbers, it must simply be
dropped) and UAs must therefore not serialize numbers in those formats.
integer
email
mailbox
token, defined in RFC822 section 6.1).
uri
absoluteURI
token, defined in RFC2396 section 3).
To limit the range of values allowed by the above types, two new attributes are introduced, which apply to the date-related, time-related, and numeric types:
min
max
UAs must not submit forms that contain fields whose values do not match their types (ERROR_TYPE_MISMATCH) or whose values are outside the allowed range (ERROR_RANGE_UNDERFLOW, ERROR_RANGE_OVERFLOW).
Need to define the numeric conversions for decimal to binary so that min/max can be done interoperably at difficult decimal-to-binary cases. Brendan suggested referencing ECMA262, but I don't know which section exactly.
Note that a field with a max
less than its min
can never be satisfied and thus would block a form from being submitted.
This is not considered an error condition.
Note that fields may have no value, in which case they aren't "successful", do not take part in submission, and therefore do not need to have their values match their types (unless they are required fields).
For more details on the meaning and relevance of the term "successful", see HTML4 section 17.3.2.
The following form uses some of the types described above:
<form action="..." method="post" onsubmit="verify(event)"> <p> <label> Quantity: <input name="count" type="integer" 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:00" max="17:00:00" value="08:00:00" /> — <input id="time2" name="time2" type="time" min="08:00:00" max="17:00:00" value="17:00:00" /> </p> <script type="text/javascript"> function verify(event) { // check that time1 is smaller than time2, otherwise, swap them if (event.target.time1 >= event.target.time2) { // ISO8601 times are string-comparison safe. var time2 = event.target.time2; event.target.time2 = event.target.time1; event.target.time1 = time2; } } </script> </form>
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.
The size
attribute of the input
element is
deprecated in favor of using CSS to specify the layout of the form.
select
elementIn addition to the new types above, the select
element is
extended to allow for a free-form input control which has author-specified
auto-completion values.
editable
select
element's value
can be one other than those specified in the list of option
elements.
The editable="editable"
syntax, which is
the result of 1998's XML removing some features from 1986's SGML, is a
bit ugly. What can we do about it?
For example, a Web page may wish to ask a user to enter a filename, offering some suggested names but allowing the user to enter other names as well:
<select name="filename" editable="editable"> <option>My First Holiday</option> <option>untitled1.txt</option> </select>
When this attribute is specified, the DOM type
attribute
([DOM2HTML]) has the value "edit-one".
If both editable
and multiple
are specified,
the UA must allow the user to enter multiple free-form values. This kind
of interface is sometimes seen in mail user agents for their "To:" fields,
for instance.
When both these attributes are specified, the DOM type
attribute has the value "edit-multiple". The DOM
HTMLSelectElement
interface is extended to have a new
attribute values
of type DOMStringList
([DOM3Core]) that represents the currently
selected or entered values.
In documents conforming to this specification, select
elements need not have any option
elements.
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 width of the display device 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.
soft
hard
cols
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 stylesheet that key the default 'white-space'
property values based on the wrap
element for
textarea
elements.
In addition to the new attributes given in this section, some existing attributes from [HTML4] are clarified below. These, and other attributes from HTML4, continue having the same semantics as described in HTML4 unless specified otherwise.
accept
<input type="file">
) uses
the accept
attribute to specify a comma-separated list of
content types that a server processing the form will handle correctly. In
this specification, this attribute is extended as follows:
*
, 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 an image, a sound clip, a video, etc,
without specifying the exact list of types.
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"> <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.
accept
attribute is set on a form
element, it sets the default for any file upload controls in that form.
(This is done by the file upload controls first checking their
attribute, and if they don't have one, checking their form's.)
action
form
element's action
attribute is no
longer a required attribute. If omitted, the default value is the empty
string, which is a relative URI pointing at the current document.
disabled
disabled
attribute applies to all control types,
including fieldset
(in HTML4 the disabled
attribute did not apply to the fieldset
element), except the
output
element.
maxlength
This attribute applies to text
, password
and
file
input types. In particular, it does not apply to the
date-related, time-related, and numeric field types, or to the
email
or uri
types. In
HTML4, this attribute only applied to the text
and
password
types.
When this attribute is specified on text
or
password
controls, the server must not submit a form with
the control having more than the specified number of characters (ERROR_TOO_LONG). For details on counting
string lengths, see [CHARMOD].
When specified on a file upload control, it specifies the maximum size in bytes of the content. UAs must not submit files bigger than this size (ERROR_TOO_LONG).
Servers must 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.
name
readonly
text
,
password
, email
, uri
,
date-related, time-related, and numeric input types, as well as the
textarea
element. Specifically, it does not apply to radio
buttons, check boxes, file upload fields, select
elements
(editable or not), or any of the button types; the interface concept of
"readonly" values does not apply to button-like interfaces. (The DOM
readonly
attribute ([DOM2HTML])
obviously applies to the same set of types as the HTML attribute.)
Other attributes not listed here retain the same semantics as in [HTML4].
pattern
attributeFor the text
, email
and uri
types
of the input
element, the select
element when it
has the new editable
attribute set, and the
textarea
element, a new attribute, pattern
, is
introduced to specify patterns that the strings must match.
When specified, the pattern
attribute contains a regular
expression that the field's value must match before the form may be
submitted (ERROR_PATTERN_MISMATCH).
<label> Credit Card Number: <input type="text" pattern="^[0-9]{10}$" name="cc" /> </label>
The regular expression language used for this attribute is the same as that defined in [ECMA262].
UAs must refuse to submit forms that contain fields whose values do not match their patterns.
In the case of the email
and uri
, the
pattern
attribute specifies a pattern that must be matched
in addition to the value matching the generic pattern relevant
for the field. If the pattern given by the attribute specifies a pattern
that is incompatible with the grammar of the field type, as in the example
below, then the field could never be satisfied. (A document containing
such a situation is not technically invalid, but it is of dubious semantic
use.)
<form> <p> This form could never be submitted, as the following required field can never be satisfied: <input type="uri" pattern="^[^:]+$" required="required" name="test"/> </p> </form>
When the value doesn't match the field's type, a ERROR_TYPE_MISMATCH error occurs; when the value doesn't match the pattern, a ERROR_PATTERN_MISMATCH error occurs.
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
check boxes, those with the type hidden
, image inputs,
buttons, fieldset
s, and output
elements. It
can be used on controls with the readonly
attribute
set; this may be useful in scripted environments. For disabled controls,
the attribute has no effect.
User agents must not submit forms that have form controls marked as required that do not have values (ERROR_REQUIRED). For radio buttons, exactly one radio button from each set must be checked.
Here is a form fragment showing two required fields and one optional field. A user agent would not allow the user to submit the form until the "name" and "team" fields were filled in.
<ul> <li>Name: <input type="text" name="name" required="required" /></li> <li>Team: <select name="team" required="required"> <option value="foxes">The Foxes</option> <option value="ferrets">The Ferrets</option> <option value="kittens">The Kittens</option> </select> <li>Comment: <input type="text" name="comment" /></li> </li> </ul>
form
attributeAll form controls can have the form
attribute specified.
The form
attribute gives the ID of the form
element the form control should be associated with, and overrides the
relationship between the form control and any ancestor form
element.
Setting an element's form
attribute either to a
non-existent ID or to one that identifies an element that is not an HTML
form
element disassociates the form control from its form,
leaving it unassociated with any form. On the other hand, an element whose
form
attribute is the empty string (as in
form=""
) is treated like an element
with no form
element ancestor (even if it has such an
ancestor).
When set on a fieldset
element, this also changes the
association of any descendant form controls, unless they have
form
attributes of their own, or are contained inside forms
that are themselves descendants of the fieldset
element.
When forms are submitted, 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 only with one form at a time.
A form
attribute that specifies an ID that occurs multiple
times in a document should select the same form as would be selected by
the getElementById()
method for that ID ([DOM3CORE]).
In this example, each row contains one form, even though without this attribute it would not be possible to have more than one form per table if any of them span 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>
autocomplete
attributeAll form controls except the various push button controls and
hidden
and output
controls, can have the
autocomplete
attribute set. The attribute takes two values,
true
and false
. The default, when the attribute
is not specified, is true
.
A true value means the UA is allowed to store the value entered by the user so that if the user returns to the page, the UA can pre-fill the form. A false value means that the UA must not remember that field's value.
Banks frequently do not want UAs to pre-fill login information:
<p>Account: <input type="text" name="ac" autocomplete="false" /></li> <p>PIN: <input type="text" name="pin" autocomplete="false" /></li>
In practice, this attribute is required by many banking institutions, who insist that UAs 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.
inputmode
attributeThe inputmode
attribute applies to the input
element when it has a type
attribute of text
,
password
, email
, or uri
, to the
select
element when it has a the editable
attribute set, 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].
help
attributeAny form control can have a help
attribute specified. This
attribute contains a URI that the UA may use to provide help information
regarding the active field.
This specification does not specify how help information should be used, but for example, the UA could show a small pop-up window if the user focuses such a control and pressed the F1 key, or could show the help information in a side-bar while the relevant control is focused.
This attribute is added mainly because XForms has it, to
show that it would be trivial to add to HTML as well. However, there is
some doubt that it is actually a useful feature. The XForms
hint
element is already supported in HTML, as the
title
attribute.
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. It has no attributes beyond the common attributes and
the form
attribute. Its value is given by its contents, which
must be only text (like the textarea
element). Its value can
be set dynamically via the value
DOM attribute, thus
replacing the contents of the element.
The initial value of the output
control is stored
in a mutable defaultValue
DOM attribute of type
DOMString
. This is similar to the way textarea
elements work, except that the contents of an element for
output
controls reflects the current value not the
initial, or default, value. See [HTML4] section
17.2 for the
definiton of the term "initial value".
The output
element is never successful for form submission.
Resetting a form does reset its output
elements.
The following example shows two input fields. Changing either field
updates an output
element containing the product of both
fields.
<form> <p> <input name="a" type="number" value="0"> * <input name="b" type="number" 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.
When a form control has no form element ancestor and no form attribute,
or when the form attribute is set to the empty string, it is called an
orphan form control. Orphan controls are bound to
an anonymous HTMLFormElement
DOM node that is associated with
the document and has its
parentNode
set to the document node, but does not
(initially) appear in the document. If it is inserted into the document by
some evil QA engineer, or otherwise manipulated, it does not lose its role
as guardian of the orphan form controls, although if then removed from the
document again, its parentNode
does not revert to the
document node.
Implementors: Please let me know if that is a good way of defining it. If you'd rather it did revert to the document node, or would rather never have it associated with the document node, or whatever, let me know. The idea is to make events bubble through this element and then up to the document, the bit about inserting into the document is just there to define it. I just want this easy to implement. I don't really care either way as far as the edge cases go here so long as they are defined, so let me know what you prefer, even if it is the status quo.
The implied form is only created when it is required. When created, it
is added to the document's DOM's forms
collection.
This form can be submitted like any other form; it partakes in all the
normal event handling and so forth. Since by default forms have
action
attributes that point to the base URI (typically the
document itself), and by default use the GET URI scheme, the obsolete
isindex
element can be replaced with the following more
styleable alternative:
<p>Keywords: <input name="keywords"> <input type="submit"></p>
The only difference is that this would be submitted using
application/x-www-form-urlencoded
instead of simply causing
the keywords to be appended as one query string.
There are several elements that are defined as expecting particular elements as children. Using the DOM, or in XML, it is possible for authors to violate these expectations and place elements in unexpected places.
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 such an invalid construct, UAs must proceed as follows:
input
elements
output
elements containing elements
defaultValue
DOM attribute is initialized from the
DOM3 Core textContent
attribute ([DOM3CORE]). Setting the element's
value
attribute is defined to 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 elements
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.
We could take the child text nodes instead. Or make it equivalent to editing the first text node. But doing it as textContent is the simplest from a specification point of view. Opinions?
select
elements containing nodes other than
option
and optgroup
elements, and for
optgroup
elements containing nodes other than
option
elements
option
and optgroup
elements take
part in the select
semantics. Unless otherwise forced to
appear by a stylesheet, other child nodes are never visible.
option
elements containing nodes other than text
nodes
textContent
DOM attribute's value.
As far as rendering goes, it is left largely up to the UA. Two possibilities are sensible: rendering the content normally, just as it would have been outside the form control; and rendering the initial value only, with the rest of the content not displayed (unless forced to appear through some CSS).
It should be noted that while nesting
a form inside a select
control may look cool, it is
extremely poor UI and must not be encouraged.
option
and optgroup
elements that are
not inside select
elements
span
elements as
far as rendering goes.
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 fields. 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 to the reader.
In this section, a number of references are made to namespaces. For authors who are only using HTML or XHTML, the definitions below ensure that no namespaces need appear in the document (except the namespace on the root element). Thus, such a reader can simply gloss over the parts that mention namespaces.
In order to implement such a form declaratively, a new global attribute
is introduced: the repeat
attribute.
When placed on elements in the http://www.w3.org/1999/xhtml
namespace, it must be a namespace-free attribute, and when placed on other
elements, it must be an attribute in the
http://www.w3.org/1999/xhtml
namespace.
The effect of this attribute depends on its value, which is a
space-separated list of tokens with no leading spaces. The first token is
mandatory and must be either template
or
repeated
. If the attribute is present but either is empty, or
starts with whitespace, or has a first token that is neither of these two
values, it has no effect.
The second token is optional, if present it must be an integer. If the second token is not an integer, it is ignored. The third token, and any subsequent tokens, if any are present, are always ignored.
An element in the http://www.w3.org/1999/xhtml
namespace
with the repeat
attribute in no
namespace, or an element in any other namespace with the repeat
attribute in the
http://www.w3.org/1999/xhtml
namespace, with the first token
of the attribute's value equal to template
, is a repetition template.
Repetition templates may occur anywhere. They are not specifically associated with any form.
Every template has an index associated with it. By default, the index
has the value 0. However, if the aforementioned repeat
attribute has a second token, and that
token is an integer (one or more digits in the range 0-9, optionally with
a leading minus sign), then the index is set to that value.
Unrecognized tokens must be ignored.
<div repeat="template 1 "/> <!-- A template, index set to 1. --> <div repeat="template +1 3"/> <!-- A template, index set to 0 (second and third tokens ignored). --> <div repeat="template 2 3"/> <!-- A template, index set to 2 (third token ignored). --> <div repeat="invalid template "/> <!-- Not a template. --> <div repeat=" template "/> <!-- Not a template (leading whitespace). -->
An element in the http://www.w3.org/1999/xhtml
namespace
with the repeat
attribute in no
namespace, or an element in any other namespace with the repeat
attribute in the
http://www.w3.org/1999/xhtml
namespace, with the first token
of the attribute's value equal to repeated
, is a repetition block.
Repetition blocks should only occur as following siblings of repetition templates. If an element is declared as a repetition block but does not have a previous sibling that is a repetition template, then it can only take part in certain aspects of the repetition model (namely deletion and movement, and not addition). Such elements are termed orphan repetition blocks.
Every repetition block has an index associated with it. By default, the
index is equal to the number of repetition blocks present in the DOM tree
between the repetition block and its template (so the first block's index
defaults to 0, the second to 1, and so forth). The index of orphan
repetition blocks defaults to 0. However, if the repetition block's
repeat
attribute has a second token,
and that token is an integer (one or more digits in the range 0-9,
optionally with a leading minus sign), then the index is set to that
value.
<div> <div repeat="template"/> <!-- The template for the next few elements. --> <div repeat="repeated"/> <!-- A simple repetition block, index 0. --> <div repeat="repeated -5"/> <!-- Another, index -5 --> <div repeat="repeated"/> <!-- A simple repetition block, index 2. --> <div repeat="nothing"/> <!-- Just a normal element. --> <div repeat="repeated"/> <!-- A simple repetition block, index 3. --> </div> <div repeat="repeated"/> <!-- Orphan repetition block, index 0. -->
Several new button types are introduced to support the repetition model.
These values are valid types for both the input
element and
the button
element.
add
remove
move-up
move-down
These control types can never be successful.
In addition, to support the add
type, a
new attribute is introduced to the input
and
button
elements: template
.
template
These are described in more detail in the next section.
A repetition template 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 stylesheet:
@namespace html url(http://www.w3.org/1999/xhtml); :not(html|*)[html|repeat="template"], :not(html|*)[html|repeat^="template "], html|*[|repeat="template"], html|*[|repeat^="template "] { display: none; }
Any form controls inside a repetition
template are associated with their form's
templateElements
DOM attribute, and are not present
in the form's elements
DOM attribute, unless the relevant
form is inside the template itself. Since only controls in the
elements
attribute can be successful, controls inside
repetition templates that would be part of forms outside the template can
never be successful and cannot be pre-filled directly when the form is
pre-seeded. However, see the section on seeding a form with initial
values for details on how repeating blocks can be pre-filled.
If an add
button is activated, and it
has a template
attribute, and the element, in the same
document, with the ID given by the template
attribute in
question, is a repetition template
as defined above, then that element's template replication behaviour is
invoked. (Specifically, in scripting-aware environments, the element's
addRepetitionBlock()
method
is called with a null argument.)
If an add
button is activated, and it
has no template
attribute, but the element has an ancestor
that is a repetition block that is
not an orphan repetition block, then the repetition template associated with that
repetition block has its template replication behaviour invoked with the
respective repetition block as its argument. (Specifically, in
scripting-aware environments, the element's addRepetitionBlock()
method is
called with a reference to the DOM Element node that represents the
repetition block.)
When a template's replication behaviour is invoked (specifically, when
either its addRepetitionBlock()
method is
called or its addRepetitionBlockByIndex()
method is called) the following is performed:
addRepetitionBlockByIndex()
method, and the value of the method's index argument is greater than the
template's index, then the template's index is set to the value of index
argument.
http://www.w3.org/1999/xhtml
namespace, then the repeat
attribute in no namespace on the cloned
element has its value changed to repeated
. Otherwise, the
repeat
attribute in the
http://www.w3.org/1999/xhtml
namespace has its value changed
to repeated
.
addRepetitionBlockByIndex()
method, the new repetition block element's index is set to the method's
index argument. Otherwise, the new repetition block element's index is
set to the template's index.
For an example, see the example section below.
If a remove
button is activated, and
the element has an ancestor that is a repetition block as defined above, then the
nearest such ancestor's template deletion behaviour is invoked.
(Specifically, in scripting-aware environments, the element's removeRepetitionBlock()
method is
invoked.)
When a repetition block's deletion behaviour is invoked (specifically,
when its removeRepetitionBlock()
method is called) the following is performed:
This occurs even if the repetition block is an orphan repetition block.
For an example, see the example section below.
The two remaining button types, move-up
and move-down
, are used to move the current
repetition block up or down the sibling repetition blocks.
If a move-up
or move-down
button is activated, and the
element has an ancestor that is a repetition
block as defined above, then the nearest such ancestor's
template movement behaviour is invoked in the relevant direction.
(Specifically, in scripting-aware environments, the element's moveRepetitionBlock()
method is
called; for move-up
buttons the
argument is -1 and for move-down
buttons the argument is 1).
When a repetition block's movement behaviour is invoked (specifically,
when its moveRepetitionBlock()
method
is called) the following is performed, where distance is an
integer representing how far and in what direction to move the block (the
argument to the method):
previousSibling
is defined and
is not a repetition template, set
target to this previousSibling
and, if it is a
repetition block, increase
distance by one (make it less negative by one).
nextSibling
is defined
and is not a repetition template,
set target to this nextSibling
and, if it is a
repetition block, decrease
distance by one. After the loop, set target to
target's nextSibling
(which may be null).
insertBefore()
method with the newChild
argument being the repetition block
and the refChild
argument being target (which may
be null by this point).
This occurs even if the repetition block is an orphan repetition block.
Moving repetition blocks does not change the index of the repetition blocks.
In addition, user agents must automatically disable move-up
buttons (irrespective of the value of
the disabled
DOM attribute) when their repetition block could
not be moved any higher according to the algorithm above, and when the
buttons are not in a repetition block. Similarly, user agents must
automatically disable move-down
buttons when their repetition block could not be moved any lower according
to the algorithm above, and when the buttons are not in a repetition
block. This automatic disabling does not affect the DOM
disabled
property.
The following example shows how to use repetition templates to dynamically add more rows to a form in a table.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> <title>Form Repeat Demo</title> </head> <body> <form action="http://software.hixie.ch/utilities/cgi/test-tools/echo" method="post" enctype="multipart/form-data"> <table> <thead> <tr> <th>Name</th> <th>Count</th> <th></th> </tr> </thead> <tbody> <tr repeat="template" id="row"> <td><input type="text" name="name__row_" value=""></td> <td><input type="text" name="count__row_" value="1"></td> <td><input type="remove" value="Delete Row"></td> </tr> <tr repeat="repeated"> <td><input type="text" name="name_0" value="John Smith"></td> <td><input type="text" name="count_0" value="1"></td> <td><input type="remove" value="Delete Row"></td> </tr> </tbody> </table> <p> <input type="add" value="Add Row" template="row"> </p> </form> </body> </html>
Initially, one row would be visible, with two text input fields, one having the value "John Smith" and the other having the value "1".
If the "Add Row" button is pressed, a new row is added. The first such row would have the index 1 and so the controls would be named "name_1" and "count_1" respectively.
If the "Delete Row" button above is pressed, the row would be removed.
This example does not demonstrate nested repeat blocks, reordering repetition blocks, and inserting new repetition blocks in the middle of the existing sequence, all of which are possible using the facilities described above.
The following events are considered form events:
Some of the above are mainly described in [DOM3EVENTS] and [HTML4]. This section introduces the new events and new semantics for the existing events.
Since form controls no longer need to be descendants of their form elements, the semantics of form events bubbling are changed slightly.
If a bubbling form-related event is targeted
at, or bubbles into, a form control with a form
attribute
pointing to a valid form (which, if the attribute is the empty string,
would be the implied form), it continues
bubbling not at the node's parent, but at the specified form element.
For example, in the following document:
<application> <fieldset xmlns="http://www.w3.org/1999/xhtml" form=""> <button> Test </button> </fieldset> </application>
...clicking the button generates an event that is targeted on the button, bubbles up to the fieldset, is redirected straight to the anonymous implied form, and from there bubbles to the document (recall that the anonymous form node is parented to the document node by default). The root element never sees the event during the bubbling phase.
If a bubbling form-related event bubbles into the document node without
passing through a form
element, it is similarly redirected so
that it continues bubbling at the implied form. (In the esoteric case
where the implied form has been inserted into the document, this will
cause the event to bubble into the document node twice.)
The scope chain for ECMAScript executed in HTML event handler attributes
links from the activation object for the handler, to its this
parameter (the event target), to the form, to the document, to the default
view (the window).
The event handler is passed one argument, event, corresponding to the event object.
This definition is intentionally backwards compatible with DOM Level 0. See also ECMA-262 Edition 3, sections 10.1.6 and 10.2.3, for more details on activation objects. [ECMA262]
In [DOM3EVENTS] and [HTML4], the change
event is fired on a
form control element when the control loses the input focus and its value
has been modified since gaining focus.
To address the need for more immediate feedback mechanisms, this
specification introduces the input
event. This event is fired on a control whenever the value of the
control changes due to input from the user, and is otherwise identical to
the change
event. (For example, it bubbles, is not
cancelable, and has no context information.)
Sometimes form controls are inter-dependent. In these cases, it is more
intuitive to specify the dependencies on the control whose value or
attributes depend on another's, rather than specify which controls should
be affected by a change on the element that changes. For this reason, two
new events are introduced, formchange
and forminput
.
These events are in the same namespace as the other form events, do not bubble, cannot be canceled, have no context information, and have no default action.
The default action of a change
event is to fire a formchange
event at each element in the
form's elements
and templateElements
lists, in
document order, with the elements
list processed first. Note
that template controls are affected. This is important as it
enables templates to be kept up to date so that when they are cloned, they
already reflect the form's state.
The input
element analogously invokes the forminput
event on all the form's controls as
its default action.
Due to the way in which scope resolution is defined, a subset of ECMAScript that is completely declarative can be specified for dependencies. Doing so is left as an exercise to the reader.
Should I specify one?
In the following example, the text field is only enabled if the checkbox is checked.
<p> <label> <input type="checkbox" name="subscribe"> Subscribe to daily newsletter </label> </p> <p> <label> E-mail: <input type="email" name="email" disabled="disabled" onformchange="disabled = !subscribe.checked"> </label> </p>
With the introduction of the various type checking mechanisms, some way
for scripting authors to hook into the type checking process is required.
This is provided by the formerror
event (in the http://www.w3.org/2001/xml-events
namespace).
Can we put that event into that namespace?
When a form is submitted, each control in that form, in document order,
is checked for validity. For each control that fails to comply with its
constraints (i.e. each control whose validity
attribute is
non-zero), a formerror
event must be
fired on the control.
The onformerror
attribute (on input
,
textarea
and select
elements) can be used to
write handlers for this event.
The formerror
event bubbles, as
described in an earlier section.
This event is cancelable. The default action depends on when the event
was fired. If it was fired during form submission, then the default action
is UA-specific, but is expected to consist of focusing the element,
alerting the user that the entered value is unacceptable in the user's
native language along with explanatory text saying why the value
is currently invalid, and aborting the form submission. UAs would
typically only do this for the first form control found to be invalid;
while the event is dispatched to all invalid controls, it is simpler for
the user to deal with one error at a time. When fired by script calling
the validate()
method (i.e. not during form submission), the
event has no default action.
The following example shows one way to use this event.
<form action="..." method="post"> <p> <label> Byte 1: <input name="byte" type="integer" min="0" max="255" required="required" onformerror="failed(event)" /> </label> <output name="error"/> </p> <script type="text/javascript"> function failed(event) { // a control can fail for more than one reason; only report one of them. form.error.value = 'The value is wrong for a reason I did not expect.'; if (event.target.validity & event.target.form.ERROR_TYPE_MISMATCH) form.error.value = 'That is not an integer.'; else if (event.target.validity & event.target.form.ERROR_RANGE_UNDERFLOW) form.error.value = 'That integer is less than 0.'; else if (event.target.validity & event.target.form.ERROR_RANGE_OVERFLOW) form.error.value = 'That integer is more than 255.'; else if (event.target.validity & event.target.form.ERROR_RANGE_REQUIRED) form.error.value = 'You did not enter a value.'; } </script> </form>
This description is really bad. It's the algorithm I want but it needs to be rewritten. Anyone able to write it up better?
Processors conforming to this specification must use a slightly different algorithm than the [HTML4] form submission algorithm (HTML4 section 17.13.3), as described in this section.
When the user agent submits a form (e.g., in response to the user activating a submit button), it must perform the following steps.
All the controls that apply to the form, whether successful or not,
should be taken, in document order. These controls are those listed in
the form's elements
DOM attribute, and excludes certain
controls as specified in the section describing the repetition
model.
The original list of ways in which a control can be
successful is defined in HTML4
section 17.3.2. This specification extends this list in places, for
example output
elements are defined to never be successful.
A form data set is a sequence of control-name, index, current-value triples constructed from the controls identified in the first step.
It is constructed by iterating over the form controls listed in step one, taking note of the form control names as they are seen. With each control, if it is the first time that control's name has been seen, then the control is assigned an index of 0. Otherwise, if the control name was associated with an earlier control, then the index assigned is exactly one more than the last control with that name. Even unsuccessful controls are so numbered. However, only successful controls are added to the form data set. A successful control with more than one value is added multiple times, one for each value (each time with the same form control name and form control index).
For example, the following form:
<form> <p> <label> Name: <input type="text" name="username"/> </label> </p> <p> Lottery numbers: <input type="integer" name="number" min="1" max="49"/> <input type="integer" name="number" min="1" max="49"/> <input type="integer" name="number" min="1" max="49"/> <input type="integer" name="number" min="1" max="49"/> <input type="integer" name="number" min="1" max="49"/> </p> <p> <label> Games: <select name="type" multiple="multiple"> <option value="Thunderbolt"> Thunderbolt </option> <option value="Lightning"> Lightning </option> </select> </label> </p> <p> <input type="submit" value="Send"> </p> </form>
...if filled in with the name "Erwin" and the numbers 20, 30 and 40 with the first and last number fields left blank, and all the values in the select list selected, would generate the following form data set:
The form data set also includes a list of which repetition blocks are involved in the submission.
For each control in the form data set, the control and the control's ancestors are examined, up to but not including the first node that is a common ancestor of the control and the form, or is the form itself. For each element so examined, if it is a repetition block that is not an orphan repetition block and whose template does have an ID, and that repetition block has not yet been added to the list of repetition blocks, it is added.
The form data set is then encoded according to the content type
specified by the method
and enctype
attribute
of the form
element. If method
is
get
, then enctype
is treated as if it had the
value application/x-www-form-urlencoded
, whatever its real
value. The possible values of enctype
defined by this
specification are:
application/x-www-form-urlencoded
multipart/form-data
application/x-www-form+xml
Other values may be defined by other specifications.
During this step, the form data set is examined to ensure all the characters are representable in the submission character encoding.
submit
events.
The submit
event is then submitted as described in [HTML4]. If it is canceled, then the submission
processing stops at this point.
Finally, the encoded data is sent to the processing agent designated
by the action
attribute using the protocol method specified
by the method
attribute.
For HTTP GET submissions, the encoded form data is used as the query value. For HTTP POST submissions, the encoded data is used as the entity body.
User agents should handle responses to the submission. For example if
the action
denotes an HTTP resource, and the
method
is post
and the remote server replies
with a 200 OK
response, then the returned document should
be displayed to the user as if the user had navigated to that document
by following a link to it.
The different form data set encoding types each define how to find the character encoding to use to submit the data.
Sometimes, the form submission character set used is not able to represent all the character present in the form submission.
If the form data set contains characters that are outside the submission character set, the user agent should inform the user that his submission will be changed, for example using a dialog in the form:
____________________________________________________ || Warning ||||||||||||||||||||||||||||||||||||||||||| | | | This form cannot handle some of the characters you | | have entered. The data will be sent as "D?rst". | | | | (( Send anyway )) ( Return to form ) | `----------------------------------------------------'
If the submission is not canceled, the user agent MUST replace each character that is not in the submission character set with one or more replacement characters.
For each such missing character, UAs must either transliterate the character to a UA-defined human-recognizable representation (for example transliterating U+263A to the three-character string ":-)" in US-ASCII, or U+2126 to the byte 0xD9 in ISO-8859-7), or, for characters where a dedicated transliteration is not known to the UA, replace the character with either U+FFFD, "?", or some other single character representing the same semantic as U+FFFD.
Note that a string containing the codepoint's value itself (for example the six-character string "U+263A" or the seven-character string "☺") is not considered to be human readable and must not be used as a transliteration. (This is to discourage servers from attempting to mechanically convert such codepoints back into Unicode characters, as there is no way to distinguish such characters from identical literal strings entered by the user.)
application/x-www-form-urlencoded
This is the default content type. Forms submitted with this content type must be encoded as follows:
accept-charset
attribute. If the attribute is not specified,
then the client should use either the page's character encoding, or
UTF-8. Character encodings that are not supersets of US-ASCII must not be
used (this includes UTF-16 and EBCDIC).
hidden
with
the name _charset_
, it is forced to appear in the form data
set, with the value equal to the name of the submission character
encoding used.
Note that the index and repetition block parts of the form data set are not used.
application/x-www-form+xml
: XML submissionThis section defines the expected behaviour for step 3, "Step three:
Encode the form data set", of the submission algorithm described above,
for the form content type application/x-www-form+xml
. The
rest of the form submission process progresses as described above.
The message entity is an XML 1.1 document, encoded as UTF-8, which has a
root element named "submission", with no prefix, defining a default
namespace data:,formData
. UA may include an XML declaration
but this is not necessary as it would be redundant (the MIME type and
version must not be changed from the above values, and submission
documents have no document type and therefore are always standalone.).
Note that the form's accept-charset
attribute is ignored
for this encoding type.
First, for each repetition block in the form data set, an element
repeat
is inserted, with an attribute
template
equal to the ID of the template, and an attribute
index
equal to the index of the repetition block. The element
is empty.
Servers are generally expected to ignore repeat
elements; they are primarily included so
that form data can be round-tripped using the data
attribute
on the form element.
Then, for each successful control that is not a file upload control, in
the order that the controls are to be found in the original document, an
element field
is inserted, with an attribute
name
having the name of the form control, an attribute
index
having the index described above in the definition of
the form data set, and with the
element content being the current value of the form control.
Form controls with multiple values result in multiple field
elements being inserted into the output, one for each value, all with the
same index.
File controls are submitted using a file
element instead of
a field
element. The file
element has four
attributes, name
, index
, filename
,
and type
. The name
attribute contains the name
of the file control. The index
attribute contains the index
in the control's entry in the form data set. The filename
attribute is optional and may contain the name of the file. The
type
attribute is not optional and must contain the MIME type
of the file. The contents of the file are base64 encoded and then included
literally as content directly inside the file
element. As
base64 data is whitespace-clean, UAs may introduce whitespace into the
file
element to ensure the submitted data has reasonable line
lengths. This is, however, completely optional. (It is primarily intended
to make it possible to write readable examples of submission output.)
UAs may use either CDATA blocks, entities, or both in escaping the contents of attributes and elements, as appropriate. The resulting XML must be a well-formed XML instance. The only mention of namespaces in the submission document must be the declaration of the default namespace on the root element.
Whitespace may be inserted around elements that are children of the
submission
element in order to make the submitted data easier
to scan by eye. However, this is optional. Processors should not be
affected by such whitespace, or whitespace inside file
elements, when reading the submitted data back from the XML instance.
(Whitespace inside field
elements is significant, however.)
The following example illustrates
application/x-www-form+xml
encoding. Suppose we have the
following form:
<form action="http://example.com/cgi/handle" enctype="application/x-www-form+xml" method="post"> <p> <label> What is your name? <input type="text" name="submit-name"/> </label> <label> What files are you sending? <input type="file" name="files"/> </label> <label> When were they written? <input type="date" name="stamp"/> </label> <input type="submit" value="Send"> </p> </form>
If the user enters "Larry" in the text input, selects the text file "file1.txt", and picks an arbitrary date, the user agent might send back the following data:
Content-Type: application/x-www-form+xml <submission xmlns="data:,formData"> <field name="submit-name" index="0">Larry</field> <file name="files" index="0" filename="file1.txt" type="text/plain;charset=iso-8859-1"> Y29udGVudHMgb2YgZmlsZTEudHh0 </file> <field name="stamp" index="0">1979-04-13</field> </submission>
If the user selected a second (image) file "file2.png", and changes the date, the user agent might construct the entity as follows:
Content-Type: application/x-www-form+xml <submission xmlns="data:,formData"> <field name="submit-name" index="0">Larry</field> <file name="files" index="0" filename="file1.txt" type="text/plain;charset=iso-8859-1"> Y29udGVudHMgb2YgZmlsZTEudHh0 </file> <file name="files" index="0" filename="file2.png" type="image/png"> iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAMAAAAoyzS7AAAABGdBTUEAAK /INwWK6QAAABl0RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwA AAAGUExURQD/AAAAAG8DfkMAAAAMSURBVHjaYmAACDAAAAIAAU9tWeEAAA AASUVORK5CYII= </file> <field name="stamp" index="0">1979-12-27</field> </submission>
Note how the content of the plain text attached file is base64-encoded, despite being a plain text file. This preserves the integrity of the file in cases where the MIME type is incorrect. It also means that files with malformed content, for example a file encoded as UTF-8 with stray continuation bytes, will be transmitted faithfully instead of being re-encoded by the UA.
This example illustrates this encoding for the case with two form controls with the same name. Suppose we have the following form:
<form enctype="application/x-www-form+xml" method="post"> <p> Enter your new password twice: <input type="password" name="password"/> <input type="password" name="password"/> <input type="submit" value="Send"> </p> </form>
If the user enters "perfect" and "prefect", the user agent might send back the following data:
Content-Type: application/x-www-form+xml <submission xmlns="data:,formData"> <field name="password" index="0">perfect</field> <field name="password" index="1">prefect</field> </submission>
Recall the example for repetition blocks. If it was immediately submitted, the output would be an XML file equivalent to:
Content-Type: application/x-www-form+xml <submission xmlns="data:,formData"> <repeat template="row" index="0"/> <field name="name_0" index="0">John Smith</field> <field name="count_0" index="0">1</field> </submission>
If a form
has a data
attribute, it must be a
URI that points to a well-formed XML file containing a
formdata
element in the data:,formData
namespace.
UAs must process this file if it has an XML MIME type, if it is a well-formed XML file, and if the root element is the right root element in the right namespace. If any of these conditions are not met, UAs must act as if the attribute was not specified, although they may report the error to the user. UAs are expected to correctly handle namespaces, so the file may use prefixes, etc.
If the UA processes the file, it must use the following algorithm to fill the form.
repeat
elements in the
data:,formData
namespace that are children of the root
element, have a non-empty template
attribute and an
index
attribute that contains only one or more digits in the
range 0-9 with an optional leading minus sign, have no other
non-namespaced attributes, and have no content, must be processed as
follows:
If the template
attribute specifies an element that is
not a repetition template, then
the element is ignored.
If the template
attribute specifies a repetition template and that template
already has a repetition block
with the index specified by the index
attribute, then the
element is ignored.
Otherwise, the specified template's addRepetitionBlockByIndex()
method is called, with a null first argument and the index specified by
the repeat
element's
index
attribute as the second.
field
elements in the data:,formData
namespace that are children of the root element, have a non-empty
name
attribute and an index
attribute that
contains only one or more digits in the range 0-9, have no other
non-namespaced attributes, and have either nothing or only text and CDATA
nodes as children, must be used to initialize fields, as follows.
First, the form control that the field references must be identified.
This is done by walking the list of form controls associated with the
form until one is found that has a name exactly equal to the name given
in the field
element's name
attribute,
skipping as many such matches as is specified in the index
attribute.
If the identified form control is a file upload control, a push
button control, or an image control, then the field
element
is now skipped.
Next, if the identified form control is not a multiple-valued control
(a multiple-valued control is one that can generate more than one value
on submission, such as a <select
multiple="multiple">
), or if it is a multiple-valued control
but it is the first time the control has been identified by a
field
element in this data file that was not ignored, then
it is set to the given value (the contents of the field
element), removing any previous values (even if these values were the
result of processing previous field
elements in the same
data file). Otherwise, this is a
subsequent value for a
multiple-valued control, and the given value (the contents of the
field
element) should be added to the list of
values that the element has selected.
If the element cannot be given the value specified, the
field
element is ignored and the control's value is left
unchanged.
If the element is a multiple-valued control and the control already has the given value selected, but it can be given the value again, then that occurs. For example, in the following case:
<select name="select" multiple="multiple"> <option>test</option> <option>test</option> <option>test</option> </select>
...if the data file contained two instances of:
<field name="select" index="0">test</select>
...then the first two option
elements would end up
selected, and the last would not. This would be the case irrespective of
which option
elements had their selected
attribute set in the markup.
The option
elements are never directly
matched by field
elements; it is the select
element in this case that is matched (twice). This is why the two
field
elements select subsequent values in the control.
If the element is a multiple-valued control and the control already has the given value selected and it cannot be given the value again, then the field is ignored.
formchange
event is then
fired on all the form controls of the form.
Note that file upload controls cannot be repopulated.
However, output
control can be populated. This can
be used, for example, for localizing a form by including the structure in
one file and the strings in another. (The semantics of this practice are
somewhat dubious, however. It is only mentioned because XForms advocates
claim this as a feature.)
Unless otherwise specified, these interfaces have the same semantics as defined in [DOM2HTML].
interface HTMLFormElement : HTMLElement { readonly attribute HTMLCollection elements; readonly attribute long length; attribute DOMString name; attribute DOMString acceptCharset; attribute DOMString action; attribute DOMString enctype; attribute DOMString method; attribute DOMString target; void submit(); void reset(); // new in this specification: const unsigned short ERROR_TYPE_MISMATCH = 1; const unsigned short ERROR_RANGE_UNDERFLOW = 2; const unsigned short ERROR_RANGE_OVERFLOW = 4; const unsigned short ERROR_TOO_LONG = 8; const unsigned short ERROR_PATTERN_MISMATCH = 16; const unsigned short ERROR_REQUIRED = 32; const unsigned short ERROR_USER_DEFINED = 32768; attribute DOMString accept; readonly attribute HTMLCollection templateElements; void validate(); }; interface HTMLSelectElement : HTMLElement { readonly attribute DOMString type; attribute long selectedIndex; attribute DOMString value; attribute unsigned long length; // raises(DOMException) on setting readonly attribute HTMLFormElement form; readonly attribute HTMLOptionsCollection options; attribute boolean disabled; attribute boolean multiple; attribute DOMString name; attribute long size; attribute long tabIndex; void add(in HTMLElement element, in HTMLElement before) raises(DOMException); void remove(in long index); void blur(); void focus(); // new in this specification: attribute boolean editable; attribute DOMString pattern; attribute boolean required; attribute boolean autocomplete; attribute DOMString inputmode; attribute HTMLCollection selectedOptions; void reset(); readonly attribute long validity; void validate(); void markValid(); void markInvalid(); }; interface HTMLOptGroupElement : HTMLElement { attribute boolean disabled; attribute DOMString label; }; interface HTMLOptionElement : HTMLElement { readonly attribute HTMLFormElement form; attribute boolean defaultSelected; readonly attribute DOMString text; readonly attribute long index; attribute boolean disabled; attribute DOMString label; attribute boolean selected; attribute DOMString value; }; interface HTMLInputElement : HTMLElement { attribute DOMString defaultValue; attribute boolean defaultChecked; readonly attribute HTMLFormElement form; attribute DOMString accept; attribute DOMString accessKey; attribute DOMString align; attribute DOMString alt; attribute boolean checked; attribute boolean disabled; attribute long maxLength; attribute DOMString name; attribute boolean readOnly; attribute unsigned long size; attribute DOMString src; attribute long tabIndex; attribute DOMString type; attribute DOMString useMap; attribute DOMString value; void blur(); void focus(); void select(); void click(); // new in this specification: attribute long min; attribute long max; attribute DOMString pattern; attribute boolean required; attribute boolean autocomplete; attribute DOMString inputmode; readonly attribute RepetitionElement template; void reset(); readonly attribute long validity; void validate(); void markValid(); void markInvalid(); }; interface HTMLTextAreaElement : HTMLElement { attribute DOMString defaultValue; readonly attribute HTMLFormElement form; attribute DOMString accessKey; attribute long cols; attribute boolean disabled; attribute DOMString name; attribute boolean readOnly; attribute long rows; attribute long tabIndex; readonly attribute DOMString type; attribute DOMString value; void blur(); void focus(); void select(); // new in this specification: attribute DOMString wrap; attribute DOMString pattern; attribute boolean required; attribute boolean autocomplete; attribute DOMString inputmode; void reset(); readonly attribute long validity; void validate(); void markValid(); void markInvalid(); }; interface HTMLButtonElement : HTMLElement { readonly attribute HTMLFormElement form; attribute DOMString accessKey; attribute boolean disabled; attribute DOMString name; attribute long tabIndex; readonly attribute DOMString type; attribute DOMString value; // new in this specification: readonly attribute RepetitionElement template; }; interface HTMLLabelElement : HTMLElement { readonly attribute HTMLFormElement form; attribute DOMString accessKey; attribute DOMString htmlFor; }; interface HTMLFieldSetElement : HTMLElement { readonly attribute HTMLFormElement form; // new in this specification attribute boolean disabled; }; interface HTMLLegendElement : HTMLElement { readonly attribute HTMLFormElement form; attribute DOMString accessKey; attribute DOMString align; }; // new in this specification interface HTMLOutputElement : HTMLElement { attribute DOMString defaultValue; readonly attribute HTMLFormElement form; attribute DOMString name; attribute DOMString value; void reset(); }; // new in this specification interface RepetitionElement { const unsigned short REPETITION_NONE = 0; const unsigned short REPETITION_TEMPLATE = 1; const unsigned short REPETITION_BLOCK = 2; attribute unsigned short repetitionType; attribute long repetitionIndex; readonly attribute Element repetitionTemplate; readonly attribute HTMLCollection repetitionBlocks; void addRepetitionBlock(in Node refNode); void addRepetitionBlockByIndex(in Node refNode, in long index); void moveRepetitionBlock(in long distance); void removeRepetitionBlock(); } // new in this specification interface FormDocument { Document load(in DOMString action, in DOMString method, in DOMString enctype, in DOMString content); }
HTMLFormElement
interfaceThe new accept
attribute reflects the form
element's accept
attribute and its addition here merely
address an oversight in DOM2.
The templateElements
attribute contains the list of form
controls associated with this form that form part of repetition templates
that the form itself is not also a part of. It is defined in more detail
in the section on the repetition model.
The validate()
method invokes the validate()
method of all the elements in the form's elements
list whose
interfaces have a validate()
method defined.
HTMLSelectElement
interfaceThe editable
DOM attribute reflects the
editable
content attribute in the same way as the
multiple
DOM attribute reflects the multiple
content attribute.
The selectedOptions
attribute provides a readonly list of
the descendant HTMLOptionElement
nodes that currently have
their selected
attribute set to a true value (a subset of the
controls listed in the options
attribute). The list is
returned live, so changing the options selected (by the user or by script)
will change the list. The order of the list should be consistent with the
order of the options
list.
HTMLOutputElement
interfaceThis interface is added for the new output
element. Its
attributes work analogously to those on other controls. The semantics of
the value
and defaultValue
DOM attributes are
described in the section describing the output
element.
The validity
attribute returns whether the form control is
currently valid. Its value is a bit field giving the errors that currently
apply ot the control, the sum of the relevant ERROR_*
constants defined on the HTMLFormElement
interface. These
have the following meanings:
expdate
fields, and the user has entered SEP02,
then this error code would be used. This code is also used when the
selected file in a file upload control does not have an appropriate MIME
type.
min
attribute is lower than the min.
max
attribute is higher than the max.
maxlength
attribute is
longer than the attribute allows.
pattern
attribute doesn't
match the pattern.
required
attribute set but has no
value.
markValid()
and
markInvalid()
methods.
When the definitions above refer to elements that have an attribute set
on them, they do not refer to elements on which that attribute is defined
not to apply. For example, the ERROR_REQUIRED
code cannot be
set on an <input type="checkbox">
element, even if that
element has the required
attribute set, since
required
doesn't apply to check boxes.
The validate()
method, present on several of the form
control interfaces, causes an formerror
event to be fired on that control,
unless the validity
of the control is zero. Recall that this is automatically done during form
submission.
The markValid()
and
markInvalid()
methods set and reset (respectively) the
ERROR_USER_DEFINED
bit on the validity
attribute. Even attributes that are empty and not required can be marked
invalid like this, and would abort form submission if so marked.
The new pattern
, required
,
autocomplete
, inputmode
, min
,
max
, wrap
, and disabled
attributes
simply reflect the current value of their relevant attribute.
In addition to the reset()
method on the form interface,
this specification introduces the reset()
method on the form
conrol interfaces to reset just the relevant control to its initial value.
The RepetitionElement
interface should be implemented by
all elements.
If the element is a repetition
template, its repetitionType
DOM attribute must
return REPETITION_TEMPLATE
.
Otherwise, if the element is a repetition
block, it must return REPETITION_BLOCK
. Otherwise,
it is a normal element, and that attribute should return
REPETITION_NONE
.
The repetitionIndex
attribute must return the current value of the index of the repetition
template or block. If the element is a normal element, it must return
zero. Setting this attribute must not affect the repeat
content attribute.
The repetitionTemplate
attribute is null unless the element is a repetition block, in which case
it points to the block's template. If the block is an orphan
repetition black then it returns null.
The repetitionBlocks
attribute is null unless the element is a repetition template, in which
case it points to a list of elements (an HTMLCollection
,
although the name of that interface is a misnomer since there is nothing
HTML-specific about it). The list consists of all the repetition
blocks that have this element as their template. The list is live.
The addRepetitionBlock()
,
addRepetitionBlockByIndex()
,
moveRepetitionBlock()
and
removeRepetitionBlock()
methods are defined in the section on the
repetition model.
The template
DOM attribute on the
HTMLInputElement
and HTMLButtonElement
interfaces represents the repetition template that the
template
content attribute refers to. If the content
attribute points to a non-existent element or an element that is not a
repetition template, the DOM attribute returns null. This DOM attribute is
readonly in this version of this specification.
The FormDocument
interface can be obtained using
binding-specific casting methods on the document
object.
The load
method on the FormDocument
interface
returns a Document
interface, and then queues the specified
resource to be loaded into that document. When the document has finished
loading, a load
event fires on the object. If a failure
occurs during loading, an error
event fires instead.
Maybe this should be on the DOMImplementation object.
This method has four arguments:
Implementations may limit which hosts, ports, and schemes can be accessed using this method. For example, it is highly recommended that the SMTP port not be allowed, since otherwise it can be used to relay spam on the behalf of the unwitting user. Similarly, cross-domain scripting restrictions are fully expected to apply.
The load
method is asynchronous, and is guarenteed to not
finish loading the document or signal an error before the running script
either completes or yields to the user (e.g. by calling
window.alert()
). Thus, the following code is guarenteed to
hook in the event handlers before the document has either finished loading
or signalled an error:
var d = document.load('http://example.org/search', 'post', 'application/xml', ''); d.addEventListenerNS('http://www.w3.org/2001/xml-events', 'load', function () { alert('loaded!'); }, false, null); d.addEventListenerNS('http://www.w3.org/2001/xml-events', 'error', function () { alert('loaded!'); }, false, null);
For more control over loading remote documents, see DOM3 Load and Save [DOM3LS].
The CSS working group is expected to develop a language designed, amongst other things, for the advanced styling of form controls. In the meantime, technologies such as [HTC] and [XBL] can be used as guides for what is expected.
UAs, in the absence of such advanced styling information, may render form controls described in this draft as they wish. It is recommended that form controls remain faithful to the look and feel of the system's global user interface, though.
Note that [CSS21] explicitly does not define how CSS applies to form controls.
[CSS3UI] introduces a number of pseudo-classes for form controls. Their relationship to the form controls described in this specification is described here.
disabled
attribute set.
disabled
attribute set.
checked
.
formerror
event fired at them if the form
was submitted.
formerror
event fired at them if the form
was submitted.
required
attribute set.
required
attribute set.
readonly
attribute set.
readonly
attribute set (including password
fields, although technically they should be called "writeonly").
When the definitions above refer to elements that have an attribute set
on them, they do not refer to elements on which that attribute is defined
not to apply. For example, the :read-only
attribute cannot
apply to a <input type="radio">
element, even if that
element has the readonly
attribute set, since
readonly
doesn't apply to radio buttons.
The Forms Extensions Module provides all of the forms features found in HTML 4.0, plus the extensions described above. Specifically, the Forms Extensions Module supports:
Elements | Attributes | Minimal Content Model |
---|---|---|
form | Common, accept (ContentTypes), accept-charset (Charsets), action (URI), method ("get"* | "post"), enctype (ContentType) | (Heading | List | Block - form)* |
input | Common, accept (ContentTypes), accesskey (Character), alt (Text), autocomplete ("true"* | "false"), checked ("checked"), disabled ("disabled"), form (IDREF), help (URI), inputmode (CDATA), maxlength (Number), min (CDATA), max (CDATA), name (CDATA), pattern (CDATA), readonly ("readonly"), required ("required"), size (Number), src (URI), tabindex (Number), template (IDREF), type ("text"* | "password" | "checkbox" | "radio" | "button" | "submit" | "reset" | "add" | "remove" | "file" | "hidden" | "image" | "datetime" | "date" | "expdate" | "time" | "number" | "integer" | "email" | "uri"), value (CDATA), | EMPTY |
select | Common, autocomplete ("true"* | "false"), disabled ("disabled"), editable ("editable"), form (IDREF), help (URI), inputmode (CDATA), multiple ("multiple"), name (CDATA), pattern (CDATA), required ("required"), size (Number), tabindex (Number) | (optgroup | option)* |
optgroup | Common, disabled ("disabled"), label* (Text) | option* |
option | Common, disabled ("disabled"), label (Text), selected ("selected"), value (CDATA) | PCDATA |
textarea | Common, accesskey (Character), autocomplete ("true"* | "false"), cols (Number), disabled ("disabled"), form (IDREF), help (URI), inputmode (CDATA), name (CDATA), readonly ("readonly"), required ("required"), rows (Number), tabindex (Number), wrap ("soft"* | "hard") | PCDATA |
output | Common, form (IDREF), name (CDATA) | PCDATA |
button | Common, accesskey (Character), disabled ("disabled"), form (IDREF), help (URI), name (CDATA), tabindex (Number), template (IDREF), type ("button" | "submit"* | "reset" | "add" | "remove"), value (CDATA) | (PCDATA | Heading | List | Block - Form | Inline - Formctrl)* |
fieldset | Common, disabled ("disabled"), form (IDREF), help (URI), | (PCDATA | legend | Flow)* |
legend | Common, accesskey (Character) | (PCDATA | Inline)* |
label | Common, accesskey (Character), for (IDREF) | (PCDATA | Inline - label)* |
This module defines two content sets:
When this module is used, it adds the Form
content set to
the Block
content set and it adds the Formctrl
content set to the Inline
content set as these are defined in
the Text Module.
All XHTML elements (all elements in the
http://www.w3.org/1999/xhtml
namespace) may have the repeat
attribute specified. Similarly, the
global attribute repeat
in the
http://www.w3.org/1999/xhtml
namespace may be specified on
any non XHTML element.
The form
element may be placed inside XHTML
head
elements when it is empty.
The oninput
attribute is added to all the elements that
have an onchange
attribute in the XHTML Intrinsic Events
module. The onformchange
, onforminput
and
onformerror
attributes are added to all form control elements
(including fieldset
).
The Forms Extensions Module is a superset of the Forms and Basic Forms
modules. These modules may not be used together in a single document type.
Note that the content models in this module differ from those of the
XHTML1 Forms module in some subtle ways (for example, the
select
element may be empty).
The input
element takes a large number of attributes that
do not always apply. The following table summarizes which attributes apply
to which input types.
type | text | password | checkbox | radio | button | submit | reset | add | remove move-up move-down | file | hidden | image | datetime date expdate time | number integer | email uri |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accept | - | - | - | - | - | - | - | - | - | Yes | - | - | - | - | - |
accesskey | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | - | Yes | Yes | Yes | Yes |
alt | - | - | - | - | - | - | - | - | - | - | - | Yes | - | - | - |
autocomplete | Yes | Yes | Yes | Yes | - | - | - | - | - | Yes | - | - | Yes | Yes | Yes |
checked | - | - | Yes | Yes | - | - | - | - | - | - | - | - | - | - | - |
disabled | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
form | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
help | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | - | Yes | Yes | Yes | Yes |
inputmode | Yes | Yes | - | - | - | - | - | - | - | - | - | - | - | - | Yes |
maxlength | Yes | Yes | - | - | - | - | - | - | - | Yes | - | - | - | - | - |
min | - | - | - | - | - | - | - | - | - | - | - | - | Yes | Yes | - |
max | - | - | - | - | - | - | - | - | - | - | - | - | Yes | Yes | - |
name | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
pattern | Yes | Yes | - | - | - | - | - | - | - | - | - | - | - | - | Yes |
readonly | Yes | Yes | - | - | - | - | - | - | - | - | - | - | Yes | Yes | Yes |
required | Yes | Yes | - | Yes | - | - | - | - | - | Yes | - | - | Yes | Yes | Yes |
size | Yes | Yes | - | - | - | - | - | - | - | - | - | - | - | - | - |
src | - | - | - | - | - | - | - | - | - | - | - | Yes | - | - | - |
tabindex | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | - | Yes | Yes | Yes | Yes |
template | - | - | - | - | - | - | - | Yes | - | - | - | - | - | - | - |
value | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | - | Yes | - | Yes | Yes | Yes |
Thanks to Håkon Wium Lie, Maciej Stachowiak, David Hyatt, Peter N Stark, Jason Kersey, Neil Rashbrook, Brendan Eich, Bert Bos, and John Keiser for their substantial comments.
Thanks also to Anne van Kesteren, Michael Daskalov and Rigo Wenning for their comments, and to the #mozilla crew, the #elektra crew, and the #mrt crew for their ideas and support.
Thanks to the XForms working group for unintentionally giving the incentive to develop this specification.