HTML 5

2.3. Common DOM interfaces

2.3.1. Collections

The HTMLCollection, HTMLFormControlsCollection, and HTMLOptionsCollection interfaces represent various lists of DOM nodes. Collectively, objects implementing these interfaces are called collections.

When a collection is created, a filter and a root are associated with the collection.

For example, when the HTMLCollection object for the document.images attribute is created, it is associated with a filter that selects only img elements, and rooted at the root of the document.

The collection then represents a live view of the subtree rooted at the collection's root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.

The rows list is not in tree order.

An attribute that returns a collection must return the same object every time it is retrieved.

2.3.1.1. HTMLCollection

The HTMLCollection interface represents a generic collection of elements.

interface HTMLCollection {
  readonly attribute unsigned long length;
  Element item(in unsigned long index);
  Element namedItem(in DOMString name);
};

The length attribute must return the number of nodes represented by the collection.

The item(index) method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must return null.

The namedItem(key) method must return the first node in the collection that matches the following requirements:

• It is an a, applet, area, form, img, or object element with a name attribute equal to key, or,
• It is an HTML element of any kind with an id attribute equal to key. (Non-HTML elements, even if they have IDs, are not searched for the purposes of namedItem().)

If no such elements are found, then the method must return null.

In ECMAScript implementations, objects that implement the HTMLCollection interface must also have a [[Get]] method that, when invoked with a property name that is a number, acts like the item() method would when invoked with that argument, and when invoked with a property name that is a string, acts like the namedItem() method would when invoked with that argument.

2.3.1.2. HTMLFormControlsCollection

The HTMLFormControlsCollection interface represents a collection of form controls.

interface HTMLFormControlsCollection {
  readonly attribute unsigned long length;
  HTMLElement item(in unsigned long index);
  Object namedItem(in DOMString name);
};

The length attribute must return the number of nodes represented by the collection.

The item(index) method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must return null.

The namedItem(key) method must act according to the following algorithm:

1. If, at the time the method is called, there is exactly one node in the collection that has either an id attribute or a name attribute equal to key, then return that node and stop the algorithm.
2. Otherwise, if there are no nodes in the collection that have either an id attribute or a name attribute equal to key, then return null and stop the algorithm.
3. Otherwise, create a NodeList object representing a live view of the HTMLFormControlsCollection 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 key. The nodes in the NodeList object must be sorted in tree order.
4. Return that NodeList object.

In the ECMAScript DOM binding, objects implementing the HTMLFormControlsCollection interface must support being dereferenced using the square bracket notation, such that dereferencing with an integer index is equivalent to invoking the item() method with that index, and such that dereferencing with a string index is equivalent to invoking the namedItem() method with that index.

2.3.1.3. HTMLOptionsCollection

The HTMLOptionsCollection interface represents a list of option elements.

interface HTMLOptionsCollection {
           attribute unsigned long length;
  HTMLOptionElement item(in unsigned long index);
  Object namedItem(in DOMString name);
};

On getting, the length attribute must return the number of nodes represented by the collection.

On setting, the behaviour 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). 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 item(index) method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must return null.

The namedItem(key) method must act according to the following algorithm:

1. If, at the time the method is called, there is exactly one node in the collection that has either an id attribute or a name attribute equal to key, then return that node and stop the algorithm.
2. Otherwise, if there are no nodes in the collection that have either an id attribute or a name attribute equal to key, then return null and stop the algorithm.
3. Otherwise, create a 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 key. The nodes in the NodeList object must be sorted in tree order.
4. Return that NodeList object.

In the ECMAScript DOM binding, objects implementing the HTMLOptionsCollection interface must support being dereferenced using the square bracket notation, such that dereferencing with an integer index is equivalent to invoking the item() method with that index, and such that dereferencing with a string index is equivalent to invoking the namedItem() method with that index.

We may want to add add() and remove() methods here too because IE implements HTMLSelectElement and HTMLOptionsCollection on the same object, and so people use them almost interchangeably in the wild.

2.3.2. DOMTokenList

The DOMTokenList interface represents an interface to an underlying string that consists of an unordered set of space-separated tokens.

Which string underlies a particular DOMTokenList object is defined when the object is created. It might be a content attribute (e.g. the string that underlies the classList object is the class attribute), or it might be an anonymous string (e.g. when a DOMTokenList object is passed to an author-implemented callback in the datagrid APIs).

interface DOMTokenList {
  readonly attribute unsigned long length;
  DOMString item(in unsigned long index);
  boolean has(in DOMString token);
  void add(in DOMString token);
  void remove(in DOMString token);
  boolean toggle(in DOMString token);
};

The length attribute must return the number of unique tokens that result from splitting the underlying string on spaces.

The item(index) method must split the underlying string on spaces, sort the resulting list of tokens by Unicode codepoint, remove exact duplicates, and then return the indexth item in this list. If index is equal to or greater than the number of tokens, then the method must return null.

In ECMAScript implementations, objects that implement the DOMTokenList interface must also have a [[Get]] method that, when invoked with a property name that is a number, acts like the item() method would when invoked with that argument.

The has(token) method must run the following algorithm:

1. If the token argument contains any spaces, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
2. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
3. If the token indicated by token is one of the tokens in the object's underlying string then return true and stop this algorithm.
4. Otherwise, return false.

The add(token) method must run the following algorithm:

1. If the token argument contains any spaces, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
2. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
3. If the given token is already one of the tokens in the DOMTokenList object's underlying string then stop the algorithm.
4. Otherwise, if the last character of the DOMTokenList object's underlying string is not a space character, then append a U+0020 SPACE character to the end of that string.
5. Append the value of token to the end of the DOMTokenList object's underlying string.

The remove(token) method must run the following algorithm:

1. If the token argument contains any spaces, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
2. Otherwise, remove the given token from the underlying string.

The toggle(token) method must run the following algorithm:

1. If the token argument contains any spaces, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
2. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
3. If the given token is already one of the tokens in the DOMTokenList object's underlying string then remove the given token from the underlying string, and stop the algorithm, returning false.
4. Otherwise, if the last character of the DOMTokenList object's underlying string is not a space character, then append a U+0020 SPACE character to the end of that string.
5. Append the value of token to the end of the DOMTokenList object's underlying string.
6. Return true.

In the ECMAScript DOM binding, objects implementing the DOMTokenList interface must stringify to the object's underlying string representation.

2.3.3. DOM feature strings

DOM3 Core defines mechanisms for checking for interface support, and for obtaining implementations of interfaces, using feature strings. [DOM3CORE]

A DOM application can use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTML" and "5.0" (respectively) to determine whether or not this module is supported by the implementation. In addition to the feature string "HTML", the feature string "XHTML" (with version string "5.0") can be used to check if the implementation supports XHTML. User agents should respond with a true value when the hasFeature method is queried with these values. Authors are cautioned, however, that UAs returning true might not be perfectly compliant, and that UAs returning false might well have support for features in this specification; in general, therefore, use of this method is discouraged.

The values "HTML" and "XHTML" (both with version "5.0") should also be supported in the context of the getFeature() and isSupported() methods, as defined by DOM3 Core.

The interfaces defined in this specification are not always supersets of the interfaces defined in DOM2 HTML; some features that were formerly deprecated, poorly supported, rarely used or considered unnecessary have been removed. Therefore it is not guarenteed that an implementation that supports "HTML" "5.0" also supports "HTML" "2.0".