HTML

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 associated element is the element in question and whose associated attribute's local name is the name of the attribute in question. The same DOMTokenList or DOMSettableTokenList object must be returned every time for each attribute.

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):

1. If the corresponding content attribute is absent, then the IDL attribute must return null.
2. Let candidate be the element that the 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.
3. If candidate is null, or if it is not type-compatible with the IDL attribute, then the IDL attribute must return null.
4. Otherwise, it must return candidate.

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.

interface HTMLAllCollection : HTMLCollection {
  // inherits length and item(unsigned long index)
  (HTMLCollection or Element)? item(DOMString name);
  legacycaller getter (HTMLCollection or Element)? namedItem(DOMString name); // shadows inherited namedItem()
  HTMLAllCollection tags(DOMString tagName);
};

The object's supported property indices are as defined for HTMLCollection objects.

The supported property names consist of the values of all the id attributes of all the elements represented by the collection, and the values of all the name attributes of all the a, applet, area, embed, form, frame, frameset, iframe, img, and object elements represented by the collection, in tree order, ignoring later duplicates, with the id of an element preceding its name if it has both, they differ from each other, and neither is the duplicate of an earlier entry.

The item(name) and namedItem(name) methods must act according to the following algorithm:

1. Let collection be an HTMLCollection 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:

   • a, applet, area, embed, form, frame, frameset, iframe, img, or object elements with a name attribute equal to name, or,
   • elements with an ID equal to name.
2. If, at the time the method is called, there is exactly one node in collection, then return that node and stop the algorithm.
3. Otherwise, if, at the time the method is called, collection is empty, return null and stop the algorithm.
4. Otherwise, return collection.

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.

interface HTMLFormControlsCollection : HTMLCollection {
  // inherits length and item()
  legacycaller getter (RadioNodeList or Element)? namedItem(DOMString name); // shadows inherited namedItem()
};

interface RadioNodeList : NodeList {
          attribute DOMString value;
};

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, in tree order, ignoring later duplicates, with the id of an element preceding its name if it has 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:

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 name, 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 name, then return null and stop the algorithm.
3. Otherwise, create a new 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.
4. Return that 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:

1. 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.

2. If element is null, or if it is an element with no value attribute, return the empty string.

3. Otherwise, return the value of element's value attribute.

On setting, the value IDL attribute must run the following steps:

1. 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.

2. If element is not null, then set its checkedness to true.

interface HTMLOptionsCollection : HTMLCollection {
  // inherits item()
           attribute unsigned long length; // shadows inherited length
  legacycaller getter (HTMLOptionElement or HTMLOptGroupElement)? namedItem(DOMString name); // shadows 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;
};

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, in tree order, ignoring later duplicates, with the id of an element preceding its name if it has both, they differ from each other, and neither is the duplicate of an earlier entry.

The namedItem(name) method must return the first node in the collection that has either an id attribute or a name attribute equal to name, if there is one; otherwise, it must return null.

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:

1. If value is null, invoke the steps for the remove method with index as the argument, and abort these steps.

2. Let length be the number of nodes represented by the collection.

3. Let n be index minus length.

4. 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.

5. 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:

1. If element is an ancestor of the select element on which the HTMLOptionsCollection is rooted, then throw a HierarchyRequestError exception and abort these steps.

2. 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 and abort these steps.

3. If element and before are the same element, then return and abort these steps.

4. 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.

5. 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.

6. Act as if the DOM 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:

1. If the number of nodes represented by the collection is zero, abort these steps.

2. 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.

3. Let element be the indexth element in the collection.

4. 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

interface HTMLPropertiesCollection : HTMLCollection {
  // inherits length and item()
  getter PropertyNodeList? namedItem(DOMString name); // shadows inherited namedItem()
  readonly attribute DOMString[] names;
};

typedef sequence<any> PropertyValueArray;

interface PropertyNodeList : NodeList {
  PropertyValueArray getValues();
};

The object's supported property indices are as defined for HTMLCollection objects.

The supported property names consist of the property names of all the elements represented by the collection, in tree order, ignoring later duplicates.

The names attribute must return a live read only array object giving the property names of all the elements represented by the collection, listed in tree order, but with duplicates removed, leaving only the first occurrence of each name. The same object must be returned each time.

The namedItem(name) method must return a PropertyNodeList object representing a live view of the HTMLPropertiesCollection object, further filtered so that the only nodes in the PropertyNodeList object are those that have a property name equal to name. The nodes in the PropertyNodeList object must be sorted in tree order, and the same object must be returned each time a particular name is queried.

---

Members of the PropertyNodeList interface inherited from the NodeList interface must behave as they would on a NodeList object.

The getValues method the PropertyNodeList object must return a newly constructed array whose values are the values obtained from the itemValue DOM property of each of the elements represented by the object, in tree order.

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 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, in the order returned.

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.

<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">

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
  }
}

When a DOMElementMap object is instantiated, it is associated with three algorithms, one for getting the list of name-element mappings, one for mapping a name to a certain element, and one for deleting mappings by name.

interface DOMElementMap {
  getter Element (DOMString name);
  setter creator void (DOMString name, Element value);
  deleter void (DOMString name);
};

The supported property names on a DOMElementMap object at any instant are the names for each mapping returned from the algorithm for getting the list of name-element mappings at that instant, in the order returned.

To determine the value of a named property name in a DOMElementMap, the user agent must return the element component of the name-element mapping whose name component is name in the list returned by the algorithm for getting the list of name-element mappings.

To set the value of a new or existing named property name to value value, the algorithm for mapping a name to a certain element must be run, passing name as the name value as the element.

To delete an existing named property name, the algorithm for deleting mappings must be run, passing name as the name component of the mapping to be deleted.

The DOMElementMap interface definition here is only intended for JavaScript environments. Other language bindings will need to define how DOMElementMap is to be implemented for those languages.

[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.)

2.7.6 Safe passing of structured data

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.

1. Let input be the value being cloned.

2. Let transfer map be the transfer map passed to the algorithm, if any, or the empty list otherwise.

3. 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.

4. 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.

5. 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.

6. Return output.

The internal structured cloning algorithm is always called with two arguments, input and memory, and its behavior is as follows:

1. 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.

2. If input is a primitive value, then return that value and abort these steps.

3. The input value is an object. Jump to the appropriate step below:

   If input is a Boolean object

   Let output be a newly constructed Boolean object with the same value as input.

   If input is a Number object

   Let output be a newly constructed Number object with the same value as input.

   If input is a String object

   Let output be a newly constructed String object with the same value as input.

   If input is a Date object

   Let output be a newly constructed Date object with the same value as input.

   If input is a RegExp object

   Let output be a newly constructed RegExp object with the same pattern and flags as input.

   The value of the lastIndex property is not copied.

   If input is a File object

   Let output be a newly constructed File object corresponding to the same underlying data.

   If input is a Blob object

   Let output be a newly constructed Blob object corresponding to the same underlying data.

   If input is a FileList object

   Let 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.

   If input is an ImageData object

   Let output be a newly constructed ImageData object whose width, height, and resolution 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.

   If input is an ImageBitmap object

   Let output be a newly constructed ImageBitmap object whose bitmap data is a copy of input's bitmap data.

   If input is an Array object

   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.

   If input is an Object object

   Let output be a newly constructed empty Object object.

   If input is an object that another specification defines how to clone

   Let output be a clone of the object as defined by the other specification.

   If input is another native object type (e.g. Error, Function)

   If input is a host object (e.g. a DOM node)

   Throw a DataCloneError exception and abort the overall structured clone algorithm.

4. Add a mapping from input (the source object) to output (the destination object) to memory.

5. 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.

6. Return output.

This algorithm preserves cycles and preserves the identity of duplicate objects in graphs.

callback FileCallback = void (File file);

2.7.8 Garbage collection

There is an implied strong reference from any IDL attribute that returns a pre-existing object to that object.