search
element with form functionality — Last Updated 1 December 2021Some IDL attributes are defined to reflect a particular content attribute. This means that on getting, the IDL attribute returns the current value of the content attribute, and on setting, the IDL attribute changes the value of the content attribute to the given value.
In general, on getting, if the content attribute is not present, the IDL attribute must act as if the content attribute's value is the empty string; and on setting, if the content attribute is not present, it must first be added.
If a reflecting IDL attribute is a USVString
attribute
whose content attribute is defined to contain a URL, then on getting, if the
content attribute is absent, the IDL attribute must return the empty string. Otherwise, the IDL
attribute must parse the value of the content attribute relative
to the element's node document and if that is successful, return the resulting
URL string. If parsing fails, then the value of the content attribute must be returned
instead, converted to a USVString
. On setting, the content attribute must be set to the
specified new value.
If a reflecting IDL attribute is a DOMString
attribute
whose content attribute is an enumerated attribute, and the IDL attribute is
limited to only known values, then, on getting, the IDL attribute must return the
keyword value associated with the state the attribute is in, if any, or the empty string if the
attribute is in a state that has no associated keyword value or if the attribute is not in a
defined state (e.g. the attribute is missing and there is no missing value default). If there are multiple keyword values for the state, then
return the conforming one. If there are multiple conforming keyword values, then one will be
designated the canonical keyword; choose that one. On setting, the content attribute
must be set to the specified new value.
If a reflecting IDL attribute is a nullable DOMString
attribute whose content attribute is an enumerated attribute, then, on getting, if
the corresponding content attribute is in its missing value default state then the IDL
attribute must return null, otherwise, the IDL attribute must return the keyword value associated
with the state the attribute is in. If there are multiple keyword values for the state, then
return the conforming one. If there are multiple conforming keyword values, then one will be
designated the canonical keyword; choose that one. On setting, if the new value is
null, the content attribute must be removed, and otherwise, the content attribute must be set to
the specified new value.
If a reflecting IDL attribute is a DOMString
or USVString
attribute but doesn't fall into any of the above
categories, then the getting and setting must be done in a transparent, case-preserving manner.
If a reflecting IDL attribute is a boolean
attribute, then on
getting the IDL attribute must return true if the content attribute is set, and false if it is
absent. On setting, the content attribute must be removed if the IDL attribute is set to false,
and must be set to the empty string if the IDL attribute is set to true. (This corresponds to the
rules for boolean content attributes.)
If a reflecting IDL attribute has a signed integer type (long
)
then, on getting, the content attribute must be parsed according to the rules for parsing signed integers, and if that is successful, and the
value is in the range of the IDL attribute's type, the resulting value must be returned. If, on
the other hand, it fails or returns an out of range value, or if the attribute is absent, then the
default value must be returned instead, or 0 if there is no default value. On setting, the given
value must be converted to the shortest possible string representing the number as a valid
integer and then that string must be used as the new content attribute value.
If a reflecting IDL attribute has a signed integer type (long
)
that is limited to only non-negative numbers then, on getting, the content attribute
must be parsed according to the rules for parsing non-negative integers, and if that
is successful, and the value is in the range of the IDL attribute's type, the resulting value must
be returned. If, on the other hand, it fails or returns an out of range value, or if the attribute
is absent, the default value must be returned instead, or −1 if there is no default value.
On setting, if the value is negative, the user agent must throw an
"IndexSizeError
" DOMException
. Otherwise, the given value
must be converted to the shortest possible string representing the number as a valid
non-negative integer and then that string must be used as the new content attribute
value.
If a reflecting IDL attribute has an unsigned integer type (unsigned long
) then, on getting, the content attribute must be
parsed according to the rules for parsing non-negative integers, and if that is
successful, and the value is in the range 0 to 2147483647 inclusive, the resulting value must be
returned. If, on the other hand, it fails or returns an out of range value, or if the attribute is
absent, the default value must be returned instead, or 0 if there is no default value. On setting,
first, if the new value is in the range 0 to 2147483647, then let n be the new value,
otherwise let n be the default value, or 0 if there is no default value; then,
n must be converted to the shortest possible string representing the number as a
valid non-negative integer and that string must be used as the new content attribute
value.
If a reflecting IDL attribute has an unsigned integer type (unsigned long
) that is limited to only non-negative numbers
greater than zero, then the behavior is similar to the previous case, but zero is not
allowed. On getting, the content attribute must first be parsed according to the rules for
parsing non-negative integers, and if that is successful, and the value is in the range 1
to 2147483647 inclusive, the resulting value must be returned. If, on the other hand, it fails or
returns an out of range value, or if the attribute is absent, the default value must be returned
instead, or 1 if there is no default value. On setting, if the value is zero, the user agent must
throw an "IndexSizeError
" DOMException
. Otherwise, first,
if the new value is in the range 1 to 2147483647, then let n be the new value,
otherwise let n be the default value, or 1 if there is no default value; then,
n must be converted to the shortest possible string representing the number as a
valid non-negative integer and that string must be used as the new content attribute
value.
If a reflecting IDL attribute has an unsigned integer type (unsigned long
) that is limited to only non-negative numbers
greater than zero with fallback, then the behavior is similar to the previous case, but
disallowed values are converted to the default value. On getting, the content attribute must first
be parsed according to the rules for parsing non-negative integers, and if that is
successful, and the value is in the range 1 to 2147483647 inclusive, the resulting value must be
returned. If, on the other hand, it fails or returns an out of range value, or if the attribute is
absent, the default value must be returned instead. On setting, first, if the new value is in the
range 1 to 2147483647, then let n be the new value, otherwise let n be the
default value; then, n must be converted to the shortest possible string representing
the number as a valid non-negative integer and that string must be used as the new
content attribute value.
If a reflecting IDL attribute has an unsigned integer type (unsigned long
) that is clamped to the range
[min, max], then on getting, the content attribute must first be parsed
according to the rules for parsing non-negative integers, and if that is successful,
and the value is between min and max inclusive, the resulting value must be
returned. If it fails, the default value must be returned. If it succeeds but the value is less
than min, min must be returned. If it succeeds but the value is greater than
max, max must be returned. On setting, it behaves the same as setting a
regular reflected unsigned integer.
If a reflecting IDL attribute has a floating-point number type (double
or unrestricted
double
), then, on getting, the content attribute must be parsed according to the
rules for parsing floating-point number values, and if that is successful, the
resulting value must be returned. If, on the other hand, it fails, or if the attribute is absent,
the default value must be returned instead, or 0.0 if there is no default value. On setting, the
given value must be converted to the best representation of the number as a floating-point
number and then that string must be used as the new content attribute value.
If a reflecting IDL attribute has a floating-point number type (double
or unrestricted
double
) that is limited to numbers greater than zero, then the behavior is
similar to the previous case, but zero and negative values are not allowed. On getting, the
content attribute must be parsed according to the rules for parsing floating-point number
values, and if that is successful and the value is greater than 0.0, the resulting value
must be returned. If, on the other hand, it fails or returns an out of range value, or if the
attribute is absent, the default value must be returned instead, or 0.0 if there is no default
value. On setting, if the value is less than or equal to zero, then the value must be ignored.
Otherwise, the given value must be converted to the best representation of the number as a
floating-point number and then that string must be used as the new content attribute
value.
The values Infinity and Not-a-Number (NaN) values throw an exception on setting, as defined in Web IDL. [WEBIDL]
If a reflecting IDL attribute has the type DOMTokenList
, then on getting it must
return a DOMTokenList
object whose associated element is the element in question and
whose associated attribute's local name is the name of the attribute in question.
The HTMLFormControlsCollection
and HTMLOptionsCollection
interfaces
are collections derived from the
HTMLCollection
interface. The HTMLAllCollection
interface is a collection, but is not so derived.
HTMLAllCollection
interfaceThe HTMLAllCollection
interface is used for the legacy document.all
attribute. It operates similarly to
HTMLCollection
; the main differences are that it allows a staggering variety of
different (ab)uses of its methods to all end up returning something, and that it can be called as
a function as an alternative to property access.
All HTMLAllCollection
objects are rooted at a Document
and have a filter that matches all elements, so the elements represented by the
collection of an HTMLAllCollection
object consist of all the descendant
elements of the root Document
.
Objects that implement the HTMLAllCollection
interface are legacy platform objects with an additional [[Call]] internal
method described in the section below. They also have an
[[IsHTMLDDA]] internal slot.
Objects that implement the HTMLAllCollection
interface have several unusual
behaviors, due of the fact that they have an [[IsHTMLDDA]] internal slot:
The ToBoolean abstract operation in JavaScript returns
false when given objects implementing the HTMLAllCollection
interface.
The Abstract Equality Comparison algorithm,
when given objects implementing the HTMLAllCollection
interface, returns true when
compared to the undefined
and null
values.
(Comparisons using the Strict Equality Comparison
algorithm, and Abstract Equality comparisons to other values such as strings or objects, are
unaffected.)
The typeof
operator in JavaScript returns the string
"undefined"
when applied to objects implementing the
HTMLAllCollection
interface.
These special behaviors are motivated by a desire for compatibility with two classes of legacy
content: one that uses the presence of document.all
as a
way to detect legacy user agents, and one that only supports those legacy user agents and uses
the document.all
object without testing for its presence
first. [JAVASCRIPT]
[Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface HTMLAllCollection {
readonly attribute unsigned long length ;
getter Element (unsigned long index );
getter (HTMLCollection or Element )? namedItem (DOMString name );
(HTMLCollection or Element )? item (optional DOMString nameOrIndex );
// Note: HTMLAllCollection objects have a custom [[Call]] internal method and an [[IsHTMLDDA]] internal slot.
};
The object's supported property indices are as defined for
HTMLCollection
objects.
The supported property names consist of the non-empty values of all the id
attributes of all the elements represented by the
collection, and the non-empty values of all the name
attributes of
all the "all"-named elements represented by the collection, in
tree order, ignoring later duplicates, with the id
of
an element preceding its name
if it contributes both, they differ from
each other, and neither is the duplicate of an earlier entry.
The length
getter steps are to return the number
of nodes represented by the collection.
The indexed property getter must return the result of getting the "all"-indexed element from this given the passed index.
The namedItem(name)
method steps are
to return the result of getting the "all"-named
element(s) from this given name.
The item(nameOrIndex)
method steps
are:
If nameOrIndex was not provided, return null.
Return the result of getting the "all"-indexed or named element(s) from this, given nameOrIndex.
The following elements are "all"-named elements:
a
,
button
,
embed
,
form
,
frame
,
frameset
,
iframe
,
img
,
input
,
map
,
meta
,
object
,
search
,
select
, and
textarea
To get the "all"-indexed element from an
HTMLAllCollection
collection given an index index, return the
indexth element in collection, or null if there is no such
indexth element.
To get the "all"-named element(s) from an
HTMLAllCollection
collection given a name name, perform the
following steps:
If name is the empty string, return null.
Let subCollection be an HTMLCollection
object rooted at the same
Document
as collection, whose filter matches only elements that are
either:
"all"-named elements with a name
attribute equal to
name, or,
elements with an ID equal to name.
If there is exactly one element in subCollection, then return that element.
Otherwise, if subCollection is empty, return null.
Otherwise, return subCollection.
To get the "all"-indexed or named
element(s) from an HTMLAllCollection
collection given
nameOrIndex:
If nameOrIndex, converted to a JavaScript String value, is an array index property name, return the result of getting the "all"-indexed element from collection given the number represented by nameOrIndex.
Return the result of getting the "all"-named element(s) from collection given nameOrIndex.
If argumentsList's size is zero, or if argumentsList[0] is undefined, return null.
Let nameOrIndex be the result of converting argumentsList[0] to a DOMString
.
Let result be the result of getting the "all"-indexed or named element(s)
from this HTMLAllCollection
given nameOrIndex.
Return the result of converting result to an ECMAScript value.
The thisArgument is ignored, and thus code such as Function.prototype.call.call(document.all, null, "x")
will still search for
elements. (document.all.call
does not exist, since document.all
does not inherit from Function.prototype
.)
HTMLFormControlsCollection
interfaceThe HTMLFormControlsCollection
interface is used for
collections of listed
elements in forms.
Support in all current engines.
Support in all current engines.
[Exposed =Window ]
interface HTMLFormControlsCollection : HTMLCollection {
// inherits length and item()
getter (RadioNodeList or Element )? namedItem (DOMString name ); // shadows inherited namedItem()
};
[Exposed =Window ]
interface RadioNodeList : NodeList {
attribute DOMString value ;
};
collection.length
Returns the number of elements in collection.
element = collection.item(index)
element = collection[index]
Returns the item at index index in collection. The items are sorted in tree order.
element = collection.namedItem(name)
HTMLFormControlsCollection/namedItem
Support in all current engines.
radioNodeList = collection.namedItem(name)
element = collection[name]
radioNodeList = collection[name]
Returns the item with ID or name
name from collection.
If there are multiple matching items, then a RadioNodeList
object containing all
those elements is returned.
radioNodeList.value
Returns the value of the first checked radio button represented by radioNodeList.
radioNodeList.value = value
Checks the first first radio button represented by radioNodeList that has value value.
The object's supported property indices are as defined for
HTMLCollection
objects.
The supported property names consist of the non-empty values of all the id
and name
attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id
of an element preceding its name
if it contributes both, they differ from each other, and neither is the
duplicate of an earlier entry.
The namedItem(name)
method
must act according to the following algorithm:
id
attribute or a name
attribute equal to name, then return that node and stop the algorithm.id
attribute or a name
attribute equal
to name, then return null and stop the algorithm.RadioNodeList
object representing a live
view of the HTMLFormControlsCollection
object, further filtered so that the only
nodes in the RadioNodeList
object are those that have either an id
attribute or a name
attribute equal
to name. The nodes in the RadioNodeList
object must be sorted in
tree order.RadioNodeList
object.Members of the RadioNodeList
interface inherited from the NodeList
interface must behave as they would on a NodeList
object.
Support in all current engines.
The value
IDL attribute on the
RadioNodeList
object, on getting, must return the value returned by running the
following steps:
Let element be the first element in tree order
represented by the RadioNodeList
object that is an input
element whose
type
attribute is in the Radio Button state and whose checkedness is true. Otherwise, let it be null.
If element is null, return the empty string.
If element is an element with no value
attribute, return the string "on
".
Otherwise, return the value of element's value
attribute.
On setting, the value
IDL attribute must run the
following steps:
If the new value is the string "on
": let element be the first element in tree order
represented by the RadioNodeList
object that is an input
element whose
type
attribute is in the Radio Button state and whose value
content attribute is either absent, or present and equal to the new value, if any. If no such element exists, then instead let element be null.
Otherwise: let element be the first element in tree order
represented by the RadioNodeList
object that is an input
element whose
type
attribute is in the Radio Button state and whose value
content attribute is present and equal to the new value, if
any. If no such element exists, then instead let element be null.
If element is not null, then set its checkedness to true.
HTMLOptionsCollection
interfaceSupport in all current engines.
The HTMLOptionsCollection
interface is used for collections of option
elements. It is always
rooted on a select
element and has attributes and methods that manipulate that
element's descendants.
[Exposed =Window ]
interface HTMLOptionsCollection : HTMLCollection {
// inherits item(), namedItem()
[CEReactions ] attribute unsigned long length ; // shadows inherited length
[CEReactions ] setter undefined (unsigned long index , HTMLOptionElement ? option );
[CEReactions ] undefined add ((HTMLOptionElement or HTMLOptGroupElement ) element , optional (HTMLElement or long )? before = null );
[CEReactions ] undefined remove (long index );
attribute long selectedIndex ;
};
collection.length
Returns the number of elements in collection.
collection.length = value
When set to a smaller number than the existing length, truncates the number of
option
elements in the container corresponding to collection.
When set to a greater number than the existing length, adds new blank option
elements to the container corresponding to collection.
element = collection.item(index)
element = collection[index]
Returns the item at index index in collection. The items are sorted in tree order.
collection[index] = element
When index is a greater number than the number of items in collection,
adds new blank option
elements in the corresponding container.
When set to null, removes the item at index index from collection.
When set to an option
element, adds or replaces it at index index in
collection.
element = collection.namedItem(name)
element = collection[name]
Returns the item with ID or name
name from collection.
If there are multiple matching items, then the first is returned.
collection.add(element[, before])
Inserts element before the node given by before.
The before argument can be a number, in which case element is inserted before the item with that number, or an element from collection, in which case element is inserted before that element.
If before is omitted, null, or a number out of range, then element will be added at the end of the list.
Throws a "HierarchyRequestError
" DOMException
if
element is an ancestor of the element into which it is to be inserted.
collection.remove(index)
Removes the item with index index from collection.
collection.selectedIndex
Returns the index of the first selected item, if any, or −1 if there is no selected item.
collection.selectedIndex = index
Changes the selection to the option
element at index index in
collection.
The object's supported property indices are as defined for
HTMLCollection
objects.
On getting, the length
attribute must return the number of
nodes represented by the collection.
On setting, the behavior depends on whether the new value is equal to, greater than, or less
than the number of nodes represented by the collection at that time. If the number is
the same, then setting the attribute must do nothing. If the new value is greater, then n new option
elements with no attributes and no child nodes must be
appended to the select
element on which the HTMLOptionsCollection
is
rooted, where n is the difference between the two numbers (new value minus old
value). Mutation events must be fired as if a DocumentFragment
containing the new
option
elements had been inserted. If the new value is lower, then the last n nodes in the collection must be removed from their parent nodes, where n is the difference between the two numbers (old value minus new value).
Setting length
never removes
or adds any optgroup
elements, and never adds new children to existing
optgroup
elements (though it can remove children from them).
The supported property names consist of the non-empty values of all the id
and name
attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id
of an element preceding its name
if it contributes both, they differ from each other, and neither is
the duplicate of an earlier entry.
When the user agent is to set the value of a new indexed property or set the value of an existing indexed property for a given property index index to a new value value, it must run the following algorithm:
If value is null, invoke the steps for the remove
method with index as
the argument, and return.
Let length be the number of nodes represented by the collection.
Let n be index minus length.
If n is greater than zero, then append a DocumentFragment
consisting of n-1 new option
elements with no attributes and
no child nodes to the select
element on which the HTMLOptionsCollection
is rooted.
If n is greater than or equal to zero, append value to the select
element. Otherwise, replace the indexth element in the collection by value.
The add(element, before)
method must act according to the following algorithm:
If element is an ancestor of the select
element on which
the HTMLOptionsCollection
is rooted, then throw a
"HierarchyRequestError
" DOMException
.
If before is an element, but that element isn't a descendant of the
select
element on which the HTMLOptionsCollection
is rooted, then throw
a "NotFoundError
" DOMException
.
If element and before are the same element, then return.
If before is a node, then let reference be that node. Otherwise, if before is an integer, and there is a beforeth node in the collection, let reference be that node. Otherwise, let reference be null.
If reference is not null, let parent be the parent
node of reference. Otherwise, let parent be the
select
element on which the HTMLOptionsCollection
is rooted.
Pre-insert element into parent node before reference.
The remove(index)
method must act
according to the following algorithm:
If the number of nodes represented by the collection is zero, return.
If index is not a number greater than or equal to 0 and less than the number of nodes represented by the collection, return.
Let element be the indexth element in the collection.
Remove element from its parent node.
The selectedIndex
IDL attribute must act
like the identically named attribute on the select
element on which the
HTMLOptionsCollection
is rooted
DOMStringList
interfaceSupport in all current engines.
The DOMStringList
interface is a non-fashionable retro way of representing a list
of strings.
[Exposed =(Window ,Worker )]
interface DOMStringList {
readonly attribute unsigned long length ;
getter DOMString ? item (unsigned long index );
boolean contains (DOMString string );
};
New APIs must use sequence<DOMString>
or
equivalent rather than DOMStringList
.
strings.length
Returns the number of strings in strings.
strings[index]
strings.item(index)
Returns the string with index index from strings.
strings.contains(string)
Returns true if strings contains string, and false otherwise.
Each DOMStringList
object has an associated list.
The DOMStringList
interface supports indexed properties. The
supported property indices are the indices of this's
associated list.
The length
getter steps are to return
this's associated list's size.
The item(index)
method steps are to
return the indexth item in this's associated list, or null if
index plus one is greater than this's associated list's size.
The contains(string)
method steps
are to return true if this's associated list contains string, and false otherwise.