Abstract

This specification defines the DOM Core part of the Web platform. The DOM is a language- and platform neutral interface that allows programs and scripts to dynamically access and update the content and structure of documents.

Table of contents

  1. Goals
  2. Issues
  3. 1 Common infrastructure
    1. 1.1 Terminology
    2. 1.2 Conformance requirements
      1. 1.2.1 Dependencies
      2. 1.2.2 Extensibility
    3. 1.3 Case-sensitivity
    4. 1.4 Common microsyntaxes
      1. 1.4.1 Common parser idioms
      2. 1.4.2 Space-separated tokens
    5. 1.5 DOM features
    6. 1.6 Cloning nodes
    7. 1.7 Namespaces
  4. 2 Exceptions
    1. 2.1 Exception DOMException
  5. 3 Nodes Model
  6. 4 Nodes
    1. 4.1 Interface Node
    2. 4.2 Interface DocumentFragment
    3. 4.3 Interface Document
      1. 4.3.1 Interface DOMImplementation
    4. 4.4 Interface Attr
    5. 4.5 Interface Element
    6. 4.6 Interface DocumentType
    7. 4.7 Interface ProcessingInstruction
    8. 4.8 Interface CharacterData
    9. 4.9 Interface Text
    10. 4.10 Interface Comment
  7. 5 Collections
    1. 5.1 Interface NodeList
    2. 5.2 Interface HTMLCollection
    3. 5.3 Interface NamedNodeMap
  8. 6 Lists
    1. 6.1 Interface DOMStringList
    2. 6.2 Interface DOMTokenList
    3. 6.3 Interface DOMSettableTokenList
  9. 7 Historical
  10. References
  11. Acknowledgements

Goals

Obsoleting DOM Level 3 Core is not a goal. It is a fine specification for Java servers. Web DOM Core presents an alternative.

New features might be added, once everything else is sort of stable.

Issues

1 Common infrastructure

1.1 Terminology

The term tree order means a pre-order, depth-first traversal of DOM nodes involved (through the parentNode/childNodes relationship).

The term context node means the Node on which the method or attribute being discussed was called.

The term root element, when not explicitly qualified as referring to the document's root element, means the furthest ancestor element node of whatever node is being discussed, or the node itself if it has no ancestors. When the node is a part of the document, then the node's root element is indeed the document's root element; however, if the node is not currently part of the document tree, the root element will be an orphaned node.

When an element's root element is the root element of a Document, it is said to be in a Document.

A node's home subtree is the subtree rooted at that node's root element. When a node is in a Document, its home subtree is that Document's tree.

The space characters, for the purposes of this specification, are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).

1.2 Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

1.2.1 Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

Except where otherwise specified, if an IDL attribute that is a floating point number type (float) is assigned an Infinity or Not-a-Number (NaN) value, a NOT_SUPPORTED_ERR exception must be raised.

Except where otherwise specified, if a method with an argument that is a floating point number type (float) is passed an Infinity or Not-a-Number (NaN) value, a NOT_SUPPORTED_ERR exception must be raised.

Some of the terms used in this specification are defined in Web IDL, XML and Namespaces in XML. [WEBIDL] [XML] [XMLNS]

1.2.2 Extensibility

Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.

If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.

When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognise the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.

1.3 Case-sensitivity

This specification defines several comparison operators for strings.

Comparing two strings in a case-sensitive manner means comparing them exactly, codepoint for codepoint.

Comparing two strings in a ASCII case-insensitive manner means comparing them exactly, codepoint for codepoint, except that the characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are considered to also match.

Converting a string to uppercase means replacing all characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).

Converting a string to lowercase means replacing all characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) with the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).

1.4 Common microsyntaxes

1.4.1 Common parser idioms

Some of the micro-parsers described below follow the pattern of having an input variable that holds the string being parsed, and having a position variable pointing at the next character to parse in input.

For parsers based on this pattern, a step that requires the user agent to collect a sequence of characters means that the following algorithm must be run, with characters being the set of characters that can be collected:

  1. Let input and position be the same variables as those of the same name in the algorithm that invoked these steps.

  2. Let result be the empty string.

  3. While position does not point past the end of input and the character at position is one of the characters, append that character to the end of result and advance position to the next character in input.

  4. Return result.

The step skip whitespace means that the user agent must collect a sequence of characters that are space characters. The collected characters are not used.

1.4.2 Space-separated tokens

A set of space-separated tokens is a string containing zero or more words separated by one or more space characters, where words consist of any string of one or more characters, none of which are space characters.

A string containing a set of space-separated tokens may have leading or trailing space characters.

When a user agent has to split a string on spaces, it must use the following algorithm:

  1. Let input be the string being parsed.

  2. Let position be a pointer into input, initially pointing at the start of the string.

  3. Let tokens be a list of tokens, initially empty.

  4. Skip whitespace

  5. While position is not past the end of input:

    1. Collect a sequence of characters that are not space characters.

    2. Add the string collected in the previous step to tokens.

    3. Skip whitespace

  6. Return tokens.

When a user agent has to remove a token from a string, it must use the following algorithm:

  1. Let input be the string being modified.

  2. Let token be the token being removed. It will not contain any space characters.

  3. Let output be the output string, initially empty.

  4. Let position be a pointer into input, initially pointing at the start of the string.

  5. Loop: If position is beyond the end of input, terminate these steps.

  6. If the character at position is a space character:

    1. Append the character at position to the end of output.

    2. Advance position so it points at the next character in input.

    3. Return to the step labeled loop.

  7. Otherwise, the character at position is the first character of a token. Collect a sequence of characters that are not space characters, and let that be s.

  8. If s is exactly equal to token, then:

    1. Skip whitespace (in input).

    2. Remove any space characters currently at the end of output.

    3. If position is not past the end of input, and output is not the empty string, append a single U+0020 SPACE character at the end of output.

  9. Otherwise, append s to the end of output.

  10. Return to the step labeled loop.

This causes any occurrences of the token to be removed from the string, and any spaces that were surrounding the token to be collapsed to a single space, except at the start and end of the string, where such spaces are removed.

1.5 DOM features

A DOM feature is a unique, ASCII case-insensitive string that represents a certain feature of the user agent.

A DOM feature version is a (feature, version) tuple, where feature is DOM feature and version is a case-sensitive string representing a version number.

Specifications may define which DOM features a user agent is to support, as well as an associated list of one or more case-sensitive strings representing version numbers, and under which circumstances, when necessary for compatibility (i.e. because of historical use). Specifications must not introduce new DOM features or new versions for existing features.

A user agent must support a DOM feature version (feature, version) if it supports a DOM feature that is a ASCII case-insensitive match for feature and version is in the associated list of versions.

A user agent must support the (feature, "") tuple if it supports a DOM feature that is a ASCII case-insensitive match for feature.

Authors are strongly discouraged from using DOM features, as they are notoriously unreliable and imprecise. Authors are encouraged to rely on explicit feature testing or graceful degradation.

For historical reasons, user agents must support the "XML" DOM feature with the versions "1.0" and "2.0" associated with it, and the "Core" DOM feature with the version "2.0" associated with it.

1.6 Cloning nodes

To clone a node, with a new ownerDocument and with a clone children flag, these steps must be run:

  1. If node is a DocumentType node, raise a DATA_CLONE_ERR exception and terminate these steps.

  2. Let copy be a new Node that implements the same interfaces as node, with ownerDocument set to new ownerDocument, prefix, localName and namespaceURI attributes set to the values of the attributes on node with the same names, and other attributes set to the values of the attributes on node with the same names, depending on the node:

    Attr

    value

    Text
    Comment

    data

    ProcessingInstruction

    target, data

    Any other node

    —

  3. If node is an Element node, let copy's attributes be a new NamedNodeMap, and for each Attr old attribute in node's attributes, clone it and append it to the copy's attributes.

  4. If the clone children flag is set, clone all the children of node and append them to copy, with the same new ownerDocument and the clone children flag being set.

  5. Return copy.

1.7 Namespaces

The HTML namespace is http://www.w3.org/1999/xhtml.

The XML namespace is http://www.w3.org/XML/1998/namespace.

The XMLNS namespace is http://www.w3.org/2000/xmlns/.

2 Exceptions

2.1 Exception DOMException

exception DOMException {
  const unsigned short INDEX_SIZE_ERR = 1;
  const unsigned short DOMSTRING_SIZE_ERR = 2; // historical
  const unsigned short HIERARCHY_REQUEST_ERR = 3;
  const unsigned short WRONG_DOCUMENT_ERR = 4;
  const unsigned short INVALID_CHARACTER_ERR = 5;
  const unsigned short NO_DATA_ALLOWED_ERR = 6; // historical
  const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
  const unsigned short NOT_FOUND_ERR = 8;
  const unsigned short NOT_SUPPORTED_ERR = 9;
  const unsigned short INUSE_ATTRIBUTE_ERR = 10; // historical
  const unsigned short INVALID_STATE_ERR = 11;
  const unsigned short SYNTAX_ERR = 12;
  const unsigned short INVALID_MODIFICATION_ERR = 13; // historical
  const unsigned short NAMESPACE_ERR = 14;
  const unsigned short INVALID_ACCESS_ERR = 15;
  const unsigned short VALIDATION_ERR = 16; // historical
  const unsigned short TYPE_MISMATCH_ERR = 17;
  const unsigned short SECURITY_ERR = 18;
  const unsigned short NETWORK_ERR = 19;
  const unsigned short ABORT_ERR = 20;
  const unsigned short URL_MISMATCH_ERR = 21;
  const unsigned short QUOTA_EXCEEDED_ERR = 22;
  const unsigned short TIMEOUT_ERR = 23;
  const unsigned short NOT_READABLE_ERR = 24;
  const unsigned short DATA_CLONE_ERR = 25;
  const unsigned short ENCODING_ERR = 26;

  unsigned short code;
  DOMString name;
};

The code exception field must return the code for the exception, which must be one of the following:

  1. INDEX_SIZE_ERR: the index is not in the allowed range;
  2. DOMSTRING_SIZE_ERR: the text does not fit in a DOMString (historical);
  3. HIERARCHY_REQUEST_ERR: the operation would yield an incorrect nodes model;
  4. WRONG_DOCUMENT_ERR: the object is in the wrong Document, a call to importNode is required;
  5. INVALID_CHARACTER_ERR: the string contains invalid characters;
  6. NO_DATA_ALLOWED_ERR: data is specified for an object that does not support it (historical);
  7. NO_MODIFICATION_ALLOWED_ERR: the object can not be modified;
  8. NOT_FOUND_ERR: the object can not be found here;
  9. NOT_SUPPORTED_ERR: this operation is not supported;
  10. INUSE_ATTRIBUTE_ERR: the attribute is in use (historical);
  11. INVALID_STATE_ERR: the object is in an invalid state;
  12. SYNTAX_ERR: the string did not match the expected pattern;
  13. INVALID_MODIFICATION_ERR: the object can not be modified (historical);
  14. NAMESPACE_ERR: the operation is not allowed by Namespaces in XML; [XMLNS]
  15. INVALID_ACCESS_ERR: the object does not support the operation or argument;
  16. VALIDATION_ERR: the operation is invalid (historical);
  17. TYPE_MISMATCH_ERR: the type of the object does not match the expected type;
  18. SECURITY_ERR: the operation is insecure;
  19. NETWORK_ERR: a network error occurred;
  20. ABORT_ERR: the user aborted an operation;
  21. URL_MISMATCH_ERR: the given URL does not match another URL;
  22. QUOTA_EXCEEDED_ERR: the quota has been exceeded;
  23. TIMEOUT_ERR: a timeout occurred;
  24. NOT_READABLE_ERR: the file cannot be read, typically due due to permission problems that occur after a reference to a file has been acquired;
  25. DATA_CLONE_ERR: the object can not be cloned;
  26. ENCODING_ERR: an error occurred while encoding the data.

The name exception field must return the name of the exception constant as a string.

3 Nodes Model

The DOM represents a tree of Node objects. The following structure is imposed on this tree, represented as relationship between the node and its child nodes:

Document

In tree order:

  1. Zero or more nodes each of which is either ProcessingInstruction or Comment.

  2. Optionally one DocumentType node.

  3. Zero or more nodes each of which is either ProcessingInstruction or Comment.

  4. Optionally one Element node.

  5. Zero or more nodes each of which is either ProcessingInstruction or Comment.

DocumentFragment
Element

Zero or more nodes each of which is one of Element, ProcessingInstruction, Comment, or Text.

DocumentType
ProcessingInstruction
Comment
Text

No children.

Attr

4 Nodes

4.1 Interface Node

interface Node {
  const unsigned short ELEMENT_NODE = 1;
  const unsigned short ATTRIBUTE_NODE = 2;
  const unsigned short TEXT_NODE = 3;
  const unsigned short CDATA_SECTION_NODE = 4; // historical
  const unsigned short ENTITY_REFERENCE_NODE = 5; // historical
  const unsigned short ENTITY_NODE = 6; // historical
  const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short COMMENT_NODE = 8;
  const unsigned short DOCUMENT_NODE = 9;
  const unsigned short DOCUMENT_TYPE_NODE = 10;
  const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short NOTATION_NODE = 12; // historical

  readonly attribute unsigned short nodeType;
  readonly attribute DOMString nodeName;
           attribute DOMString nodeValue;
           attribute DOMString textContent;

  readonly attribute Document ownerDocument;
  readonly attribute Node parentNode;
  readonly attribute Element parentElement;
  boolean hasChildNodes();
  readonly attribute NodeList childNodes;
  readonly attribute Node firstChild;
  readonly attribute Node lastChild;
  readonly attribute Node previousSibling;
  readonly attribute Node nextSibling;

  boolean hasAttributes();
  readonly attribute NamedNodeMap attributes;

  Node insertBefore(Node newChild, Node refChild);
  Node replaceChild(Node newChild, Node oldChild);
  Node removeChild(Node oldChild);
  Node appendChild(Node newChild);

  readonly attribute DOMString namespaceURI;
  readonly attribute DOMString prefix;
  readonly attribute DOMString localName;

  readonly attribute DOMString baseURI;

  const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
  const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
  const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
  const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;

  unsigned short compareDocumentPosition(Node other);

  Node cloneNode(boolean deep);
  boolean isSameNode(Node node);
  boolean isEqualNode(Node node);

  DOMString lookupPrefix([TreatNullAs=EmptyString] DOMString namespace);
  DOMString lookupNamespaceURI(DOMString? prefix);
  boolean isDefaultNamespace([TreatNullAs=EmptyString] DOMString namespace);
};

The nodeType attribute must return the type of the node, which must be one of the following:

  1. ELEMENT_NODE
  2. ATTRIBUTE_NODE
  3. TEXT_NODE
  4. CDATA_SECTION_NODE (historical)
  5. ENTITY_REFERENCE_NODE (historical)
  6. ENTITY_NODE (historical)
  7. PROCESSING_INSTRUCTION_NODE
  8. COMMENT_NODE
  9. DOCUMENT_NODE
  10. DOCUMENT_TYPE_NODE
  11. DOCUMENT_FRAGMENT_NODE
  12. NOTATION_NODE (historical)

The constants marked historical can no longer be returned, but are still exposed on the interface.

The nodeName attribute must return the following, depending on the context node:

Element

The context node's tagName attribute.

Attr

The context node's name attribute.

Text

"#text".

ProcessingInstruction

The context node's target attribute.

Comment

"#comment".

Document

"#document".

DocumentType

The context node's name attribute.

DocumentFragment

"#document-fragment".

The nodeValue attribute must return the following, depending on the context node:

Attr
Text
Comment
ProcessingInstruction

The context node's textContent attribute.

Any other node

Null.

Setting the nodeValue attribute must do as described below, depending on the context node:

Attr
Text
Comment
ProcessingInstruction

Set the context node's textContent attribute to the given value.

Any other node

Do nothing.

The textContent attribute must return the following, depending on the context node:

DocumentFragment
Element
Attr

The concatenation of the data of all the descendant Text nodes of the context node, in tree order.

Text
Comment

The context node's data attribute.

ProcessingInstruction

The context node's data attribute.

Any other node
Null.

Setting the textContent attribute must do as described below, depending on the context node:

DocumentFragment
Element
Attr

  1. Remove all the descendent nodes of the context node.

  2. Let data be the given value.

  3. If data is not the empty string, append a new Text node to the context node whose data is set to data.

Text
Comment

Set context node's data attribute to the given value.

ProcessingInstruction

Set the context node's data attribute to the given value.

Any other node
Do nothing.

The ownerDocument attribute must return the Document node that the context node is associated with, or null if there is none.

The parentNode attribute must run these steps:

  1. If the context node is an Attr node, return null and terminate these steps.

  2. If the context node does not have a parent node, return null and terminate these steps.

  3. Return the parent node of the context node.

The parentElement attribute must return the parent node of the context node if there is a parent and it is an Element node, or null otherwise.

The hasChildNodes() method must return false if the context node's firstChild is null, or true otherwise.

The childNodes attribute must return a NodeList rooted at the context node matching only child nodes.

The firstChild attribute must return the first child node of the context node, or null if there is none.

The lastChild attribute must return the last child node of the context node, or null if there is none.

The previousSibling attribute must run these steps:

  1. If the context node is an Attr node, return null and terminate these steps.

  2. If the context node does not have a previous sibling node, return null and terminate these steps.

  3. Return the previous sibling node of the context node.

The nextSibling attribute must run these steps:

  1. If the context node is an Attr node, return null and terminate these steps.

  2. If the context node does not have a next sibling node, return null and terminate these steps.

  3. Return the next sibling node of the context node.

The hasAttributes() method must return true if there are any attributes associated with the context node, if it is an Element node, and false otherwise.

The attributes attribute must return a NamedNodeMap of all the Attr nodes associated with the node of the context node, if it is an Element node, or null otherwise.

The insertBefore(newChild, refChild) method must run these steps:

  1. If the context node is an Attr node or a Text node, then raise a HIERARCHY_REQUEST_ERR and terminate these steps.

  2. If newChild is null, then raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  3. If refChild is null, return the result of invoking context node's appendChild with newChild as argument and terminate these steps.

  4. If refChild is not a child of the context node, then raise a NOT_FOUND_ERR exception and terminate these steps.

  5. If newChild is the context node or an ancestor of the context node raise a HIERARCHY_REQUEST_ERR and terminate these steps.

  6. If newChild is a DocumentType node and its ownerDocument is not null raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  7. If newChild is a DocumentType node set its ownerDocument to the context node's ownerDocument.

  8. If newChild is not a DocumentType node let newChild be the result of invoking the context node's ownerDocument adoptNode method with newChild as its argument.

  9. If newChild is a DocumentFragment node, insert the children of newChild in the context node, in tree order, so that the last child becomes the previous sibling of refChild.

  10. Otherwise insert newChild in the context node as the previous sibling of refChild.

  11. Return newChild.

The replaceChild(newChild, oldChild) method must run these steps:

  1. If the context node is an Attr node or a Text node, then raise a HIERARCHY_REQUEST_ERR and terminate these steps.

  2. If either newChild or oldChild is null, then raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  3. If oldChild is not a child of the context node, then raise a NOT_FOUND_ERR exception and terminate these steps.

  4. If newChild is the context node or an ancestor of the context node raise a HIERARCHY_REQUEST_ERR and terminate these steps.

  5. If newChild is a DocumentType node and its ownerDocument is not null raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  6. If newChild is a DocumentType node set its ownerDocument to the context node's ownerDocument.

  7. If newChild is not a DocumentType node let newChild be the result of invoking the context node's ownerDocument adoptNode method with newChild as its argument.

  8. Let refChild be oldChild's nextSibling.

  9. Remove oldChild from the context node.

  10. Return the result of invoking the context node's insertBefore method with newChild and refChild as arguments.

The removeChild(oldChild) method must run these steps:

  1. If oldChild is null, then raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  2. If oldChild is not a child of the context node, then raise a NOT_FOUND_ERR exception and terminate these steps.

  3. Remove oldChild from the context node.

  4. Return oldChild.

The appendChild(newChild) method must run these steps:

  1. If the context node is an Attr node or a Text node, then raise a HIERARCHY_REQUEST_ERR and terminate these steps.

  2. If newChild is null, then raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  3. If newChild is the context node or an ancestor of the context node raise a HIERARCHY_REQUEST_ERR and terminate these steps.

  4. If newChild is a DocumentType node and its ownerDocument is not null raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  5. If newChild is a DocumentType node set its ownerDocument to the context node's ownerDocument.

  6. If newChild is not a DocumentType node let newChild be the result of invoking the context node's ownerDocument adoptNode method with newChild as its argument.

  7. Append newChild to the context node.

  8. Return newChild.

The namespaceURI attribute must return the namespace that is associated with the node, if there is one and it's not the empty string, or null otherwise.

The prefix attribute must return the prefix that is associated with the node, if there is one and it's not the empty string, or null otherwise.

Setting the prefix attribute is not supported.

The localName attribute must return the local name that is associated with the node, if it has one, and null otherwise.

The baseURI attribute must ...

These are the constants compareDocumentPosition() returns.

  1. DOCUMENT_POSITION_DISCONNECTED
  2. DOCUMENT_POSITION_PRECEDING
  3. DOCUMENT_POSITION_FOLLOWING
  4. DOCUMENT_POSITION_CONTAINS
  5. DOCUMENT_POSITION_CONTAINED_BY
  6. DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC

The compareDocumentPosition(other) method must ...

The cloneNode(deep) method must return a clone of the context node, with new ownerDocument being the context node's ownerDocument, and the clone children flag set if deep is true.

The isSameNode(node) method must return true if node is a reference to the same object as the context node, or false otherwise.

The isEqualNode(node) method must return true if all of the following conditions are true, or false otherwise:

To locate a namespace prefix for an element using namespace run these steps:

  1. If element's namespace is namespace and its namespace prefix is not null return its namespace prefix and terminate these steps.

  2. If there is an attribute associated with the element whose namespace prefix is "xmlns" and value is namespace then return its local name and terminate these steps.

  3. Return the result of running locate a namespace prefix on its parentNode using namespace, if parentNode is an Element node, or null otherwise.

To locate a namespace for a node using prefix depends on the node:

Element

  1. If its namespace is not null and its namespace prefix is prefix return namespace and terminate these steps.

  2. If there is an attribute associated with the node whose namespace prefix is "xmlns" and local name is prefix or whose namespace prefix is null and local name is "xmlns":

    1. Let value be its value if it is not the empty string, or null otherwise.

    2. Return value and terminate these steps.

  3. Return the result of running locate a namespace on its parentNode using prefix, if parentNode is an Element node, or null otherwise.

Document

Return the result of running locate a namespace on its documentElement using prefix, if documentElement is not null, or null otherwise.

DocumentType
DocumentFragment

Return null.

Any other node

Return the result of running locate a namespace on its parentNode using prefix, if parentNode is an Element node, or null otherwise.

The lookupPrefix(namespace) method must run these steps:

  1. If namespace is the empty string return null.

  2. Otherwise it depends on the context node:

    Element

    Return the result of running locate a namespace prefix for the node using namespace.

    Document

    Return the result of finding a namespace prefix for its documentElement, if that is not null, or null otherwise.

    DocumentType
    DocumentFragment

    Return null.

    Any other node

    Return the result of finding a namespace prefix for its parentNode, if that is an Element node, or null otherwise.

The lookupNamespaceURI(prefix) method must return the result of running locate a namespace for the context node using prefix.

The isDefaultNamespace(namespace) method must run these steps:

  1. Let defaultNamespace be the result of invoking lookupNamespaceURI with null as argument on the context node.

  2. If defaultNamespace is null let it be the empty string.

  3. Return true if defaultNamespace is namespace, or false otherwise.

4.2 Interface DocumentFragment

interface DocumentFragment : Node {
};

4.3 Interface Document

interface Document : Node {
  readonly attribute DocumentType doctype;
  readonly attribute DOMImplementation implementation;
  readonly attribute Element documentElement;

  Element createElement([TreatNullAs=EmptyString] DOMString localName);
  Element createElementNS(DOMString namespace, DOMString qualifiedName);
  DocumentFragment createDocumentFragment();
  Text createTextNode(DOMString data);
  Comment createComment(DOMString data);
  ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);

  NodeList getElementsByTagName(DOMString qualifiedName);
  NodeList getElementsByTagNameNS(DOMString namespace, DOMString localName);
  NodeList getElementsByClassName(DOMString classNames);
  Element getElementById(DOMString elementId);

  Node importNode(Node node, boolean deep);
  Node adoptNode(Node node);

           attribute DOMString documentURI;
  readonly attribute DOMString compatMode;
};

A Document node is assumed to be an XML document unless it is flagged as being an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.

A Document node is always set to one of three modes: no-quirks mode, the default; quirks mode, used typically for legacy documents; and limited-quirks mode, also known as "almost standards" mode. Unless other applicable specifications define otherwise, the Document must be in no-quirks mode.

The mode is only ever changed from the default if the Document node is created by the HTML parser, based on the presence, absence, or value of the DOCTYPE string. [HTML]

The doctype attribute must return the first child of the Document node that is a DocumentType node, if there is one, or null otherwise.

In both HTML and XML there will only ever be one DocumentType node descendant of the Document node. [HTML] [XML]

The implementation attribute must return the DOMImplementation object that is associated with the Document node.

The documentElement attribute must return the first child of the Document node that is an Element node, if there is one, or null otherwise.

The createElement(localName) method must run the these steps:

  1. If localName does not match the Name production in XML, raise an INVALID_CHARACTER_ERR exception and terminate these steps.

  2. If the context node is an HTML document, let localName be converted to lowercase.

  3. Return a new Element node with no attributes, namespace set to the HTML namespace, local name set to localName, and ownerDocument set to the context node.

The createElementNS(namespace, qualifiedName) method must run these steps:

  1. If qualifiedName does not match the Name production in XML, raise an INVALID_CHARACTER_ERR exception and terminate these steps.

  2. If qualifiedName does not match the QName production in Namespaces in XML, raise a NAMESPACE_ERR exception and terminate these steps.

  3. If qualifiedName contains a ":" (U+003E), then split the string on it and let prefix be the part before and localName the part after. Otherwise, let prefix be null and localName be qualifiedName.

  4. If prefix is not null and namespace is an empty string, raise a NAMESPACE_ERR exception and terminate these steps.

  5. If prefix is "xml" and namespace is not the XML namespace, raise a NAMESPACE_ERR exception and terminate these steps.

  6. If qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, raise a NAMESPACE_ERR exception and terminate these steps.

  7. If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", raise a NAMESPACE_ERR exception and terminate these steps.

  8. Return a new Element node with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, and ownerDocument set to the context node.

The createDocumentFragment() method must return a new DocumentFragment node with its ownerDocument set to the context node.

The createTextNode(data) method must return a new Text node with its data attribute set to data and ownerDocument set to the context node.

No check is performed that the text node contains characters that match the Char production in XML.

The createComment(data) method must return a new Comment node with its data attribute set to data and ownerDocument set to the context node.

No check is performed that the comment contains characters that match the Char production in XML or that it contains two adjacent hyphens or ends with a hyphen.

The createProcessingInstruction(target, data) method must run these steps:

  1. If the context node is an HTML document, raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  2. If target does not match the Name production in XML, raise an INVALID_CHARACTER_ERR exception and terminate these steps.

  3. If data contains the string "?>", raise an INVALID_CHARACTER_ERR exception and terminate these steps.

  4. Return a new ProcessingInstruction, with target set to target, data set to data, and ownerDocument set to the context node.

No check is performed that the processing instruction target contains "xml" or the colon, or that the data contains characters that match the Char production in XML.

collection = document . getElementsByClassName(classes)
collection = element . getElementsByClassName(classes)

Returns a NodeList of the elements in the object on which the method was invoked (a Document or an Element) that have all the classes given by classes.

The classes argument is interpreted as a space-separated list of classes.

The getElementsByTagName(localName) method must run these steps:

  1. If localName is "*" (U+002A), return a NodeList rooted at the context node, whose filter matches only Element nodes.

  2. Otherwise, if the context node is an HTML document, return a NodeList rooted at the context node, whose filter matches only the following nodes:

  3. Otherwise, return a NodeList rooted at the context node, whose filter matches only Element nodes whose local name is localName.

A new NodeList object must be returned each time. XXX some impl cache

Thus, in an HTML document, document.getElementsByTagName("FOO") will match FOO elements that aren't in the HTML namespace, and foo elements that are in the HTML namespace, but not FOO elements that are in the HTML namespace.

The getElementsByTagNameNS(namespace, localName) method must run these steps:

  1. If both namespace and localName are "*" (U+002A) return a NodeList rooted at the context node, whose filter matches only Element nodes.

  2. Otherwise, if just namespace is "*" (U+002A), return a NodeList rooted at the context node, whose filter matches only Element nodes whose local name is localName.

  3. Otherwise, if just localName is "*" (U+002A), return a NodeList rooted at the context node, whose filter matches only Element nodes whose namespace is namespace.

  4. Otherwise, return a NodeList rooted at the context node, whose filter matches only Element nodes whose namespace is namespace and local name is localName.

A new NodeList object must be returned each time. XXX some impl cache

The getElementsByClassName(classNames) method takes a string that contains a set of space-separated tokens representing classes. When called, the method must return a live NodeList object containing all the elements in the context node, in tree order, that have all the classes specified in the classNames argument, having obtained the classes by splitting the string on spaces. (Duplicates are ignored.) If there are no tokens specified in the argument, then the method must return an empty NodeList. If the document is in quirks mode, then the comparisons for the classes must be done in an ASCII case-insensitive manner, otherwise, the comparisons must be done in a case-sensitive manner.

A new NodeList object must be returned each time.

Given the following XHTML fragment:

<div id="example">
  <p id="p1" class="aaa bbb"/>
  <p id="p2" class="aaa ccc"/>
  <p id="p3" class="bbb ccc"/>
</div>

A call to document.getElementById('example').getElementsByClassName('aaa') would return a NodeList with the two paragraphs p1 and p2 in it.

A call to getElementsByClassName('ccc bbb') would only return one node, however, namely p3. A call to document.getElementById('example').getElementsByClassName('bbb  ccc ') would return the same thing.

A call to getElementsByClassName('aaa,bbb') would return no nodes; none of the elements above are in the "aaa,bbb" class.

The getElementById(elementId) method must return the first Element node, in tree order, in the context node whose ID is elementId, or null if there is none.

The importNode(node, deep) method must return a clone of node, with new ownerDocument being the context node, and the clone children flag set if deep is true.

The adoptNode(node) method must run these steps:

  1. If node is a Document node or a DocumentType node, raise a NOT_SUPPORTED_ERR exception and terminate these steps.

  2. If node is an Element node, it is affected by a base URL change.

  3. If node's parentNode is not null, remove node from its parent.

  4. Set ownerDocument for node and all its descendent nodes as well as any associated Attr nodes to the context node.

  5. Return node.

document . compatMode

Returns the string "CSS1Compat" if the context node is in no-quirks mode or limited-quirks mode, and "BackCompat", if the Document is in quirks mode.

documentURI Should document.documentURI really exist? be readonly?

The compatMode IDL attribute must return the literal string "CSS1Compat" unless the context node is in quirks mode, in which case it must instead return the literal string "BackCompat".

4.3.1 Interface DOMImplementation

User agents must create a new DOMImplementation object whenever a new Document node is created and associate it with the that Document node. 

interface DOMImplementation {
  boolean hasFeature(DOMString feature, [TreatNullAs=EmptyString] DOMString version);

  DocumentType createDocumentType([TreatNullAs=EmptyString] DOMString qualifiedName, DOMString publicId, DOMString systemId);
  Document createDocument([TreatNullAs=EmptyString] DOMString namespace, [TreatNullAs=EmptyString] DOMString qualifiedName, DocumentType doctype);
  Document createHTMLDocument(DOMString title);
};
hasSupport = document . implementation . hasFeature( feature, version )

Returns whether the user agent supports the version version of feature. The empty string means any version.

The hasFeature(feature, version) method must return true if the user agent supports the (feature, version) tuple and false otherwise.

doctype = document . implementation . createDocumentType( qualifiedName, publicId, systemId )

Returns a new DocumentType, with the given qualifiedName, publicId, and systemId. If qualifiedName does not match the Name production in XML, an INVALID_CHARACTER_ERR exception is raised, and if it does not match the NCName production in Namespaces in XML, a NAMESPACE_ERR exception is raised.

doc = document . implementation . createDocument( namespace, qualifiedName, doctype )

Returns a new Document, with a new root Element whose localName is qualifiedName and whose namespaceURI is namespace (unless qualifiedName is the empty string), and with doctype, if it is given, as its DocumentType.

This method raises the same exceptions as the createElementNS method, when called with the same arguments. If doctype comes from another Document, a WRONG_DOCUMENT_ERR exception is raised.

doc = document . implementation . createHTMLDocument( title )

Returns a new Document, with a basic DOM already constructed with an appropriate title element.

The createDocumentType(qualifiedName, publicId, systemId) method must run the following steps:

  1. If qualifiedName does not match the Name production in XML, raise an INVALID_CHARACTER_ERR exception and terminate these steps.

  2. If qualifiedName does not match the NCName production in Namespaces in XML, raise a NAMESPACE_ERR exception and terminate these steps.

  3. Return a new DocumentType, with qualifiedName as its name, publicId as its public ID, and systemId as its system ID, and with its ownerDocument set to null.

No check is performed that the publicId matches the PublicChar production in XML or that the systemId does not contain both a quotation mark (") and an apostrophe (').

The createDocument(namespace, qualifiedName, doctype) method must run the following steps:

  1. Let document be a new Document node.

  2. Let element be null.

  3. If qualifiedName is not the empty string, set element to the result of invoking the createElementNS method with the arguments namespace and qualifiedName on document. If that raised an exception, re-raise the same exception and terminate these steps.

  4. If doctype is not null, run the following substeps:

    1. If the doctype's ownerDocument is not null, raise a WRONG_DOCUMENT_ERR exception and terminate the overall set of steps.

    2. Set the doctype's ownerDocument to document.

    3. Append doctype to document.

  5. If element is not null, append element to document.

  6. Return document.

The createHTMLDocument(title) method, when invoked, must run the following steps:

  1. Let doc be a newly created Document object.

  2. Mark doc as being an HTML document.

  3. Create a new DocumentType, with "html" as its name and with its ownerDocument set to doc. Append the newly created node to doc.

  4. Create an html element in the HTML namespace, and append it to doc.

  5. Create a head element in the HTML namespace, and append it to the html element created in the previous step.

  6. Create a title element in the HTML namespace, and append it to the head element created in the previous step.

  7. Create a Text node, and set its data attribute to the string given by the method's argument (which could be the empty string). Append it to the title element created in the previous step.

  8. Create a body element in the HTML namespace, and append it to the html element created in the earlier step.

  9. Return doc.

4.4 Interface Attr

The tentative plan is to let Attr no longer have child nodes and turn it into a very lightweight object that no longer inherits from Node — http://lists.w3.org/Archives/Public/public-webapps/2010JulSep/0797.html 

interface Attr : Node {
  readonly attribute DOMString name;
  readonly attribute boolean specified;
           attribute DOMString value;
  readonly attribute Element ownerElement;
};

Attr nodes represent attributes. They have a name and an element associated with them when they are created. Attr nodes are not considered part of the document tree, so their parentNode, previousSibling and nextSibling attributes return null. Also, its child nodes can not be manipulated directly through the insertBefore, replaceChild and appendChild methods.

The name attribute must return the name associated with the context node.

The specified attribute must return true.

The value attribute must return the value of the context node's textContent attribute and on setting, must set the context node's textContent attribute to the given value.

The ownerElement attribute must return the element associated with the context node.

This specification further defines two special types of attributes: ID attributes and class attributes.

ID attributes must have a value that contains at least one character and does not contain any space characters. The value must be unique amongst all the IDs in the element's home subtree.

For example, the id attribute in HTML is an ID attribute, as well as the id attributes in MathML and SVG. [HTML] [MATHML] [SVG]

Class attributes must have a value that is a set of space-separated tokens representing the various classes that the element belongs to.

The classes that an Element node has associated with it is the set of all the classes returned when the value of the class attribute is split on spaces. (Duplicates are ignored.)

The class attributes in HTML, MathML and SVG are all class attributes. [HTML] [MATHML] [SVG]

This specification does not define the name of ID or class attributes.

4.5 Interface Element

interface Element : Node {
  readonly attribute DOMString tagName;

  DOMString? getAttribute(DOMString qualifiedName);
  DOMString? getAttributeNS(DOMString namespace, DOMString localName);
  void setAttribute(DOMString qualifiedName, DOMString value);
  void setAttributeNS(DOMString namespace, DOMString qualifiedName, DOMString value);
  void removeAttribute(DOMString qualifiedName);
  void removeAttributeNS(DOMString namespace, DOMString localName);
  boolean hasAttribute(DOMString qualifiedName);
  boolean hasAttributeNS(DOMString namespace, DOMString localName);

  NodeList getElementsByTagName(DOMString qualifiedName);
  NodeList getElementsByTagNameNS(DOMString namespace, DOMString localName);
  NodeList getElementsByClassName(DOMString classNames);

  readonly attribute HTMLCollection children;
};

Element nodes have an associated namespace, namespace prefix, local name, and qualified name.

When an Element node is created its local name is always given. Unless explicitly given when an Element node is created, its namespace and namespace prefix are null and its qualified name is its namespace prefix, followed by a ":" (U+003A), followed by its local name, if its namespace prefix is not null, or otherwise qualified name is just its local name.

Element nodes can have a unique identifier (ID) associated with them. User agents must associate the value of all ID attributes in the Element node's attributes with the Element node, unless it is the empty string.

Specifications may define base URL change steps.

When an Element node is affected by a base URL change, the user agent must run the base URL change steps, as defined in other applicable specifications.

The tagName attribute must return the context node's qualified name, converted to uppercase if the context node is in the HTML namespace and its ownerDocument is an HTML document.

The getAttribute(name) method must run these steps:

  1. If the context node is in the HTML namespace and its ownerDocument is an HTML document, let name be converted to lowercase.

  2. Return the value of the first attribute in the context node's attributes whose name is name, if the attribute is present, or null otherwise.

The getAttributeNS(namespace, localName) method must return the value of the attribute in the context node's attributes whose namespaceURI is namespace and localName is localName, if the attribute is present, or null otherwise.

The setAttribute(qualifiedName, value) method must run these steps:

  1. If qualifiedName does not match the Name production in XML, raise an INVALID_CHARACTER_ERR exception and terminate these steps.

  2. Do something about qualifiedName == "xmlns"? Moz bug 315805

  3. If the context node is in the HTML namespace and its ownerDocument is an HTML document, let qualifiedName be converted to lowercase.

  4. If the node does not have an attribute whose name is qualifiedName, create an Attr node, with qualifiedName as its name and the context node as its element. Set its value to value. Append this node to the context node's attributes, as its last item.

  5. Otherwise, set the value of the first attribute in the context node's attributes whose name is qualifiedName, in any namespace, to value.

setAttributeNS

removeAttribute

removeAttributeNS

The hasAttribute(qualifiedName) method must run these steps:

  1. If the context node is in the HTML namespace and its ownerDocument is an HTML document, let qualifiedName be converted to lowercase.

  2. Return true if context node's attributes contains an attribute whose name is qualifiedName, or false otherwise.

The hasAttributeNS(namespace, localName) method must return true if context node's attributes contains an attribute whose namespaceURI is namespace and localName is localName, or false otherwise.

The getElementsByTagName(qualifiedName) method on the Element interface must return a live NodeList with the nodes that the getElementsByTagName method would return when called on the context node's ownerDocument and passed the same argument, excluding any elements that are not descendants of the context node on which the method was invoked.

A new NodeList object must be returned each time.

The getElementsByTagNameNS(namespace, localName) method on the Element interface must return a live NodeList with the nodes that the getElementsByTagNameNS method would return when called on the context node's ownerDocument and passed the same arguments, excluding any elements that are not descendants of the context node on which the method was invoked.

A new NodeList object must be returned each time.

The getElementsByClassName(classNames) method on the Element interface must return a live NodeList with the nodes that the getElementsByClassName method would return when called on the context node's ownerDocument and passed the same argument, excluding any elements that are not descendants of the context node on which the method was invoked.

A new NodeList object must be returned each time.

The children attribute must return an HTMLCollection collection, rooted at the context node, whose filter matches only Element nodes whose parentNode is the context node.

4.6 Interface DocumentType

interface DocumentType : Node {
  readonly attribute DOMString name;
  readonly attribute DOMString publicId;
  readonly attribute DOMString systemId;
};

DocumentType nodes have an associated name, public ID, and system ID.

When a DocumentType node is created name is always given. Unless explicitly given when a DocumentType node is created, its public ID and system ID are the empty string.

The name attribute must return the context node's name.

The publicId attribute must return the context node's public ID.

The systemId attribute must return the context node's system ID.

4.7 Interface ProcessingInstruction

interface ProcessingInstruction : Node {
  readonly attribute DOMString target;
           attribute DOMString data;
};

ProcessingInstruction nodes have an associated target and data. When a ProcessingInstruction node is created both are given.

The target attribute must return the context node's target.

The data attribute must return the context node's data, and on setting, set the context node's data to the new value.

4.8 Interface CharacterData

interface CharacterData : Node {
  [TreatNullAs=EmptyString] attribute DOMString data;
  readonly attribute unsigned long length;
  DOMString substringData(unsigned long offset, unsigned long count);
  void appendData(DOMString data);
  void insertData(unsigned long offset, DOMString data);
  void deleteData(unsigned long offset, unsigned long count);
  void replaceData(unsigned long offset, unsigned long count, DOMString data);
};

The data attribute must return the data of the node, and on setting, must change the node's data to the new value.

The length attribute must return the number of UTF-16 code units represented by the node's data.

The substringData(offset, count) method must run these steps:

  1. If offset is negative or is greater than the context node's length, or if count is negative, raise an INDEX_SIZE_ERR exception and terminate these steps.

  2. If offset+count is greater than the context node's length, return a DOMString whose value is the UTF-16 code units from the offsetth UTF-16 code unit to the end of data.

  3. Return a DOMString whose value is the UTF-16 code units from the offsetth UTF-16 code unit to the offset+countth UTF-16 code unit in data.

The appendData(data) method must append data to the context node's data.

The insertData(offset, data) method must run these steps:

  1. If offset is greater than the context node's length, raise an INDEX_SIZE_ERR exception and terminate these steps.

  2. Insert data into the context node's data after offset UTF-16 code units.

The deleteData(offset, count) method must run these steps:

  1. If offset is greater than the context node's length, raise an INDEX_SIZE_ERR exception and terminate these steps.

  2. If offset+count is greater than the context node's length let count be length-offset.

  3. Starting from offset UTF-16 code units remove count UTF-16 code units from the context node's data.

The replaceData(offset, count, data) method must act as if the deleteData() method is invoked with offset and count as arguments followed by the insertData() method with offset and data as arguments and re-raise any exceptions these methods might have raised.

4.9 Interface Text

interface Text : CharacterData {
  Text splitText(unsigned long offset);
  readonly attribute DOMString wholeText;
  Text replaceWholeText(DOMString data);
};

splitText

The contiguous Text nodes of a node are the node itself, the previous sibling Text node (if any) and its contiguous Text nodes, and the next sibling Text node (if any) and its contiguous Text nodes, avoiding any duplicates.

The wholeText attribute must return a concatenation of the data of the contiguous Text nodes of the context node, in tree order.

The replaceWholeText(data) method must run these steps:

  1. Remove the contiguous Text nodes of the content node.

  2. If data is not the empty string, insert a new Text node whose data is data at the place of the removed nodes, return the new Text node, and then terminate these steps.

  3. Return null.

Can we remove replaceWholeText() in favor of making wholeText no longer readonly? Do we even need this wholeText business?

4.10 Interface Comment

interface Comment : CharacterData {
};

5 Collections

A collection is an object that represents a lists of DOM nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.

If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.

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

The collection then represents a 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.

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

5.1 Interface NodeList

A NodeList object is a kind of collection. 

interface NodeList {
  getter Node item(unsigned long index);
  readonly attribute unsigned long length;
};

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 length attribute must return the number of nodes represented by the collection.

NodeLists are enumerable. Explain? for ... in

5.2 Interface HTMLCollection

The HTMLCollection interface represents a generic collection of elements.

This interface is called HTMLCollection for historical reasons. The various getters on this interface return object for interfaces that inherit from it, which return other objects for historical reasons. 

interface HTMLCollection {
readonly attribute unsigned long length;
caller getter Element item(unsigned long index);
caller getter object namedItem(DOMString name); // only returns Element
};
collection . length

Returns the number of elements in the collection.

element = collection . item(index)
collection[index]
collection(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.

element = collection . namedItem(name)
collection[name]
collection(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 in the HTML namespace can have a name for the purpose of this method; their name is given by the value of their name attribute.

The object's supported property indices are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported property indices.

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 supported property names consist of the values of the name attributes of each a, applet, area, embed, form, frame, frameset, iframe, img, and object element in the HTML namespace, represented by the collection with a name attribute, plus the list of IDs that the elements represented by the collection have.

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

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

5.3 Interface NamedNodeMap

Since attributes is the only remaining API using this interface and the tentative plan is to change Attr we also plan to remove this interface and replace it with a lightweight AttrMap or some such — http://lists.w3.org/Archives/Public/public-webapps/2010JulSep/0797.html

A NamedNodeMap object is a kind of collection, whose primary purpose is to expose Nodes by name. 

interface NamedNodeMap {
  Node getNamedItem(DOMString name);
  Node setNamedItem(Node arg);
  Node removeNamedItem(DOMString name);
  Node item(unsigned long index);
  readonly attribute unsigned long length;
  Node getNamedItemNS(DOMString namespace, DOMString localName);
  Node setNamedItemNS(Node arg);
  Node removeNamedItemNS(DOMString namespace, DOMString localName);
};

getNamedItem

setNamedItem

removeNamedItem

item

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

getNamedItemNS

setNamedItemNS

removeNamedItemNS

6 Lists

6.1 Interface DOMStringList

Only HTMLPropertiesCollection.names, DataTranser.types, Clipboard.types, and Document.styleSheetSets seem to use this API. Should they use something like DOMString[] instead if Web IDL introduces that? 

interface DOMStringList {
  readonly attribute unsigned long length;
  getter DOMString item(unsigned long index);
  boolean contains(DOMString string);
};

The DOMStringList interface represents an interface to an ordered list of strings.

stringlist . length

Returns the number of tokens in the string.

string = stringlist . item(index)
stringlist[index]

Returns the string with index index.

Returns null if index is out of range.

hasstring = stringlist . contains(string)

Returns true if the string is present; false otherwise.

The length attribute must return the number of strings in the list.

The object's supported property indices are the numbers in the range zero to length−1, unless the length is zero, in which case there are no supported property indices.

The item(index) method must return the indexth string in the list. If index is equal to or greater than the number of strings, then the method must return null.

The contains(string) method must return true if the list of strings contains string, or false otherwise.

6.2 Interface DOMTokenList

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(unsigned long index);
  boolean contains(DOMString token);
  void add(DOMString token);
  void remove(DOMString token);
  boolean toggle(DOMString token);
  stringifier DOMString ();
};
tokenlist . length

Returns the number of tokens in the string.

element = tokenlist . item(index)
tokenlist[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.

hastoken = tokenlist . 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.

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

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

hastoken = tokenlist . 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.

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

The object's supported property indices are the numbers in the range zero to length−1, unless the length is zero, in which case there are no supported property indices.

The item(index) method must split the underlying string on spaces, preserving the order of the tokens as found in the underlying string, 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.

For example, if the string is "a b a c" then there are four tokens: the token with index 0 is "a", the token with index 1 is "b", the token with index 2 is "a", and the token with index 3 is "c".

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

  1. If the token argument is the empty string, then raise a SYNTAX_ERR exception and stop the algorithm.
  2. If the token argument contains any space characters, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
  3. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
  4. If the token indicated by token is a case-sensitive match for one of the tokens in the object's underlying string then return true and stop this algorithm.
  5. Otherwise, return false.

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

  1. If the token argument is the empty string, then raise a SYNTAX_ERR exception and stop the algorithm.
  2. If the token argument contains any space characters, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
  3. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
  4. If the given token is a case-sensitive match for one of the tokens in the DOMTokenList object's underlying string then stop the algorithm.
  5. Otherwise, if the DOMTokenList object's underlying string is not the empty string and the last character of that string is not a space character, then append a U+0020 SPACE character to the end of that string.
  6. 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 is the empty string, then raise a SYNTAX_ERR exception and stop the algorithm.
  2. If the token argument contains any space characters, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
  3. Otherwise, remove the given token from the underlying string.

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

  1. If the token argument is the empty string, then raise a SYNTAX_ERR exception and stop the algorithm.
  2. If the token argument contains any space characters, then raise an INVALID_CHARACTER_ERR exception and stop the algorithm.
  3. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
  4. If the given token is a case-sensitive match for 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.
  5. Otherwise, if the DOMTokenList object's underlying string is not the empty string and the last character of that string is not a space character, then append a U+0020 SPACE character to the end of that string.
  6. Append the value of token to the end of the DOMTokenList object's underlying string.
  7. Return true.

Objects implementing the DOMTokenList interface must stringify to the object's underlying string representation.

6.3 Interface DOMSettableTokenList

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;
};
tokenlist . value

Returns the underlying string.

Can be set, to change the underlying string.

An object implementing the DOMSettableTokenList interface must act as defined for the DOMTokenList interface, except for the value attribute defined here.

The value attribute must return the underlying string and, on setting must replace the underlying string with the new value.

7 Historical

DOMString and DOMTimeStamp originally defined in DOM Level 3 Core are now defined in Web IDL.

The remainder of interfaces and interface members listed in this section are part of DOM Level 3 Core. Implementations conforming to this specification will however not support them.

Interfaces:

Interface members:

Node

normalize()

isSupported

getFeature()

getUserData()

setUserData()

Document

createCDATASection()

createAttribute()

createAttributeNS()

inputEncoding

xmlEncoding

xmlStandalone

xmlVersion

strictErrorChecking

domConfig

normalizeDocument()

renameNode()

DOMImplementation

getFeature()

Attr

schemaTypeInfo

isId

Element

getAttributeNode()

getAttributeNodeNS()

setAttributeNode()

removeAttributeNode()

schemaTypeInfo

setIdAttribute()

setIdAttributeNS()

setIdAttributeNode()

DocumentType

entities

notations

internalSubset

Text

isElementContentWhitespace

References

All references are normative unless marked "Non-normative".

[HTML]
(Non-normative) HTML, I. Hickson. WHATWG.
[MATHML]
(Non-normative) Mathematical Markup Language (MathML), D. Carlisle, P. Ion, R. Miner, N. Poppelier. W3C.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF.
[SVG]
(Non-normative) Scalable Vector Graphics (SVG), O. Andersson, R. Berjon, E. Dahlström, A. Emmons, J. Ferraiolo, A. Grasso, V. Hardy, S. Hayman, D. Jackson, C. Lilley, C. McCormack, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear. W3C.
[WEBIDL]
Web IDL, C. McCormack, S. Weinig. W3C.
[XML]
Extensible Markup Language, T. Bray, J. Paoli, C. Sperberg-McQueen, E. Maler, F. Yergeau. W3C.
[XMLNS]
Namespaces in XML, T. Bray, D. Hollander, A. Layman, R. Tobin. W3C.

Acknowledgements

Thanks to Dethe Elza, Jonas Sicking, and Henri Sivonen for their useful comments.

Special thanks to Geoffrey Sneddon, Ms2ger, and Simon Pieters for editing the initial 80% of this specification and their useful comments.

Special thanks also to Ian Hickson for first specifying some parts of this specification in HTML and his useful comments. [HTML]