Some 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 DOMString
attribute whose content attribute is defined to contain a
URL, then on getting, the IDL attribute must resolve the value of the content
attribute relative to the element and return the resulting
absolute URL if that was successful, or the empty
string otherwise; and on setting, must set the content attribute to
the specified literal value. If the content attribute is absent, the
IDL attribute must return the default value, if the content
attribute has one, or else the empty string.
If a reflecting IDL attribute is a DOMString
attribute whose content attribute is defined to contain one or more
URLs, then on getting, the IDL attribute
must split the content
attribute on spaces and return the concatenation of resolving each token URL to an
absolute URL relative to the element, with a single
U+0020 SPACE character between each URL, ignoring any tokens that
did not resolve successfully. If the content attribute is absent,
the IDL attribute must return the default value, if the content
attribute has one, or else the empty string. On setting, the IDL
attribute must set the content attribute to the specified literal
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 conforming value associated with the state the attribute is in
(in its canonical case), 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 state (e.g. the attribute is missing and
there is no missing value default); and on setting, the
content attribute must be set to the specified new value.
If a reflecting IDL attribute is a DOMString
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
exception. 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
exception. 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 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 the Web IDL specification. [WEBIDL]
If a reflecting IDL attribute has the type
DOMTokenList
or DOMSettableTokenList
, then
on getting it must return a DOMTokenList
or
DOMSettableTokenList
object (as appropriate) whose
underlying string is the element's corresponding content attribute.
When the object mutates its underlying string, the content attribute
must itself be immediately mutated. When the attribute is absent,
then the string represented by the object is the empty string; when
the object mutates this empty string, the user agent must add the
corresponding content attribute, with its value set to the value it
would have been set to after mutating the empty string. The same
DOMTokenList
or DOMSettableTokenList
object must be returned every time for each attribute.
If an element with no attributes has its element.classList.remove()
method invoked, the underlying string won't be changed, since the
result of removing any token from the empty string is still the
empty string. However, if the element.classList.add()
method is
then invoked, a class
attribute
will be added to the element with the value of the token to be
added.
If a reflecting IDL attribute has the type
HTMLElement
, or an interface that descends from
HTMLElement
, then, on getting, it must run the
following algorithm (stopping at the first point where a value is
returned):
document.getElementById()
method
would find when called on the content attribute's document if it
were passed as its argument the current value of the corresponding
content attribute.On setting, if the given element has an id
attribute, and has the same home
subtree as the element of the attribute being set, and the
given element is the first element in that home subtree
whose ID is the value of that id
attribute, then the content attribute must
be set to the value of that id
attribute. Otherwise, the content attribute must be set to the empty
string.
The HTMLAllCollection
,
HTMLFormControlsCollection
,
HTMLOptionsCollection
,
interfaces are collections derived from the
HTMLCollection
interface.
The HTMLAllCollection
interface is used for generic
collections of elements just like
HTMLCollection
, with the exception that its namedItem()
method
returns an HTMLAllCollection
object when there are
multiple matching elements, and that its item()
method can be used
as a synonym for its namedItem()
method.
It is intended only for the legacy document.all
attribute.
interface HTMLAllCollection : HTMLCollection { // inherits length and item() legacycaller getter object? namedItem(DOMString name); // overrides inherited namedItem() HTMLAllCollection tags(DOMString tagName); };
length
Returns the number of elements in the collection.
item
(index)Returns the item with index index from the collection. The items are sorted in tree order.
item
(name)item
(name)namedItem
(name)namedItem
(name)Returns the item with ID or name name from the collection.
If there are multiple matching items, then an HTMLAllCollection
object containing all those elements is returned.
Only a
, applet
, area
,
embed
, form
, frame
,
frameset
, iframe
, img
, and
object
elements can have a name for the purpose of
this method; their name is given by the value of their name
attribute.
tags
(tagName)Returns a collection that is a filtered view of the current collection, containing only elements with the given tag name.
The object's supported property indices and
supported property names are as defined for
HTMLCollection
objects.
The item(name)
and namedItem(name)
methods must act according to the
following algorithm:
Let collection be an
HTMLAllCollection
object rooted at the same node as
the HTMLAllCollection
object on which the method was
invoked, whose filter matches only elements that already
match the filter of the HTMLAllCollection
object on
which the method was invoked and that are either:
The tags(tagName)
method must return an
HTMLAllCollection
rooted at the same node as the
HTMLAllCollection
object on which the method was
invoked, whose filter matches only HTML elements whose
local name is the tagName argument and that
already match the filter of the HTMLAllCollection
object on which the method was invoked. In HTML
documents, the argument must first be converted to
ASCII lowercase.
The HTMLFormControlsCollection
interface is used for
collections of listed
elements in form
and fieldset
elements.
interface HTMLFormControlsCollection : HTMLCollection { // inherits length and item() legacycaller getter object? namedItem(DOMString name); // overrides inherited namedItem() }; interface RadioNodeList : NodeList { attribute DOMString value; };
length
Returns the number of elements in the collection.
item
(index)Returns the item with index index from the collection. The items are sorted in tree order.
namedItem
(name)namedItem
(name)item
(name)Returns the item with ID or name
name from the collection.
If there are multiple matching items, then a RadioNodeList
object containing all those elements is returned.
Returns the value of the first checked radio button represented by the object.
Can be set, to check the first radio button with the given value represented by the object.
The object's supported property indices are as
defined for HTMLCollection
objects.
The supported property names consist of the values
of all the id
and name
attributes of all the elements
represented by the collection.
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.
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, or if it is an
element with no value
attribute, return the empty string.
Otherwise, return the value of element's
value
attribute.
On setting, the value
IDL attribute must run
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 value
content
attribute is present and equal to the new value, if any. Otherwise,
let it be null.
If element is not null, then set its checkedness to true.
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.
interface HTMLOptionsCollection : HTMLCollection {
// inherits item()
attribute unsigned long length; // overrides inherited length
legacycaller getter object? namedItem(DOMString name); // overrides inherited namedItem()
setter creator void (unsigned long index, HTMLOptionElement? option);
void add((HTMLOptionElement or HTMLOptGroupElement) element, optional (HTMLElement or long)? before = null);
void remove(long index);
attribute long selectedIndex;
};
length
[ = value ]Returns the number of elements in the collection.
When set to a smaller number, truncates the number of option
elements in the corresponding container.
When set to a greater number, adds new blank option
elements to that container.
item
(index)Returns the item with index index from the collection. The items are sorted in tree order.
namedItem
(name)namedItem
(name)item
(name)Returns the item with ID or name
name from the collection.
If there are multiple matching items, then a NodeList
object containing all those elements is returned.
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 the 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.
This method will throw a HierarchyRequestError
exception if element is an ancestor of the
element into which it is to be inserted.
selectedIndex
[ = value ]Returns the index of the first selected item, if any, or −1 if there is no selected item.
Can be set, to change the selection.
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 values
of all the id
and name
attributes of all the elements
represented by the collection.
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.NodeList
object
representing a live view of the
HTMLOptionsCollection
object, further filtered so that
the only nodes in the NodeList
object are those that
have either an id
attribute or a name
attribute equal to name. The nodes in the NodeList
object
must be sorted in tree order.NodeList
object.When the user agent is to set the value of a new 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 abort
these steps.
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
exception.
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
exception.
If element and before are the same element, then return and abort these steps.
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.
Act as if the DOM Core insertBefore()
method was
invoked on the parent node, with element as the first argument and reference as the second argument.
The remove(index)
method must act according to
the following algorithm:
If the number of nodes represented by the collection is zero, abort these steps.
If index is not a number greater than or equal to 0 and less than the number of nodes represented by the collection, abort these steps.
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
The DOMStringMap
interface represents a set of
name-value pairs. It exposes these using the scripting language's
native mechanisms for property access.
When a DOMStringMap
object is instantiated, it is
associated with three algorithms, one for getting the list of
name-value pairs, one for setting names to certain values, and one
for deleting names.
interface DOMStringMap { getter DOMString (DOMString name); setter void (DOMString name, DOMString value); creator void (DOMString name, DOMString value); deleter void (DOMString name); };
The supported property names on a
DOMStringMap
object at any instant are the names of
each pair returned from the algorithm for getting the list of
name-value pairs at that instant.
To determine the value of
a named property name in a
DOMStringMap
, the user agent must return the value
component of the name-value pair whose name component is name in the list returned by the algorithm for
getting the list of name-value pairs.
To set the value of a new or existing named property name to value value, the
algorithm for setting names to certain values must be run, passing
name as the name and the result of converting
value to a DOMString
as the
value.
To delete an existing named property name, the algorithm for deleting names must be run, passing name as the name.
The DOMStringMap
interface definition
here is only intended for JavaScript environments. Other language
bindings will need to define how DOMStringMap
is to be
implemented for those languages.
The dataset
attribute on
elements exposes the data-*
attributes on the element.
Given the following fragment and elements with similar constructions:
<img class="tower" id="tower5" data-x="12" data-y="5" data-ai="robotarget" data-hp="46" data-ability="flames" src="towers/rocket.png alt="Rocket Tower">
...one could imagine a function splashDamage()
that takes some arguments, the first
of which is the element to process:
function splashDamage(node, x, y, damage) { if (node.classList.contains('tower') && // checking the 'class' attribute node.dataset.x == x && // reading the 'data-x' attribute node.dataset.y == y) { // reading the 'data-y' attribute var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute hp = hp - damage; if (hp < 0) { hp = 0; node.dataset.ai = 'dead'; // setting the 'data-ai' attribute delete node.dataset.ability; // removing the 'data-ability' attribute } node.dataset.hp = hp; // setting the 'data-hp' attribute } }
Some objects support being copied and closed in one operation. This is called transferring the object, and is used in particular to transfer ownership of unsharable or expensive resources across worker boundaries.
[NoInterfaceObject] interface Transferable { };
To transfer a Transferable
object to a
new owner, the user agent must run the steps defined for the type of
object in question. The steps will return a new object of the same
type, and will permanently neuter the original
object. (This is an irreversible and non-idempotent operation; once
an object has been transferred, it cannot be transferred, or indeed
used, again.)
The following Transferable
types exist:
MessagePort
ArrayBuffer
[TYPEDARRAY]
When a user agent is required to obtain a structured
clone of a value, optionally with a transfer map, it
must run the following algorithm, which either returns a separate
value, or throws an exception. If a transfer map is provided,
it consists of an association list of Transferable
objects to placeholder objects.
Let input be the value being cloned.
Let transfer map be the transfer map passed to the algorithm, if any, or the empty list otherwise.
Let memory be an association list of pairs of objects, initially empty. This is used to handle duplicate references. In each pair of objects, one is called the source object and the other the destination object.
For each mapping in transfer map, add a
mapping from the Transferable
object (the source
object) to the placeholder object (the destination object) to memory.
Let output be the value resulting from calling the internal structured cloning algorithm with input as the "input" argument, and memory as the "memory" argument.
Return output.
The internal structured cloning algorithm is always called with two arguments, input and memory, and its behavior is as follows:
If input is the source object of a pair of objects in memory, then return the destination object in that pair of objects and abort these steps.
If input is a primitive value, then return that value and abort these steps.
The input value is an object. Jump to the appropriate step below:
Let output be a newly constructed Boolean object with the same value as input.
Let output be a newly constructed Number object with the same value as input.
Let output be a newly constructed String object with the same value as input.
Date
objectLet output be a newly constructed Date
object with the same value as input.
RegExp
objectLet output be a newly constructed RegExp
object with the same pattern and flags as input.
The value of the lastIndex
property is not copied.
File
objectLet output be a newly constructed File
object corresponding to the same underlying data.
Blob
objectLet output be a newly constructed Blob
object corresponding to the same underlying data.
FileList
objectLet output be a newly constructed FileList
object containing a list of newly constructed File
objects corresponding to the same underlying data as those in input, maintaining their relative order.
ImageData
objectLet output be a newly constructed
ImageData
object whose width
and height
attributes have values
equal to the corresponding attributes on input, and whose data
attribute has the value
obtained from invoking the internal structured cloning
algorithm recursively with the value of the data
attribute on input as the new "input"
argument and memory as the new "memory" argument.
Let output be a newly constructed empty
Array
object whose length
is
equal to the length
of input.
This means that the length of sparse arrays is preserved.
Let output be a newly constructed empty Object
object.
Let output be a clone of the object as defined by the other specification.
Error
, Function
)Throw a DataCloneError
exception and abort
the overall structured clone algorithm.
Add a mapping from input (the source object) to output (the destination object) to memory.
If input is an Array object or an Object object, then, for each enumerable property in input, add a new property to output having the same name, and having a value created from invoking the internal structured cloning algorithm recursively with the value of the property as the "input" argument and memory as the "memory" argument. The order of the properties in the input and output objects must be the same, and any properties that involve running script must be processed in that same order. If obtaining the value of the property involved executing script, and that script threw an uncaught exception, then abort the overall structured clone algorithm, with that exception being passed through to the caller.
This does not walk the prototype chain.
Property descriptors, setters, getters, and analogous features are not copied in this process. For example, the property in the input could be marked as read-only, but in the output it would just have the default state (typically read-write, though that could depend on the scripting environment).
Properties of Array objects are not treated any differently than those of other Objects. In particular, this means that non-index properties of arrays are copied as well.
Return output.
This algorithm preserves cycles and preserves the identity of duplicate objects in graphs.
DOM3 Core defines mechanisms for checking for interface support, and for obtaining implementations of interfaces, using feature strings. [DOMCORE]
Authors are strongly discouraged from using these, as they are notoriously unreliable and imprecise. Authors are encouraged to rely on explicit feature testing or the graceful degradation behavior intrinsic to some of the features in this specification.
For historical reasons, user agents should return the true value
when the hasFeature(feature, version)
method of the DOMImplementation
interface is invoked
with feature set to either "HTML
" or "XHTML
" and version set to either "1.0
" or
"2.0
".
There is an implied strong reference from any IDL attribute that returns a pre-existing object to that object.