Web DOM Core

Issues

• This specification like DOM3Core currently talks about name. Specifications mostly use qualifiedName for DOM1Core methods. We should too.
• Should define how XML maps to the DOM. Infoset?! And prolly how the DOM maps to XML. Maybe by using HTML5 XHTML5 section.
• innerHTML etc on all Elements public-html/2007Aug/0778.html public-webapi/2007Aug/0070.html
• \0 http://krijnhoetmer.nl/irc-logs/whatwg/20080321#l-312
• [Reflect] http://krijnhoetmer.nl/irc-logs/whatwg/20090622#l-90
• Perhaps we should move DOMStringMap to this spec...

Abstract

This specification defines the DOM Core part of the Web platform. The Document Object Model is a language- and platform neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. Web DOM Core mostly subsets DOM3 Core, but redefines some things and adds some features that were widely implemented already.

Table of contents

List of tables

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.

Common infrastructure

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

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.

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

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.

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

Common microsyntaxes

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.

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.

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.

Cloning nodes

When a UA is to clone a node, with a new ownerDocument and with a clone children flag, it must run the following steps:

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 type of node according to the following table:

   Cloned attributes

   Type of node	Attributes
   Element	—
   Attr	value
   Text	data
   ProcessingInstruction	target, data
   Comment	data
   DocumentFragment	—

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.

Legal hierarchy

Simon says this section is buggy. Should we just remove it?

A Node is said to have a legal hierarchy if all the following conditions are true:

• The Node is a Document node or an Attr node and has no parent node.

• The Node is a Document node and has no child Text nodes.

• The Node is a Document node and has no more than one child Element node.

• The Node is an Attr node, a Text node, a ProcessingInstruction node, a Comment node, or a DocumentType node, and has no child nodes.

Before running the steps of an algorithm of a method or attribute in this specification, the user agent must check that running the algorithm will result in a legal hierarchy. If it won't, then the user agent must instead raise a HIERARCHY_REQUEST_ERR exception.

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

Basic types

A DOMTimeStamp represents a number of milliseconds.

typedef unsigned long long DOMTimeStamp;

Exceptions

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 DATA_CLONE_ERR = 24;
  unsigned short code;
  DOMString message;
  DOMString name;
};

The code exception member 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 not result in a legal hierarchy;
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. DATA_CLONE_ERR: the object can not be cloned;

The message exception member must return a user-agent-defined human-readable string describing the exception.

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

Nodes

Interface Node

interface Node {

  // NodeType
  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 DOMString nodeName;
           attribute DOMString nodeValue;
  readonly attribute unsigned short nodeType;
  readonly attribute Node parentNode;
  readonly attribute Element parentElement;
  readonly attribute NodeList childNodes;
  readonly attribute Node firstChild;
  readonly attribute Node lastChild;
  readonly attribute Node previousSibling;
  readonly attribute Node nextSibling;
  readonly attribute NamedNodeMap attributes;
  readonly attribute Document ownerDocument;
  Node insertBefore(Node newChild, Node refChild);
  Node replaceChild(Node newChild, Node oldChild);
  Node removeChild(Node oldChild);
  Node appendChild(Node newChild);
  boolean hasChildNodes();
  Node cloneNode(boolean deep);
  boolean isSupported([TreatNullAs=EmptyString] DOMString feature, DOMString version);
  readonly attribute DOMString namespaceURI;
  readonly attribute DOMString prefix;
  readonly attribute DOMString localName;
  boolean hasAttributes();
  readonly attribute DOMString baseURI;

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

  [TreatNullAs=EmptyString] attribute DOMString textContent;

  boolean isSameNode(Node other);
  boolean isEqualNode(Node arg);

  DOMString lookupPrefix(DOMString namespace);
  boolean isDefaultNamespace(DOMString namespace);
  DOMString lookupNamespaceURI(DOMString prefix);
};

These are the constants nodeType (as defined below) returns. The constants marked historical can no longer be returned, but are still exposed.

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 nodeName, nodeValue and nodeType attributes must return what is in the second, third and fourth column, respectively, on the same row that lists, in the first column, the interface the context node implements:

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 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 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 ownerDocument attribute must return the Document node that the context node is associated with, or null if there is none.

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

4. If newChild's ownerDocument is not equal to the context node's ownerDocument, call the context node's ownerDocument adoptNode method with newChild as its argument.

5. If newChild is a DocumentFragment node, then while newChild's firstChild is not null, call insertBefore on the context node with newChild's firstChild as first argument and refChild as second argument.

6. Otherwise, if refChild is null, append newChild to the context node.

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

8. Return newChild.

The replaceChild(newChild, oldChild) method must run the following 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 newChild's ownerDocument is not equal to the context node's ownerDocument, call the context node's ownerDocument adoptNode method with newChild as its argument.

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

5. Let refChild be oldChild's nextSibling.

6. Remove oldChild from context node.

7. Call insertBefore on the context node with newChild and refChild as arguments, respectively.

8. Return newChild.

The removeChild(oldChild) method must run the following 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 abort these steps.

3. Remove oldChild from context node.

4. Return oldChild.

The appendChild(newChild) method must run the following 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's ownerDocument is not equal to the context node's ownerDocument, call the context node's ownerDocument adoptNode method with newChild as its argument.

4. Append newChild to the context node.

5. Return newChild.

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

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 isSupported(feature, version) method must return true if the user agent supports the (feature, version) tuple on the context node, and false otherwise.

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 hasAttributes() method must return whether there are any attributes associated with the context node, if it is an Element node, and false otherwise.

The baseURI attribute must ...

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 textContent attribute must return a concatenation of the data of all the descendant Text nodes of the context node, in tree order. On setting, it must run these steps:

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

2. Let data be the value being assigned.

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

What does null mean? http://www.w3.org/mid/c9e12660808271343v58990698gabac29d2123a82ce@mail.gmail.com

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

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

• otherNode is not null.

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

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

• otherNode's localName is the same as the context node's localName.

• otherNode's namespaceURI is the same as the context node's namespaceURI.

• otherNode's prefix is the same as the context node's prefix.

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

• Either otherNode's attributes and the context node's attributes are both null or a bijection exists between the set of otherNode's attributes and the set of the context node's attributes so that every Attr node in the former is mapped to an Attr node in the latter for which calling isEqualNode on the first Attr node with the second Attr node as its argument returns true.

• otherNode'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 otherNode as argument returns true for every child node.

The lookupPrefix(namespace) method must ...

The isDefaultNamespace(namespace) method must ...

The lookupNamespaceURI(prefix) method must ...

clarify lookupNamespaceURI http://www.w3.org/mid/4878DFC6.40401@lachy.id.au; lookupNamespaceURI, isDefaultNamespace http://html5.org/tools/web-apps-tracker?from=2125&to=2126

Interface DocumentFragment

interface DocumentFragment : Node {
};

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 importedNode, boolean deep);
  Node adoptNode(Node source);

  readonly attribute DOMString inputEncoding;
           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 the following 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 the following 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.

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

<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 restrictions on importNode do not match createElement. bug/feature?

The importNode(importedNode, deep) method must run the following steps:

1. If the context node is an XML document, then if importedNode or any of its descendant nodes or any of its attributes or any of the attributes of any descendant Element nodes has a localName which either does not match the Name production in XML or contains a U+003A COLON (":") character, raise an INVALID_STATE_ERR and abort these steps.

2. Return a clone of importedNode, with new ownerDocument being the context node, and the clone children flag set if deep is true.

The adoptNode(source) method must run the following steps:

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

2. If the context node is an XML document, then if source or any of its descendant nodes or any of its attributes or any of the attributes of any descendant Element nodes has a localName which either does not match the Name production in XML or contains a U+003A COLON (":") character, raise an INVALID_STATE_ERR and abort these steps.

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

4. If source's parentNode is not null and its ownerDocument isn't equal to the context node, remove source from its parent.

5. Set source's ownerDocument to the context node.

6. If source is an Element node, set the ownerDocument of all Attr in its attributes to the context node.

7. For each child node of source, call adoptNode on the context node, with the child node as its argument.

8. Return source.

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.

inputEncoding

define HTML5 concept of document character encoding here

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

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.

Interface Attr

Free Attr from Node? Hixie suggests nuking from orbit, including .attributes. Anyone interested in implementing and figuring out what breaks? Would certainly clean things up.

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 same value as the textContent IDL attribute on the context node, and on setting, must act as if the textContent IDL attribute on the context node had been set to the new 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.

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

           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. Or a NodeList?

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.

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.

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

Interface Text

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

splitText

wholeText

replaceWholeText

Interface Comment

interface Comment : CharacterData {
};

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.

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

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 object item(unsigned long index); // only returns Element
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.

Interface NamedNodeMap

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

Lists

Interface DOMStringList

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

item

length

contains

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.

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.

Historical

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

Interfaces:

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

Interface members:

Node

normalize()

getFeature()

getUserData()

setUserData()

Document

createCDATASection()

createAttribute()

createAttributeNS()

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

Acknowledgements

Thanks to Anne van Kesteren, Dethe Elza, and Henri Sivonen, for their useful comments.

Special thanks to Ian Hickson for first specifying some parts of this specification in HTML. HTML