Abstract
This specification defines Web Forms 2.0, an extension to the forms
features found in HTML 4.01's Forms chapter. Web Forms 2.0 applies to both
HTML and XHTML user agents, and provides new strongly-typed input fields,
new attributes for defining constraints, a repeating model for declarative
repeating of form sections, new DOM interfaces, new DOM events for
validation and dependency tracking, and XML submission and initialization
of forms. This specification also standardises and codifies existing
practice in areas that have not been previously documented.
HTML4, XHTML1.1, and the DOM are thus extended in a manner that has a
clear migration path from existing HTML forms, leveraging the knowledge
authors have built up with their experience with HTML so far.
Status of this document
This document is the result of a loose collaboration between interested
parties in the context of the Web
Hypertext Application Technology Working Group.
This is the first call-for-comments draft of Web Forms 2.0. If you wish
to make comments regarding this document, please send them to whatwg@whatwg.org. All feedback is
welcome. 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".
Experimental implementations of this document are encouraged. Unless
large problems are discovered, future changes to this specification will
be minor.
This draft may contain namespaces that use the uuid: URI
scheme. These are temporary and will be changed before this specification
is ready to be implemented in consumer products.
To find the latest version of this working draft, please follow the
"Latest version" link above.
Table of contents
1. Introduction
This is an update to the forms features found in HTML 4.01's Forms chapter,
which are informally referred to as Web Forms 1.0.
Authors have long requested changes to HTML4 to support some of their
more common needs. For example, take this extract from a
recent post written by an anonymous poster on the popular topic-driven
Slashdot forum:
There are three things that need adjustments to get decent forms in HTML.
First, have the option of not redrawing the page upon submission. [...]
Second, have a "grid" widget that allows spreadsheet-like data entry
grids.
Third, have validation options such as <input type="text" name="foo"
format="number" decimals=2> or perhaps <input type="number"
name="foo" decimals=2>
This post is typical of the kind of comments made by Web authors.
Requirements from such comments in mailing lists and other discussions
have been examined, and from these sources a set of requirements and
design goals were derived:
- Backwards compatibility (where possible).
- Ease of authoring for authors with limited knowledge about XML, data
models, etc, but familiar with commonly used languages such as HTML and
ECMAScript.
- Basic data typing, providing new controls for commonly used types so
that authors do not need to repeatedly design complicated widgets such as
calendars.
- Simpler validation on the client side (while recognizing that server
side validation will still be required), with declarative solutions for
the common case, but strong DOM support so that less common cases can
easily be handled using scripting.
- Dynamically adding more fields (repeating structures) on the client
side without scripting.
- XML submission (although not necessarily structured XML submission).
- The ability to initialize forms from external data sources, so that
authors do not have to dynamically rewrite the form content itself to
prefill forms, but can instead use static pages with scripts that
dynamically generate only the data part.
- Few dependencies: this specification should stand alone and not
require support for other technologies such as XPath, XMLSchema, or XML
Events, as these are not implemented in typical Web browsers and
requiring them would significantly delay the time required to deploy
browsers supporting this specification.
- This specification should be implementable in full on devices with
limited resources.
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.
1.1. Relationship to HTML
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 need.
1.2. Relationship to
XHTML
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.
1.3. Relationship to
XForms
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. Unfortunately, due to its dependencies on technologies not
widely supported by Web browsers, it has not been widely implemented by
those browsers itself. This specification aims to simplify the task of
transforming XForms 1.0 systems into documents that can be rendered on
every day Web browsers.
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:
- The separation of the instance data model, data typing, field
interdependencies, and submission information from the content model and
interface elements.
- The ability to create arbitrary XML fragments to be filled in before
submission.
- The ability to edit local XML files directly. (While technically not
defined by the XForms 1.0 specification, UAs have generally implemented
such a feature since it is easy to extend the XForms model in that way.)
- Compound data type definitions (schemas).
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.
1.4. Relationship to
XForms Basic
This specification is unrelated to the XForms Basic profile.
A previous version of this draft was called "XForms Basic".
This name has been changed so as to avoid confusion with the similarly
named draft from the W3C.
1.5. Missing features
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:
- Digital signatures for submissions. This is currently not covered by
this specification due to patent concerns. However, it would still be
considered for future inclusion if suggestions of how to support it
without infringing on known patents were provided.
- DOM interfaces for the creation of new controls that are still able to
interact with form submission. This need will be addressed in a separate
specification.
- Elements or properties to create a "tabbed" or "wizard" interface.
This need will be addressed in a separate specification.
- A rich text editing or HTML editing control. This need may be
addressed in a future specification.
- A grid or spreadsheet editing control. This need may addressed in a
future version of this specification.
- A declarative way of specifying that one list should filter the view
of a second list. Again, however, this need may addressed in a future
version of this specification.
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 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 requirements of those specifications to claim compliance to this one.
Implementations may optionally implement only one of HTML4 and XHTML1.1.
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. Other aspects of this
specification that are defined in terms of an events model must still act
as if events were supported.
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.
Documents that use the new features described in this specification
using HTML over HTTP must be served as text/html and must use
the following DOCTYPE: <!DOCTYPE html PUBLIC "-//WHATWG//NONSGML
HTML5//EN">. The DOCTYPE will change before
this specification is finalised.
Documents that use the new features described in this specification
using XHTML or other XML languages over HTTP must be served using an XML
MIME type such as application/xml or
application/xhtml+xml and must not be served as
text/html. [RFC3023] Documents
served in this way may contain a DOCTYPE if desired, but this
is not required.
1.7. Terminology
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:
...it is possible that authors would prefer to declare the page's forms
in advance, in the head element of XHTML documents (this
does not apply to HTML documents).
Unless otherwise stated, XML elements defined in this specification are
elements in the http://www.w3.org/1999/xhtml namespace, and
attributes defined in this specification have no namespace. This does not
apply to HTML as HTML does not support namespaces.
2. Extensions to form
control elements
HTML input elements use the type attribute to
specify the data type. In [HTML4], the types (as
seen by the server) are as follows:
text
- A free-form text input, nominally free of line breaks.
password
- A free-form text input for sensitive information, nominally free of
line breaks.
checkbox
- A set of zero or more values from a predefined list (in the limiting
case of the list only containing one value, this is equivalent to a
boolean).
radio
- An enumerated value.
submit
- An enumerated value, with the extra semantic that it must be the last
value selected and initiates form submission.
file
- An arbitrary file with a MIME type and optionally a file name.
image
- A coordinate, relative to a particular image's size, with the extra
semantic that it must be the last value selected and initiates form
submission.
hidden
- An arbitrary string that is not normally displayed to the user.
In addition, HTML also provides a few alternate elements that convey
typing semantics similar to the above types, but use different content
models:
select
- An enumerated value, much like the
radio type.
select multiple
- A set of zero or more values from a predefined list, much like the
checkbox type.
textarea
- A free-form text input, nominally with no line break restrictions.
button
- An enumerated value, with the extra semantic that it must be the last
value selected and initiates form submission, much like the
submit 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.
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).
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.)
Similarly, form elements in XHTML may now be nested (this
does not apply to HTML). 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
a td, th, or block-level element other than
div.
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 left unchecked (which differs from the behavior described in
[RFC1866], but more accurately represents
common implementation and author needs).
2.1. Extensions to the
input element
Several 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 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.
datetime
- A date and time (year, month, day, hour, minute, second, fractions of
a second) encoded according to [ISO8601] with
the time zone set to UTC: four or more digits (0 to 9) representing the
year, a dash (U+002D), two digits for the month, a dash, two digits for
the day, a literal "T", two digits for the hour, a colon (U+003A), two
digits for the minute, a colon, two digits for the second, a period
(U+002E), one or more digits for the fraction of a second, a literal "Z".
All the numbers must be in base ten and zero-padded if necessary. e.g.:
1995-12-31T23:59:59.99Z or, representing the time 10
milliseconds later, 1996-01-01T00:00:00.0Z. The
step 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
timezone.
local-datetime
- A date and time (year, month, day, hour, minute, second, fractions of
a second) encoded according to [ISO8601], with
no time zone information: four or more digits (0 to 9) representing the
year, a dash (U+002D), two digits for the month, a dash, two digits for
the day, a literal "T", two digits for the hour, a colon (U+003A), two
digits for the minute, a colon, two digits for the second, a period
(U+002E), one or more digits for the fraction of a second. All the
numbers must be in base ten and zero-padded if necessary. e.g.:
1995-12-31T23:59:59.99 or, representing the time 10
milliseconds later, 1996-01-01T00:00:00.0. The
step attribute specifies the precision in
seconds, defaulting to 60 (one minute).
date
- A date (year, month, day) encoded according to [ISO8601]: four or more digits (0 to 9)
representing the year, a dash (U+002D), two digits for the month, a dash,
two digits for the day. All the numbers must be in base ten and zero
padded if necessary. e.g.: 1995-12-31. The
step attribute specifies the precision in days,
defaulting to 1. User agents are expected to show an appropriate widget,
such as a calendar.
month
- A date consisting of a year and a month encoded according to [ISO8601]: four or more digits (0 to 9)
representing the year, a dash (U+002D), two digits for the month,
zero-padded if necessary. All the numbers must be in base ten. e.g.:
1995-12. The
step attribute
specifies the precision in months, defaulting to 1. This type is used
most frequently for credit card expiry dates.
week
- A date consisting of a year and a week number encoded according to [ISO8601]: four or more digits (0 to 9)
representing the year, a dash (U+002D), a literal "W", two digits for the
week, zero-padded if necessary. All the numbers must be in base ten.
e.g.: 1995-W52. The
step
attribute specifies the precision in weeks, defaulting to 1. This type is
used most frequently for dates in European industry.
time
- A time (hour, minute, seconds, fractional seconds) encoded according
to [ISO8601] with no time zone: two digits
(0-9) for the hour, a colon (U+003A), two digits for the minute, a colon,
two digits for the second, a period (U+002E), one or more digits for the
fraction of a second. All the numbers must be in base ten and zero-padded
if necessary. e.g.: 23:59:00.0 or
00:00:00.0000. The
step
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 field 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.
number
-
A number. The step attribute
specifies the precision, defaulting to 1.
Numbers must be submitted as a significand followed by an optional
exponent. A significand is an optional minus sign (U+002D, "-"), an
integer, and optionally a decimal point (U+002E, ".") and an integer
representing the fractional part. An 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 base to get the
resulting number. Integers are one or more decimal digits. If the
exponent part is omitted it 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 required by some other
floating point syntaxes.
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 omitted). 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.
range
- Same as
number, but indicates that
the exact value is not important, letting UAs optimise their UI for
usability. For instance, visual UAs may use a track bar control. The
step, min, and max
attributes still apply. For this type, step defaults to 1, min defaults to 0, and max defaults to 100.
email
- An e-mail address, based on the definitions in [RFC2822] (specifically the
addr-spec token, defined in RFC2822 section 3.4.1, excluding
the CFWS subtoken everywhere and 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.)
uri
- A URI, as defined by [RFC2396] (the
absoluteURI token, defined in RFC2396 section 3). UAs could,
for example, offer the user URIs from his bookmarks. (See below for notes on IDN.)
The email and uri fields may contain IDN domains. [RFC3490] These should be sent in their original
character set, not IDNA-encoded. (Authors can use the pattern
pattern="[\x00-\x7F]+" to
indicate that only ASCII-based domain names must be allowed.)
By default, all of these new types, just like the types from HTML4, must
have no value selected, unless a default value is provided using the
value attribute.
Empty fields (those with no value) do not need to match their type.
(Although if they are required fields, they will
stop submission for that reason anyway.)
On the other hand, fields that are not successful (such as disabled controls) do not take
part in submission, and therefore are simply not checked for validity.
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) { // ISO8601 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>
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.
2.1.1. Ranges
To limit the range of values allowed by the above types, two new
attributes are introduced, which apply to the date-related, time-related,
numeric, and file upload types:
min
- Gives the minimum value (inclusive) of the field, in the format
specified for the relevant type. Values for the field less than the
minimum value are out of range (
ERROR_RANGE_UNDERFLOW). 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.
max
- Gives the maximum value (inclusive) of the field, in the format
specified for the relevant type. Values for the field greater than the
maximum value are out of range (
ERROR_RANGE_OVERFLOW). 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 fields, the values indicate the allowed
range. For file upload fields, the values indicate the allowed number of
files.
The ERROR_TYPE_MISMATCH
code is used for fields whose values do not match their types, and the
ERROR_RANGE_UNDERFLOW and
ERROR_RANGE_OVERFLOW codes
are used for fields whose values are outside the allowed range.
A field with a max less than its
min can never be satisfied and thus would
block a form from being submitted. This is 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, having all the fields present and
with the right number of digits, with the right separating punctuation.
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.
2.1.2. Precision
Another attribute, step, is introduced
to control 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
zero.
For time controls, the value is in seconds, although it may be a
fractional number as well to allow fractional times. The format is the number format described above, except that the value
must be greater than zero. The default value for datetime, local-datetime 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">
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 is in days, weeks, or months, for the
date, week, and month
types respectively. The format is an 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 these control types is 1.
The following control would only allow sundays (starting from 1900) to
be picked:
<input type="date" min="1900-01-07" step="7" name="sunday">
For numeric controls (number and
range), the format is the number format described above, except that the value
must be greater than zero. The default value 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, ...
In addition, for any of the types, the literal value any may be used. This keyword
indicates that any value may be used (within the bounds of other
restrictions placed on the field).
The following control would allow any floating point number:
<input type="number" step="any" name="n">
The ERROR_STEP_MISMATCH
code is used for fields whose values are not one of the values allowed by
the step attribute. However, UAs may
silently round the number to the nearest allowed value instead of
reporting a 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]
2.2. The output element
The 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
onformoutput 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 is initially set to the empty
string. If an output element is added
to the document at parse time, its defaultValue DOM attribute
is 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 returns the empty
string.) This is suboptimal. Any better solutions for
how to determine the initial value?
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 fields. Changing either field
updates an output element containing
the product of both fields.
<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. It emphasises a part of
the number.
Whenever the value attribute changes (whether directly or
because the DOM under the element was mutated), a change
event is fired on the output element.
The onchange attribute can therefore be used with this
element, in the same way as for other form controls.
2.3. Extensions to the
select element
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 initial
option element of a single-select select element
with no otherwise-selected items.
2.4. Extensions to the
textarea element
The 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
- This is the default value. The text is submitted without line breaks
other than explicitly entered line breaks. (In other words, the submitted
text is exactly as found in the DOM.)
hard
- The text is submitted with explicit line breaks, and in addition, line
breaks added to wrap the text at the width given by the
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.
The maxlength attribute applies to
textarea controls.
2.5. Extensions to file upload
controls
File upload controls (input elements of type file) are not successful if the user enters a value that
specifies non-existent files. There is no error code for this situation
because that would open the way for some privacy or security leaks. It is
recommended that user agents report problems of this nature to the user.
The min and max attributes apply to file upload controls and
specify (as positive 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
implementatios in early 2004). The ERROR_RANGE_UNDERFLOW and ERROR_RANGE_OVERFLOW codes are used
to indicate when fields do not have the specified number of files
selected.
The accept attribute may be used to
specify a comma-separated list of content types that a server processing
the form will handle correctly. This attribute was specified in [HTML4]. In this specification, this attribute is
extended as follows:
- MIME types may have a subtype of
*, 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.
- UAs should use the list of acceptable types in constructing a filter
for a file picker, if one is provided to the user.
- If the UA wishes to let the user create the file prior to upload, it
should use the
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.
- The
ERROR_TYPE_MISMATCH
code 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 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 (but
should not allow users to override the type merely to let submission
continue, as that would defeat the point of having a restriction in the
first place).
- If an
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. The two attributes don't "stack".)
- The
maxlength attribute applies
to file upload controls.
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.
2.6. Extensions to the
form element
The 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 (or the specified base URI, if any).
To support incremental updates of forms, a new attribute is introduced
on the form element: replace. This attribute takes two values:
- document
- The default value. The entire document (as specified by the
target attribute when the document uses frames or windows)
is replaced by the return value.
- values
- The body returned from the server is treated as a new data file for
prefilling the form.
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 this specification's
document is equivalent to the XForms all, 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.
2.7. Extensions to the
submit buttons
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) submits the form, 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 are allowed on submit buttons: action,
method, enctype, replace, and target.
If a submit button is activated, then the submission uses the values as
given by the button that caused the activation, with missing attributes
having their values taken from the equivalent attributes on the relevant
form element, if any.
2.8. Extensions to existing
attributes
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.
disabled
-
The 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.
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 is disabled if it has its
disabled attribute set, or if any
of its ancestor fieldset elements have their
disabled attribute set.
maxlength
-
This attribute applies to text,
password, uri, email
and file input types,
and textarea elements. In particular, it does not apply to
the date-related, time-related, and numeric field 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 characters. For details on counting string
lengths, see [CHARMOD].
Authors are encouraged to only use maxlength on uri and email fields if 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.
When specified on a file upload control, it specifies the maximum size
in bytes of each file (not the maximum size of the sum of all the
files).
The ERROR_TOO_LONG code is
used when this attribute is specified on a text, password, uri, email
or textarea control and the control has more than the
specified number of characters, or when it is specifies on a file control and at least one of the selected
files is longer than the specified number of bytes.
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 empty (unless, of
course, it is a required field,
in which case it can never be valid).
name
- Some names (all starting with the string "
Ecom_") in this
version of HTML forms have predefined meanings, allowing UAs to fill in
the form fields automatically. These names, and their semantics, are
described in [RFC3106].
readonly
- This attribute applies only to
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, 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 in this specification retain the same
semantics as in [HTML4].
2.9. The pattern attribute
For the text, password, email, and uri types of the input
element,
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], except that the
pattern attribute implies a
^ at the start of the pattern and a $ at the end
(so the pattern must match the entire value, not just any subset). If the
attribute is present but empty, it only matches no value (which is
effectively the opposite of required).
If the attribute is omitted then
the control has no pattern restriction.
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 [\x000000-\x10FFFF]* or
[\s\S]* or some equivalent should be used instead, since the
dot character in JavaScript regular expressions does not include newlines.
In the case of the email and uri types, 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, an ERROR_TYPE_MISMATCH error occurs;
when the value doesn't match the pattern, an ERROR_PATTERN_MISMATCH error
occurs.
Empty fields (those with no value) do not need to match their pattern.
(Although if they are required fields, they will
stop submission for that reason anyway.)
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="The expected format is: a digit followed by three uppercase letters."/>
</label>
...could cause the UA to display an alert such as:
The text you have entered does not match the required pattern.
The expected format is: a digit followed by three uppercase letters.
Would a separate attribute be better? Like,
pattern-hint?
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 entering the field. 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.
2.10. The required attribute
Form 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, and
select, fieldset, 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.
The ERROR_REQUIRED code is
used for form controls marked as required that do not have values.
For check boxes, the required
attribute shall only be satisfied when the checkbox is checked.
For radio buttons, the required
attribute shall only be satisfied when exactly one of the radio buttons in
that radio group is checked.
Here is a form fragment showing one required field and one optional
field. A user agent would not allow the user to submit the form until the
"name" field was filled in.
<ul>
<li>Name: <input type="text" name="name" required="required" /></li>
<li>Comment: <input type="text" name="comment" /></li>
</ul>
Any non-empty value satisfies the required condition, including a simple
whitespace character.
All 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, to the empty string, or to an ID that identifies an
element that is not an HTML form element, disassociates the
form control from its form, leaving it unassociated with any
form.
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, 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 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]). (That is, the exact behaviour is
undefined, but must be the same as if the getElementById()
method was used.)
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>
The autocomplete attribute
applies to the text, password, select,
textarea, date-replated, time-related, numeric,
email, and uri controls. The
attribute takes two values, on and off. The
default, when the attribute is not specified, is
on.
The on 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. The off value means that the UA must not remember that field's
value.
A UA may allow the user to disable support for this attribute. Support
must 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.
Banks frequently do not want UAs to pre-fill login information:
<p>Account: <input type="text" name="ac" autocomplete="off" /></p>
<p>PIN: <input type="text" name="pin" autocomplete="off" /></p>
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.
2.13. The
autofocus attribute
Any 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 if the control is not
disabled, then the UA should focus
the control, as if the control's focus() method was invoked.
(When multiple elements are simultaneously inserted into the document,
they must all perform this, in document order.)
This implies that during document load, the last form control with this
attribute set is the one that should have focus once the document is
loaded.
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 is true
when the 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 sets the content attribute to the value autofocus.
Setting the DOM attribute to false removes the content attribute.
Authors should only mark one (non-disabled) control per document with
the autofocus attribute.
In the following snippet, the text field would be focussed 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>
Focussing the control does not imply that the UA must focus
the browser window if it has lost focus.
The inputmode attribute applies
to the input element when it has a type
attribute of text, password, email, or uri,
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].
2.15. The help
attribute
Any 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.
2.16. Handling unexpected
elements and values
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:
- For parsing errors in HTML
- 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.)
- For non-empty
form elements in head elements
in XHTML
- Typically 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.)
- For non-empty
input elements
- By default, the form control must replace the contents of the element
in the rendering with the form control widget. Using CSS3 Generated
Content [CSS3CONTENT] or XBL [XBL], however, it is possible for the author to
override this behaviour.
- For
output elements containing
elements in the DOM
- The
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.
- For
textarea elements containing tags in HTML
- The tags should be parsed as character data, but entities and comments
should be recognised and handled correctly.
- For
textarea elements containing elements in the DOM
- The
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.
- For
select elements containing nodes other than
option and optgroup elements, and for
optgroup elements containing nodes other than
option elements
- Only the
option and optgroup elements take
part in the select semantics. Unless otherwise forced to
appear by a stylesheet, other child nodes are never visible.
- For
option elements containing nodes other than text
nodes
- The value of the control, if not specified explicitly, is initialized
using the
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.
- For
option and optgroup elements that are
not inside select elements
- The elements should be treated much like
span elements as
far as rendering goes.
- For attributes that contain invalid values
- 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.
- For
value attributes that are invalid according to the
type attribute
- The 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 be empty.
- For
value attributes that are invalid according to the
min, max,
step, etc, attributes
- The control must be set to that value. The form will not submit with
that value, though.
- For labels pointing (via
for) to elements that
are not form controls
- The 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 labels with no
for) attributes and
containing more than one form control
- The
control DOM attribute must
return, and activating the label must transfer focus to, the first
control in a depth-first search of the label's children.
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.
3.1. Introduction for
authors
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 PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Sample Order Form</title>
</head>
<body>
<table>
<tr>
<th>Product</th>
<th>Quantity</th>
</tr>
<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>
</table>
<p><button type="submit">Submit</button></p>
</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 type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
</tr>
The template now has a unique identifier ("order"), and that identifier
is used to indicate where the row index should be substituted in. When a
template is replicated, all the attributes containing the template's id
between square bracket characters ([id]) have that
ID (and the brackets) replaced by a unique index.
In order to distinguish this row from a normal row, however, something
needs to be added to the template to mark it as being a template. This is
done using a repeat
attribute:
<tr id="order" repeat="template">
<td><input type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
</tr>
To prevent an attribute from being processed in this way,
put a non-breaking zero-width space character ()
at the start of the attribute. When the template is cloned, that character
will be removed, but any other text in the attribute will be left alone.
This could be useful if you have no control over the rest of the contents
in the attribute, e.g. if it is user configurable text.
If we replace the table with that markup:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Sample Order Form</title>
</head>
<body>
<table>
<tr>
<th>Product</th>
<th>Quantity</th>
</tr>
<tr id="order" repeat="template">
<td><input type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
</tr>
</table>
<p><button type="submit">Submit</button></p>
</body>
</html>
...then nothing but the header will appear! This is because templates
are not rendered. Templates have to be repeated.
This is done with the repeat-start attribute:
...
<tr id="order" repeat="template" repeat-start="3">
<td><input type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
</tr>
</table>
This is now identical to the original example (three rows with empty
fields will appear). It still isn't dynamic — there is no way for
the user to add more rows.
This can be solved by adding an add
button. The add button type adds a copy of
a template when the user presses the
button.
There are two ways to use add buttons.
The first is by explicitly specifying which template should be replicated:
<p><button type="add" template="order">Add Row</button></p>
The template is specified using a template attribute on the button
type="add" or input type="add" elements. In the
template attribute, you put the ID of
the template you want the button to affect.
When such a button is pressed, the template is replicated, and the
resulting block is inserted just after the last block that is associated
with the template. For example, there are three rows in the example above,
so if the user pressed that button, the new block would be inserted just
after the third one.
The second way is by including an add
button inside the template, so that when the template is replicated, the
button is replicated into the resulting block. When such a button is
pressed, the template is replicated, and inserted immediately before the
block in which the button is found. For example, if there were add buttons in the rows of the example above, and
someone pressed the button in the second row, a row would be inserted
between the first row and the second row.
For this example we will only do it the first way:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Sample Order Form</title>
</head>
<body>
<table>
<tr>
<th>Product</th>
<th>Quantity</th>
</tr>
<tr id="order" repeat="template" repeat-start="3">
<td><input type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
</tr>
</table>
<p><button type="add" template="order">Add Row</button></p>
<p><button type="submit">Submit</button></p>
</body>
</html>
Now the user can add more rows, but he cannot remove them. Removing rows
is done via the remove button type.
When a user presses such a button, the row in which the button is kept is
removed from the document.
<button type="remove">Remove This Row</button>
This is added to the template so that it appears on every row:
<tr id="order" repeat="template" repeat-start="3">
<td><input type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
<td><button type="remove">Remove This Row</button></td>
</tr>
The final result looks like this:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Sample Order Form</title>
</head>
<body>
<table>
<tr>
<th>Product</th>
<th>Quantity</th>
</tr>
<tr id="order" repeat="template" repeat-start="3">
<td><input type="text" name="row[order].product" value=""></td>
<td><input type="text" name="row[order].quantity" value="1"></td>
<td><button type="remove">Remove This Row</button></td>
</tr>
</table>
<p><button type="add" template="order">Add Row</button></p>
<p><button type="submit">Submit</button></p>
</body>
</html>
If the user pressed "Add" once, removed the middle two rows, typed in
some garbage in the two "product" text fields, and pressed "Submit", the
user agent would submit the following name-value pairs:
row0.product=some
row0.quantity=1
row3.product=garbage
row3.quantity=1
Further examples are given in the examples
section below.
The repetition model supports more than just the cases given above; for
instance, there are move-up and
move-down buttons that can be
inserted inside templates much like the remove button but for moving rows up and down.
Repetition templates can also be nested. The concept of hierarchy is
expected to be represented in the names, as it is today in hand-rolled
repeating forms, as in:
order0.name
order0.quantity
order0.comment0.text
order0.comment1.text
order1.name
order1.quantity
order1.comment0.text
That way the submission can remain compatible with the long-established
multipart/form-data, yet not lose the structure of the data.
The naming schemes used above are arbitrary. Any naming
scheme could be used, at the convenience of the author.
3.1.1. What the repetition
model can't do
This specification does not address the ability to select a
repetition block to move it up or down without using buttons directly
associated with the current block.
3.2. Definitions
This section makes a number of references 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, several new global
attributes are introduced: repeat,
repeat-start, repeat-min, and repeat-max. When placed on elements in the
http://www.w3.org/1999/xhtml namespace, they must be
namespace-free attributes, and when placed on other elements, they must be
attributes in the http://www.w3.org/1999/xhtml namespace.
The most important one is the repeat
attribute. The effect of this attribute depends on its value, which can be
either the literal string "template",
or an integer.
3.2.1. Repetition templates
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 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. The initial value of a
template's index is always 0. The index is used to ensure that when
cloning templates, the new block has a unique ID. The template's index
does not appear in the markup. (It does, however, appear in the DOM, as
the repetitionIndex
attribute.)
Unrecognized values must be ignored.
<div repeat="template"/> <!-- A template. -->
<div repeat="template +1 3"/> <!-- Not a template. -->
<div repeat=" template"/> <!-- Not a template (leading whitespace). -->
Authors may use "title" attributes on templates (if they are in the HTML
namespace) to describe their purpose. Assistive technologies may then use
these descriptions to help users. (Note, though, that such titles would
get propagated to the repetition blocks too.)
3.2.2. Repetition blocks
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 attribute's
value equal to an integer (an optional leading '-' character followed by
one or more decimal digits), is a repetition
block.
Repetition blocks should only occur as preceding siblings of repetition
templates. If an element is declared as a repetition block but does not
have a following 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. The index's
initial value is the value of the repeat attribute.
<div>
<div repeat="0"/> <!-- A simple repetition block, index 0. -->
<div repeat="-5"/> <!-- Another, index -5 -->
<div repeat="2"/> <!-- A simple repetition block, index 2. -->
<div repeat="nothing"/> <!-- Just a normal element. -->
<div repeat=" 3"/> <!-- Another normal element (leading whitespace). -->
<div repeat="template"/> <!-- The template for the last few elements. -->
<div repeat="1"/> <!-- Orphan repetition block, index 1. -->
</div>
<div repeat="0"/> <!-- Orphan repetition block, index 0. -->
Several new button types are introduced to support the repetition model.
These values are valid types for both the button element and
the input element.
add
- Adds a new repetition block.
remove
- Removes the nearest ancestor repetition block.
move-up
- Moves the nearest ancestor repetition block up one.
move-down
- Moves the nearest ancestor repetition block down one.
These control types can never be successful.
When these new types are used with input buttons, the
value attribute shall, if present, provide the button caption
(although of course this may be further overriden by the stylesheet). When
the value attribute is absent, the buttons should be given
locale-dependent default labels, in the same way as submit and reset buttons.
Invoking these buttons generates events (such as click), as
specified by the DOM specifications. The default action for these events
is to act as described below. However, if the event is cancelled, then the
default action will not occur.
In addition, to support the add type, a
new attribute is introduced to the button and
input elements: template.
template
- Specifies the repetition template to use.
These new types and attributes are described in more detail in the next
few sections.
The repeat-min attribute
specifies the number of repetition blocks that the remove button type will ensure are present each
time a block is removed. Its value must be a positive integer (one or more
digits 0-9 interpreted as a base ten number). If the attribute is omitted
or if it has an invalid value then it is treated as if its value was zero.
The repeat-max attribute
specifies the maximum number of repetition blocks that the add button type can cause to be present. Its value
must be a positive integer (one or more digits 0-9 interpreted as a base
ten number). If the attribute is omitted or if it has an invalid value
then there is no limit.
These two attributes must not be present on elements that do not have a
repeat attribute with the value set to
template.
3.5. Event interface for
repetition events
The repetition model includes several events. These use the following
interface to store their context information.
/* Similar to the UIEvent interface */
members of RepetitionEvent (which inherits from Event) are:
readonly attribute RepetitionElement element;
