jump
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.
The HTMLCollection, HTMLAllCollection, HTMLFormControlsCollection, 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.
The HTMLCollection interface represents a generic collection of elements.
interface HTMLCollection {
readonly attribute unsigned long length;
caller getter Element item(in unsigned long index);
caller getter object namedItem(in DOMString name); // only returns Element
};
lengthReturns 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.
Returns null if index is out of range.
namedItem(name)Returns the first item with ID or name name from the collection.
Returns null if no element with that ID or name could be found.
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.
The HTMLAllCollection interface represents a generic collection of elements just like HTMLCollection, with the exception that its namedItem() method returns an HTMLAllCollection object when there are multiple matching elements.
interface HTMLAllCollection : HTMLCollection {
// inherits length and item()
caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
HTMLAllCollection tags(in DOMString tagName);
};
lengthReturns 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.
Returns null if index is out of range.
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.
Returns null if no element with that ID or name could be found.
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 HTMLFormControlsCollection interface represents a collection of listed elements in form and fieldset elements.
interface HTMLFormControlsCollection : HTMLCollection {
// inherits length and item()
caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
};
interface RadioNodeList : NodeList {
attribute DOMString value;
};
lengthReturns 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.
Returns null if index is out of range.
namedItem(name)namedItem(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 null if no element with that ID or name could be found.
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 HTMLOptionsCollection interface represents a list 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
caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
void add(in HTMLElement element, in optional HTMLElement before);
void add(in HTMLElement element, in long before);
void remove(in 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.
Returns null if index is out of range.
namedItem(name)namedItem(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.
Returns null if no element with that ID could be found.
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 HIERARCHY_REQUEST_ERR exception if element is an ancestor of the element into which it is to be inserted. If element is not an option or optgroup element, then the method does nothing.
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 DOMTokenList interface represents an interface to an underlying string that consists of a set of space-separated tokens.
DOMTokenList objects are always case-sensitive, even when the underlying string might ordinarily be treated in a case-insensitive manner.
interface DOMTokenList {
readonly attribute unsigned long length;
getter DOMString item(in unsigned long index);
boolean contains(in DOMString token);
void add(in DOMString token);
void remove(in DOMString token);
boolean toggle(in DOMString token);
stringifier DOMString ();
};
lengthReturns the number of tokens in the string.
item(index)Returns the token with index index. The tokens are returned in the order they are found in the underlying string.
Returns null if index is out of range.
contains(token)Returns true if the token is present; false otherwise.
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
add(token)Adds token, unless it is already present.
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
remove(token)Removes token if it is present.
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
toggle(token)Adds token if it is not present, or removes it if it is. Returns true if token is now present (it was added); returns false if it is not (it was removed).
Throws a SYNTAX_ERR exception if token is empty.
Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.
A DOMTokenList object must stringify to the value of the DOMTokenList object's underlying string.
The DOMSettableTokenList interface is the same as the DOMTokenList interface, except that it allows the underlying string to be directly changed.
interface DOMSettableTokenList : DOMTokenList {
attribute DOMString value;
};
valueReturns the underlying string.
Can be set, to change the underlying string.
The DOMStringMap interface represents a set of name-value pairs. It exposes these using the scripting language's native mechanisms for property access.
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
}
}
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.
The following are DOMException codes. [DOMCORE]
INDEX_SIZE_ERRDOMSTRING_SIZE_ERRHIERARCHY_REQUEST_ERRWRONG_DOCUMENT_ERRINVALID_CHARACTER_ERRNO_DATA_ALLOWED_ERRNO_MODIFICATION_ALLOWED_ERRNOT_FOUND_ERRNOT_SUPPORTED_ERRINUSE_ATTRIBUTE_ERRINVALID_STATE_ERRSYNTAX_ERRINVALID_MODIFICATION_ERRNAMESPACE_ERRINVALID_ACCESS_ERRVALIDATION_ERRTYPE_MISMATCH_ERRSECURITY_ERRNETWORK_ERRABORT_ERRURL_MISMATCH_ERRQUOTA_EXCEEDED_ERRTIMEOUT_ERRDATA_CLONE_ERR