Web DOM Core

Abstract

Web DOM Core 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.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the 7 October 2010 W3C Working Draft of Web DOM Core. Please send comments to public-webapps@w3.org (archived) with [DOMCore] at the start of the subject line.

This document is produced by the Web Applications (WebApps) Working Group as First Public Working Draft. The WebApps Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

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 Element
      1. 4.4.1 Interface Attr
   5. 4.5 Interface DocumentType
   6. 4.6 Interface ProcessingInstruction
   7. 4.7 Interface CharacterData
   8. 4.8 Interface Text
   9. 4.9 Interface Comment
7. 5 Collections
   1. 5.1 Interface NodeList
   2. 5.2 Interface HTMLCollection
8. 6 Lists
   1. 6.1 Interface DOMStringList
   2. 6.2 Interface DOMTokenList
   3. 6.3 Interface DOMSettableTokenList
9. 7 Historical
10. References
    1. Normative references
    2. Informative references
11. Acknowledgements

Goals

• Align DOM Core with needs of ECMAScript where possible.
• Align DOM Core with existing implementations.
• Simplify DOM Core as much as possible.
• Import bits of HTML5 that ought to be in DOM Core.
• Prevent a dependency on HTML5.

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

• Node.baseURI
• Node.compareDocumentPosition
• Document.documentURI
• Move DOMStringMap here?
• Move Document.charset / Document.characterSet / Document.defaultCharset here?

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 (known as tokens) 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.

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 Document or 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. Also copy the following, depending on the node:

   Element

   Its namespace, namespace prefix, local name, and its associated collection of Attr objects.

   Text

   Comment

   Its data.

   ProcessingInstruction

   Its target and data.

   Any other node

   —

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

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

4 Nodes

4.1 Interface Node

interface Node {
  const unsigned short ELEMENT_NODE = 1;
  const unsigned short ATTRIBUTE_NODE = 2; // historical
  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;

  readonly attribute DOMString baseURI;

  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;

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

           attribute DOMString nodeValue;
           attribute DOMString textContent;
  Node insertBefore([NoNull] Node newChild, Node refChild);
  Node replaceChild([NoNull] Node newChild, [NoNull] Node oldChild);
  Node removeChild([NoNull] Node oldChild);
  Node appendChild([NoNull] Node newChild);

  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 (historical)
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.

Text

"#text".

ProcessingInstruction

The context node's target attribute.

Comment

"#comment".

Document

"#document".

DocumentType

The context node's name attribute.

DocumentFragment

"#document-fragment".

The baseURI attribute must ...

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 does not have a parent node, return null and terminate these steps.

2. 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 does not have a previous sibling node, return null and terminate these steps.

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

The nextSibling attribute must run these steps:

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

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

These are the constants compareDocumentPosition() returns.

1. DOCUMENT_POSITION_DISCONNECTED
2. DOCUMENT_POSITION_PRECEDING
4. DOCUMENT_POSITION_FOLLOWING
8. DOCUMENT_POSITION_CONTAINS
16. DOCUMENT_POSITION_CONTAINED_BY
32. DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC

The compareDocumentPosition(other) method must ...

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

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:

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

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

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 insertBefore(newChild, refChild) method must run these steps:

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

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

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

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

10. Return newChild.

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

1. If the context node is a Text node, then raise a HIERARCHY_REQUEST_ERR 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. 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. Let refChild be oldChild's nextSibling.

8. Remove oldChild from the context node.

9. 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 not a child of the context node, then raise a NOT_FOUND_ERR exception and terminate these steps.

2. Remove oldChild from the context node.

3. Return oldChild.

The appendChild(newChild) method must run these steps:

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

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

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

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

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

6. Append newChild to the context node.

7. Return newChild.

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:

• node is not null.

• node's nodeType is the same as the context node's nodeType.

• node's nodeName is the same as the context node's nodeName.

• node's nodeValue is the same as the context node's nodeValue.

• The following are also equal, depending on node:

  DocumentType

  Its name, public ID, and system ID.

  Element

  Its namespace, namespace prefix, local name, and its associated collection of Attr objects.

  Text

  Comment

  Its data.

  ProcessingInstruction

  Its target and data.

  Any other node

  —

• node's childNodes' length is the same as the context node's childNodes' length.

• Calling isEqualNode on each child node of the context node, with the child node of the same index in node as argument returns true for every child node.

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 locating 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 locating 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 DOMImplementation implementation;
           attribute DOMString documentURI;
  readonly attribute DOMString compatMode;

  readonly attribute DocumentType doctype;
  readonly attribute Element documentElement;
  NodeList getElementsByTagName(DOMString qualifiedName);
  NodeList getElementsByTagNameNS(DOMString namespace, DOMString localName);
  NodeList getElementsByClassName(DOMString classNames);
  Element getElementById(DOMString elementId);

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

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

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]

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.

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

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

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 doctype attribute must return the child of the Document node that is a DocumentType node, if there is one, or null otherwise.

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

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:

   • Element nodes in the HTML namespace whose local name is localName converted to lowercase.
   • Element nodes, not in the HTML namespace, whose local name is localName.

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

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

Thus, in an HTML document, document.getElementsByTagName("FOO") will match FOO elements that are not 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.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

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.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

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

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

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 to the context node.

5. Return node.

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.

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.

4.4 Interface Element

interface Element : Node {
  readonly attribute DOMString namespaceURI;
  readonly attribute DOMString prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString tagName;

  readonly attribute Attr[] attributes;
  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);

  readonly attribute HTMLCollection children;
  NodeList getElementsByTagName(DOMString qualifiedName);
  NodeList getElementsByTagNameNS(DOMString namespace, DOMString localName);
  NodeList getElementsByClassName(DOMString classNames);
};

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 also have an associated collection of Attr objects, often called attributes.

Element nodes can have a unique identifier (ID) and classes associated with them.

I think rather than leaving this up to markup specifications we should just state that id="" sets the ID and class="" sets the classes. We can then also define Element.id, Element.className, and Element.classList here. It would simplify a lot of stuff.

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 namespaceURI attribute must return the context node's namespace.

The prefix attribute must return the context node's namespace prefix.

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

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 attributes attribute must return a read only array of the context node's associated Attr objects.

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 Attr in the context node's attributes whose qualified name is name, if the Attr is present, or null otherwise.

The getAttributeNS(namespace, localName) method must return the value of the Attr in the context node's attributes whose namespace is namespace and local name is localName, if the Attr 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. If the context node is in the HTML namespace and its ownerDocument is an HTML document, let qualifiedName be converted to lowercase.

3. If qualifiedName starts with "xmlns", raise a NAMESPACE_ERR and terminate these steps.

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

5. Otherwise, set the value of the first Attr object in the context node's attributes whose qualified name is qualifiedName, to value.

The setAttributeNS(namespace, 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. 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. If the node does not have an Attr object whose namespace is namespace and local name is localName, create an Attr object, whose namespace is namespace, namespace prefix is prefix, local name is localName, and value is value. Append this object to the context node's attributes, as its last item.

9. Otherwise, set the value of the Attr object in the context node's attributes whose namespace is namespace, and local name is localName, to value, and set its namespace prefix to prefix.

The removeAttribute(qualifiedName) method must remove the first Attr object in the context node's attributes whose qualified name is qualifiedName.

The removeAttributeNS(namespace, localName) method must remove the Attr object in the context node's attributes whose namespace is namespace and local name is localName

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 Attr whose qualified name is qualifiedName, or false otherwise.

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

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.

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.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

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.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

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.

When invoked with the same argument the same NodeList object may be returned as returned by an earlier call.

4.4.1 Interface Attr

interface Attr {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString name;
           attribute DOMString value;
};

Just like Element nodes, Attr objects have an associated namespace, namespace prefix, local name, and qualified name.

When an Attr object is created its local name is always given. Unless explicitly given when an Attr object 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.

Attr objects also have an associated value, which is always given when an Attr object is created.

The namespaceURI attribute must return the namespace.

The prefix attribute must return the namespace prefix.

The localName attribute must return the local name.

The name attribute must return the qualified name.

The value attribute must return the value.

Setting the value attribute must set value to the given value.

4.5 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.6 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.7 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.8 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 context 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.9 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:

• It is an a, applet, area, embed, form, frame, frameset, iframe, img, or object element, in the HTML namespace, with a name attribute equal to key, or,
• It is an element with an ID equal to key.

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

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.

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.

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:

• CDATASection
• DOMConfiguration
• DOMError
• DOMErrorHandler
• DOMImplementationList
• DOMImplementationSource
• DOMLocator
• DOMObject
• DOMUserData
• Entity
• EntityReference
• NamedNodeMap
• NameList
• Notation
• TypeInfo
• UserDataHandler

Interface members:

Node

hasAttributes()

attributes

namespaceURI

prefix

localName

normalize()

isSupported

getFeature()

getUserData()

setUserData()

Document

createCDATASection()

createAttribute()

createAttributeNS()

inputEncoding

xmlEncoding

xmlStandalone

xmlVersion

strictErrorChecking

domConfig

normalizeDocument()

renameNode()

DOMImplementation

getFeature()

Attr

No longer inherits from Node and therefore completely changed.

Element

getAttributeNode()

getAttributeNodeNS()

setAttributeNode()

removeAttributeNode()

schemaTypeInfo

setIdAttribute()

setIdAttributeNS()

setIdAttributeNode()

DocumentType

entities

notations

internalSubset

Text

isElementContentWhitespace

References

Normative references

Informative references

Acknowledgements

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

Special thanks to Sam 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]