W3C

DOM Core

W3C Working Draft 31 May 2011

This Version:
http://www.w3.org/TR/2011/WD-domcore-20110531/
Latest Version:
http://www.w3.org/TR/domcore/
Latest Editor's Draft:
http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html
Previous Versions:
http://www.w3.org/TR/2010/WD-domcore-20101007/
Editors:
Anne van Kesteren (Opera Software ASA) <annevk@opera.com>
Ms2ger (Mozilla Foundation) <ms2ger@gmail.com>

Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

DOM Core defines the event and document model the Web platform uses. 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 31 May 2011 W3C Working Draft of DOM Core. Please send comments to www-dom@w3.org (archived) with [DOMCore] at the start of the subject line.

This document is produced by the Web Applications (WebApps) Working Group. 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 Conformance
    1. 1.1 Dependencies
    2. 1.2 Extensibility
  4. 2 Terminology
    1. 2.1 Trees
    2. 2.2 Strings
    3. 2.3 Common microsyntaxes
      1. 2.3.1 Common parser idioms
      2. 2.3.2 Space-separated tokens
    4. 2.4 Namespaces
  5. 3 Exceptions
    1. 3.1 Exception DOMException
  6. 4 Events
    1. 4.1 Interface Event
    2. 4.2 Interface CustomEvent
    3. 4.3 Interface EventTarget
    4. 4.4 Creating Events
    5. 4.5 Dispatching Events
    6. 4.6 Firing Events
    7. 4.7 Mutation events
  7. 5 Nodes
    1. 5.1 Nodes Model
    2. 5.2 Cloning nodes
    3. 5.3 Interface Node
    4. 5.4 Interface DocumentFragment
    5. 5.5 Interface Document
      1. 5.5.1 Interface DOMImplementation
    6. 5.6 Interface Element
      1. 5.6.1 Interface Attr
    7. 5.7 Interface DocumentType
    8. 5.8 Interface ProcessingInstruction
    9. 5.9 Interface CharacterData
    10. 5.10 Interface Text
    11. 5.11 Interface Comment
  8. 6 Collections
    1. 6.1 Interface NodeList
    2. 6.2 Interface HTMLCollection
  9. 7 Lists
    1. 7.1 Interface DOMStringList
    2. 7.2 Interface DOMTokenList
    3. 7.3 Interface DOMSettableTokenList
  10. 8 DOM features
  11. 9 Historical
    1. 9.1 DOM Events
    2. 9.2 DOM Core
    3. 9.3 HTML
  12. References
    1. Normative references
    2. Informative references
  13. Acknowledgements

Goals

The goal of this specification is taking all of DOM Level 3 Core and the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events (specific type of events do not belong in the base specification) and do the following: [DOM3CORE] [DOM3EVENTS]

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

Issues

1 Conformance

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

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

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

2 Terminology

The term context object means the object on which the method or attribute being discussed was called. When the context object is unambiguous, the term can be omitted.

2.1 Trees

Just like most programming paradigms the Web platform has finite hierarchical tree structures, simply named trees.

An object that participates in a tree has a parent, which is either another object or null, and an ordered list of zero or more child objects.

An object whose parent is null is called the root object.

An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.

An object A is called an ancestor of an object B if and only if B is a descendant of A.

An object A is called a sibling of an object B, if and only if B and A share the same non-null parent. A is a preceding sibling of B if A and B are siblings and A comes before B in their shared parent. A is a following sibling of B if A and B are siblings and A comes after B in their shared parent.

The term tree order means a pre-order, depth-first traversal of a tree.

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

A string pattern is a prefix match for a string s when pattern is not longer than s and truncating s to pattern's length leaves the two strings as matches of each other.

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

2.3 Common microsyntaxes

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

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

An unordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated.

An ordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated but where the order of the tokens is meaningful.

Sets of space-separated tokens sometimes have a defined set of allowed values. When a set of allowed values is defined, the tokens must all be from that list of allowed values; other values are non-conforming. If no such set of allowed values is provided, then all values are conforming.

How tokens in a set of space-separated tokens are to be compared (e.g. case-sensitively or not) is defined on a per-set basis.

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

  1. Let input be the string being parsed.

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

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

  4. Skip whitespace.

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

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

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

    3. Skip whitespace.

  6. Return tokens.

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

  1. Let input be the string being modified.

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

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

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

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

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

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

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

    3. Return to the step labeled loop.

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

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

    1. Skip whitespace (in input).

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

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

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

  10. Return to the step labeled loop.

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

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

3 Exceptions

3.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;
  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 INVALID_NODE_TYPE_ERR = 24;
  const unsigned short DATA_CLONE_ERR = 25;
  unsigned short code;
  DOMString name;
};

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

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

4 Events

This chapter provides an alternative definition for the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events. We would appreciate your input on which approach you prefer.

4.1 Interface Event

interface Event {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? currentTarget;

  const unsigned short CAPTURING_PHASE = 1;
  const unsigned short AT_TARGET = 2;
  const unsigned short BUBBLING_PHASE = 3;
  readonly attribute unsigned short eventPhase;

  void stopPropagation();
  void stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
  void preventDefault();
  readonly attribute boolean defaultPrevented;

  readonly attribute boolean isTrusted;
  readonly attribute DOMTimeStamp timeStamp;

  void initEvent(DOMString type, boolean bubbles, boolean cancelable);
};

An event allows for signaling that something has occurred. E.g. that an image has completed downloading.

Each event has a type which is initially the empty string. The type attribute must return the type.

Each event has an associated target and current target which are both initially null and then set while dispatching the event. The target attribute must return the target and the currentTarget attribute must return the current target.

Each event has a phase. The eventPhase attribute must return the current phase, which must be one of the following:

CAPTURING_PHASE (numeric value 1)

When an event is dispatched on an object that participates in a tree it will be in this phase before it reaches its target.

AT_TARGET (numeric value 2)

When an event is dispatched it will be in this phase on its target.

BUBBLING_PHASE (numeric value 3)

When an event is dispatched on an object that participates in a tree it will be in this phase after it reaches its target.

Initially the phase is AT_TARGET.

Each event has the following associated flags that are all initially unset:

When the stopPropagation() method is invoked the stop propagation flag must be set.

When the stopImmediatePropagation() method is invoked both the stop propagation flag and stop immediate propagation flag must be set.

The bubbles attribute must return true if the bubble flag is set and false otherwise.

The cancelable attribute must return true if the cancel flag is set and false otherwise.

When the preventDefault() method is invoked and the cancel flag is set, the canceled flag must be set.

The defaultPrevented attribute must return true if the canceled flag is set and false otherwise.

The isTrusted attribute must return true if the trusted flag is set and false otherwise.

The timeStamp attribute ... More information.

When the initEvent(type, bubbles, cancelable) method is invoked these steps must be run:

  1. Set the initialized flag.

  2. If the dispatch flag is set, terminate these steps.

  3. Unset the stop propagation flag, stop immediate propagation flag, canceled flag, and trusted flag.

  4. Set target to null.

  5. Set type to the type argument.

  6. If the bubbles argument is true, set the bubble flag.

  7. If the cancelable argument is true, set the cancel flag.

4.2 Interface CustomEvent

interface CustomEvent : Event {
  readonly attribute object? detail;
  void initCustomEvent(DOMString type, boolean bubbles, boolean cancelable, object? detail);
};

Events using the CustomEvent interface can be used for synthetic events that need to carry data.

Events using the CustomEvent interface have an associated detail variable. The detail attribute must return detail, if it is set, and null otherwise.

When the initCustomEvent(type, bubbles, cancelable, detail) method is invoked these steps must be run:

  1. If the dispatch flag is set, terminate these steps.

  2. Invoke initEvent() with the first three arguments.

  3. Set detail to the detail argument.

4.3 Interface EventTarget

interface EventTarget {
  void addEventListener(DOMString type, EventListener? listener, optional boolean capture);
  void removeEventListener(DOMString type, EventListener? listener, optional boolean capture);
  boolean dispatchEvent(Event event);
};

[Callback] interface EventListener {
  void handleEvent(Event event);
};

EventTarget is an object upon which an event is dispatched when something has occurred. Each EventTarget has an associated list of event listeners.

An event listener is a handler for a specific event. Each event listener consists of a name (of the event), listener, and capture variable.

When the addEventListener(type, listener, capture) method is invoked these steps must be run:

  1. If listener is null terminate these steps.

  2. If capture is omitted let capture be false.

  3. Append an event listener to the associated list of event listeners with name set to type, listener set to listener, and capture set to capture, unless there already is an event listener in that list with the same name, listener, and capture.

When the removeEventListener(type, listener, capture) method is invoked these steps must be run:

  1. If capture is omitted let capture be false.

  2. Remove an event listener from the associated list of event listeners, whose name is name, listener is listener, and capture is capture.

When the dispatchEvent(event) method is invoked these steps must be run:

  1. If event's dispatch flag is set, or if its initialized flag isn't set, throw an INVALID_STATE_ERR exception and terminate these steps.

  2. Unset event's trusted flag.

  3. Dispatch the event and return the value that returns.

4.4 Creating Events

Although the Document object is introduced later it was thought better to describe its createEvent() method here.

When the createEvent(interface) methed is invoked these steps must be run:

  1. If interface is an ASCII case-insensitive match for any of the strings in the first column in the following table let interface be the string in the second column on the same row as the matching string:

    Input interface Replacement interface
    "htmlevents""event"
    "mouseevents""mouseevent"
    "mutationevents""mutationevent"
    "uievents""uievent"

  2. If interface is not an ASCII case-insensitive match for "event" or for the name of an interface that inherits from the Event interface and is supported by the user agent, throw a NOT_SUPPORTED_ERR and terminate these steps.

  3. Create an event implementing the interface whose name interface is an ASCII case-insensitive match for and return it.

Because createEvent() is located on the Document object it cannot be used by Web Workers. Please let us know if this bothers you.

4.5 Dispatching Events

To dispatch an event on a given object run these steps:

  1. Let event be the event that is dispatched.

  2. Set event's dispatch flag.

  3. Set event's target to the object on which event is dispatched.

  4. If event's target is participating in a tree

    1. Let event path be a static ordered list of all ancestors of event's target in tree order.

    2. Set event's phase to CAPTURING_PHASE.

    3. For each object in the event path invoke its event listeners, as long as event's stop propagation flag is unset.

    4. Set event's phase to AT_TARGET.

    5. Invoke the event listeners of event's target, if event's stop propagation flag is unset.

    6. If event's bubble flag is set run these substeps:

      1. Reverse the order of event path.

      2. Set event's phase to BUBBLING_PHASE.

      3. For each object in the event path invoke its event listeners, as long as event's stop propagation flag is unset.

    Otherwise

    Invoke the event listeners of event's target.

  5. Unset event's dispatch flag.

  6. Set event's phase to AT_TARGET.

  7. Set event's current target to null.

  8. Return false if event's canceled flag is set and true otherwise.

To invoke the event listeners for an object run these steps:

  1. Let event be the event for which the event listeners are invoked.

  2. Let listeners be a static list of the event listeners associated with the object for which these steps are run.

  3. Set event's current target to the object for which these steps are run.

  4. Then run these substeps for each event listener in listeners:

    1. If event's stop immediate propagation flag is set, terminate the invoke algorithm.

    2. Let listener be the event listener.

    3. If event's type is not listener's name, terminate these substeps (and run them for the next event listener).

    4. If event's phase is CAPTURING_PHASE and listener's capture is false, terminate these substeps (and run them for the next event listener).

    5. If event's phase is BUBBLING_PHASE and listener's capture is true, terminate these substeps (and run them for the next event listener).

    6. Run listener's listener.

4.6 Firing Events

To fire an event named e means that an event using the Event interface, with its type set to e, and its trusted flag set, is to be dispatched at the indicated object.

Fire is short for initializing and dispatching an event.

Fire an event is a concept to make initializing and dispatching an event easier to write down. If the event needs its bubble flag or cancel flag set, one would write e.g. "fire an event named submit with its cancel flag set".

4.7 Mutation events

The status of mutation events is currently unclear. The editors hope they can eventually be removed from the platform. There is a proposal for a replacement. We encourage experimentation with that proposal, as well as alternative proposals.

5 Nodes

5.1 Nodes Model

Node objects (simply called nodes) participate in a tree.

The tree of nodes is constrained as follows, expressed as a relationship between the type of node and its allowed children:

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

None.

A node, or its children in case of a DocumentFragment object, are said to violate the node hierarchy of another node if inserting them within the other node's tree would violate the constraints listed above.

Operations that would cause a node to violate the node hierarchy of another node will throw a HIERARCHY_REQUEST_ERR.

The normative requirements to make this note true are not yet in place.

5.2 Cloning nodes

Specifications may define cloning steps for all or some 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, throw 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. Run any cloning steps defined for node in other applicable specifications.

  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.

5.3 Interface Node

interface Node : EventTarget {
  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(Node newChild, Node? refChild);
  Node replaceChild(Node newChild, Node oldChild);
  Node removeChild(Node oldChild);
  Node appendChild(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:

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

Element

The context object's tagName attribute.

Text

"#text".

ProcessingInstruction

The context object's target attribute.

Comment

"#comment".

Document

"#document".

DocumentType

The context object's name attribute.

DocumentFragment

"#document-fragment".

The baseURI attribute must ...

doc = node . ownerDocument

Returns the Document node belongs to.

parent = node . parentNode

Returns the parent node of node.

parent = node . parentElement

Returns the parent node of node, if it is an Element.

haschildren = node . hasChildNodes

Returns whether node has children.

children = node . childNodes

Returns the children of node.

child = node . firstChild

Returns the first child of node.

child = node . lastChild

Returns the last child of node.

child = node . previousSibling

Returns the node before node in its parent.

child = node . nextSibling

Returns the node after node in its parent.

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

The parentNode attribute must return the parent.

The parentElement attribute must return the parent element.

The hasChildNodes() method must return false if the context object has no children, or true otherwise.

The childNodes attribute must return a NodeList rooted at the context object matching only children.

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

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

The previousSibling attribute must return the first previous sibling of the context object, or null if there is none.

The nextSibling attribute must return the first next sibling of the context object, or null if there is none.

These are the constants compareDocumentPosition() returns.

The compareDocumentPosition(other) method must ...

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

Text
Comment
ProcessingInstruction

The context object's textContent attribute.

Any other node

Null.

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

Text
Comment
ProcessingInstruction

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

Any other node

Do nothing.

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

DocumentFragment
Element

The concatenation of the data attributes of all the Text object descendants of the context object, in tree order.

Text
Comment

The context object's data attribute.

ProcessingInstruction

The context object's data attribute.

Any other node
Null.

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

DocumentFragment
Element

  1. Remove all the descendants of the context object.

  2. Let data be the given value.

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

Text
Comment

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

ProcessingInstruction

Set the context object'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 object is not a Document, DocumentFragment or Element, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

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

  3. If refChild is not a child of the context object, then throw a NOT_FOUND_ERR exception and terminate these steps.

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

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

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

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

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

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

  10. Return newChild.

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

  1. If the context object is not a Document, DocumentFragment or Element, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

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

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

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

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

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

  7. Let refChild be oldChild's first next sibling.

  8. Remove oldChild from the context object.

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

The removeChild(oldChild) method must run these steps:

  1. If the context object is not a Document, DocumentFragment or Element, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

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

  3. Remove oldChild from the context object.

  4. Return oldChild.

The appendChild(newChild) method must run these steps:

  1. If the context object is not a Document, DocumentFragment or Element, throw a HIERARCHY_REQUEST_ERR and terminate these steps.

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

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

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

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

  6. If newChild is a DocumentFragment node, append the children of newChild to the context object, in tree order.

  7. Otherwise, append newChild to the context object.

  8. Return newChild.

new node = node . cloneNode(deep)

Returns a copy of the node, with its relevant node-specific data. If deep is true, the copy also includes the node's children.

same = node . isSameNode(other)

Returns whether node and other are the exact same node.

similar = node . isEqualNode(other)

Returns whether node and other have the same properties.

The cloneNode(deep) method must return a clone of the context object, with new ownerDocument being the context object'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 object, and false otherwise.

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

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

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

  2. If, in element's attributes, there is an Attr 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 parent element using namespace, if that is not null, 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, in its attributes, there is an Attr 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 parent element using prefix, if that is not null, 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 parent element using prefix, if that is not null, 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 object:

    Element

    Return the result of locating 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 parent element, or if that is null, null.

The lookupNamespaceURI(prefix) method must return the result of running locate a namespace for the context object 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 object.

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

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

5.4 Interface DocumentFragment

interface DocumentFragment : Node {
};

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

  Event createEvent(DOMString interface);
};

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 object 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 object 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 document element.

The getElementsByTagName(localName) method must run these steps:

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

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

  3. Otherwise, return a NodeList rooted at the context object, whose filter matches only elements 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 object, whose filter matches only elements.

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

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

  4. Otherwise, return a NodeList rooted at the context object, whose filter matches only elements 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 object, 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.

Given the following XHTML fragment: 

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

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

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

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

The getElementById(elementId) method must return the first element, in tree order, within the context object's tree, 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, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

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

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

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

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

  2. If qualifiedName does not match the QName production in Namespaces in XML, throw 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, throw a NAMESPACE_ERR exception and terminate these steps.

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

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

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

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

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

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

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

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 object is an HTML document, throw a NOT_SUPPORTED_ERR exception and terminate these steps.

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

  3. If data contains the string "?>", throw 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 object.

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 object, and the clone children flag set if deep is true.

The adoptNode(node) method must run these steps:

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

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

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

  4. Set ownerDocument for node and all its descendants to the context object.

  5. Return node.

5.5.1 Interface DOMImplementation

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

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

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

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

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

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

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

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

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

This method throws the same exceptions as the createElementNS method, when invoked with the same arguments. If doctype comes from another Document, a WRONG_DOCUMENT_ERR exception is thrown.

doc = document . implementation . createHTMLDocument( title )

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

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

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

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

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

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

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

  1. Let document be a new Document node.

  2. Let element be null.

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

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

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

    2. Set the doctype's ownerDocument to document.

    3. Append doctype to document.

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

  6. Return document.

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

  1. Let doc be a newly created Document object.

  2. Mark doc as being an HTML document.

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

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

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

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

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

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

  9. Return doc.

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

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

  readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
  readonly attribute unsigned long childElementCount;
};

Element objects are simply known as elements.

Elements have an associated namespace, namespace prefix, local name.

When an element is created, its local name is always given. Unless explicitly given when an element is created, its namespace and namespace prefix are null.

Elements also have an associated collection of Attr objects, often called attributes.

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

A node's parent of type Element is known as a parent element. If the node has a parent of a different type, its parent element is null.

An element is known as the document element when its parent is of type Document.

When an element or one of its ancestors is the document element, it is in a Document.

Specifications may define base URL change steps.

When an element 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 object's namespace.

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

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

The tagName attribute must run these steps:

  1. If context object's namespace prefix is not null, let qualified name be its namespace prefix, followed by a ":" (U+003A), followed by its local name. Otherwise, let qualified name be its local name.

  2. If the context object is in the HTML namespace and its ownerDocument is an HTML document, let qualified name be converted to uppercase.

  3. Return qualified name.

The attributes attribute must return a read only array of the context object's associated Attr objects.

The getAttribute(name) method must run these steps:

  1. If the context object 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 object'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 object'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, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

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

  3. If "xmlns" is a prefix match for qualifiedName, throw a NAMESPACE_ERR and terminate these steps.

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

  5. Otherwise, set the value of the first Attr object in the context object'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, throw an INVALID_CHARACTER_ERR exception and terminate these steps.

  2. If qualifiedName does not match the QName production in Namespaces in XML, throw 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 namespace is the empty string, let namespace be null.

  5. If prefix is not null and namespace is null, throw a NAMESPACE_ERR exception and terminate these steps.

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

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

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

  9. If the context object's attributes does not contain 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 object's attributes.

  10. Otherwise, set the value of the Attr object in the context object'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 run the following steps:

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

  2. Remove the first Attr object in the context object's attributes whose qualified name is qualifiedName.

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

The hasAttribute(qualifiedName) method must run these steps:

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

  2. Return true if context object's attributes contains an Attr whose qualified name is qualifiedName, or false otherwise.

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

When the getElementsByTagName(qualifiedName) method is invoked it must return a live NodeList with the elements that the getElementsByTagName method would return when called on the context object's ownerDocument and passed the same argument, excluding any elements that are not descendants of the context object 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.

When the getElementsByTagNameNS(namespace, localName) method is invoked it must return a live NodeList with the elements that the getElementsByTagNameNS method would return when called on the context object's ownerDocument and passed the same arguments, excluding any elements that are not descendants of the context object 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.

When the getElementsByClassName(classNames) method is invoked it must return a live NodeList with the elements that the getElementsByClassName method would return when called on the context object's ownerDocument and passed the same argument, excluding any elements that are not descendants of the context object 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 children attribute must return an HTMLCollection collection, rooted at the context object, whose filter matches only elements whose parent is the context object.

The firstElementChild attribute must return the first child of the context object that is of type Element or null if there is no such node.

The lastElementChild attribute must return the last child of the context object that is of type Element or null if there is no such node.

The previousElementSibling attribute must return the first preceding sibling of the context object that is of type Element or null if there is no such node.

The nextElementSibling attribute must return the first following sibling of the context object that is of type Element or null if there is no such node.

The childElementCount attribute must return the number of children of the context node that are Elements.

5.6.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 elements, 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.

5.7 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, its 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 object's name.

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

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

5.8 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 object's target.

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

5.9 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 greater than the context object's length, throw an INDEX_SIZE_ERR exception and terminate these steps.

  2. If offset+count is greater than the context object'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 object's data.

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

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

  2. Insert data into the context object'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 object's length, throw an INDEX_SIZE_ERR exception and terminate these steps.

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

  3. Starting from offset UTF-16 code units remove count UTF-16 code units from the context object'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-throw any exceptions these methods might have thrown.

5.10 Interface Text

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

The splitText(offset) method must run the following steps:

  1. If offset is greater than the context object's length, throw an INDEX_SIZE_ERR exception and terminate these steps.
  2. Let length be the context object's length − offset.
  3. Call the context object's substringData method with offset and length as its arguments. If this threw an exception, terminate these steps. Otherwise, let new data be the value returned.
  4. Call the context object's deleteData method with offset and length as its arguments. If this threw an exception, terminate these steps.
  5. Let new node be a new Text object, with the same ownerDocument as the context object. Set new node's data to new data.
  6. Let parent be the context object's parent. If parent is null, return new node and terminate these steps.
  7. Call parent's insertBefore method with new node and the context object's first next sibling as its argument.
  8. Return new node.

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 object, in tree order.

The replaceWholeText(data) method must run these steps:

  1. Remove the contiguous Text nodes of the context object.

  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?

5.11 Interface Comment

interface Comment : CharacterData {
};

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

6.1 Interface NodeList

A NodeList object is a kind of collection. 

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

Returns the number of elements in the collection.

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

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.

6.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;
  getter Element? item(unsigned long index);
  getter object? namedItem(DOMString name); // only returns Element
};
collection . length

Returns the number of elements in the collection.

element = collection . item(index)
element = 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)
element = 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 falls into one of the following categories:

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

7 Lists

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

7.2 Interface DOMTokenList

The DOMTokenList interface represents an interface to an underlying string that consists of a set of space-separated tokens.

DOMTokenList objects are always case-sensitive, even when the underlying string might ordinarily be treated in a case-insensitive manner. 

interface DOMTokenList {
  readonly attribute unsigned long length;
  getter DOMString? item(unsigned long index);
  boolean contains(DOMString token);
  void add(DOMString token);
  void remove(DOMString token);
  boolean toggle(DOMString token);
  stringifier DOMString ();
};
tokenlist . length

Returns the number of tokens in the string.

element = tokenlist . item(index)
tokenlist[index]

Returns the token with index index. The tokens are returned in the order they are found in the underlying string.

Returns null if index is out of range.

hastoken = tokenlist . contains(token)

Returns true if the token is present; false otherwise.

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

tokenlist . add(token)

Adds token, unless it is already present.

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

tokenlist . remove(token)

Removes token if it is present.

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

hastoken = tokenlist . toggle(token)

Adds token if it is not present, or removes it if it is. Returns true if token is now present (it was added); returns false if it is not (it was removed).

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

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

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

The item(index) method must split the underlying string on spaces, preserving the order of the tokens as found in the underlying string, and then return the indexth item in this list. If index is equal to or greater than the number of tokens, then the method must return null.

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

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

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

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

  1. If the token argument is the empty string, then throw a SYNTAX_ERR exception and terminate these steps.
  2. If the token argument contains any space characters, then throw an INVALID_CHARACTER_ERR exception and terminate these steps.
  3. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
  4. If the given token is a case-sensitive match for one of the tokens in the DOMTokenList object's underlying string then terminate these steps.
  5. Otherwise, if the DOMTokenList object's underlying string is not the empty string and the last character of that string is not a space character, then append a U+0020 SPACE character to the end of that string.
  6. Append the value of token to the end of the DOMTokenList object's underlying string.

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

  1. If the token argument is the empty string, then throw a SYNTAX_ERR exception and terminate these steps.
  2. If the token argument contains any space characters, then throw an INVALID_CHARACTER_ERR exception and terminate these steps.
  3. Otherwise, remove the given token from the underlying string.

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

  1. If the token argument is the empty string, then throw a SYNTAX_ERR exception and terminate these steps.
  2. If the token argument contains any space characters, then throw an INVALID_CHARACTER_ERR exception and terminate these steps.
  3. Otherwise, split the underlying string on spaces to get the list of tokens in the object's underlying string.
  4. If the given token is a case-sensitive match for one of the tokens in the DOMTokenList object's underlying string then remove the given token from the underlying string, return false and terminate these steps.
  5. Otherwise, if the DOMTokenList object's underlying string is not the empty string and the last character of that string is not a space character, then append a U+0020 SPACE character to the end of that string.
  6. Append the value of token to the end of the DOMTokenList object's underlying string.
  7. Return true.

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

7.3 Interface DOMSettableTokenList

The DOMSettableTokenList interface is the same as the DOMTokenList interface, except that it allows the underlying string to be directly changed. 

interface DOMSettableTokenList : DOMTokenList {
            attribute DOMString value;
};
tokenlist . value

Returns the underlying string.

Can be set, to change the underlying string.

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

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

8 DOM features

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.

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.

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.

9 Historical

As explained in goals this specification attempts to update various DOM specifications. Along the way a number of changes has been made of which this section is a rough summary.

The features defined by this specification mostly originated elsewhere and have been moved here as this was deemed a more appropriate location. As such this specification includes features defined by former DOM Events and DOM Core specifications, features once defined by HTML, and features defined by the Element Traversal specification.

9.1 DOM Events

This specification only replaces the core event model and not any of the events for specific contexts (e.g. user interface events).

It makes the following changes:

9.2 DOM Core

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

Node now inherits from EventTarget.

The remainder of interfaces and interface members listed in this section were once part of DOM Core. Implementations conforming to this specification will not support them.

Interfaces:

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

9.3 HTML

A number of DOM methods behave in a special way based on the HTML namespace or HTML document variables. This specification makes that an intrinsic part of the DOM.

References

Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF.
[WEBIDL]
Web IDL, C. McCormack and S. Weinig. W3C.
[XML]
Extensible Markup Language, T. Bray, J. Paoli, C. Sperberg-McQueen et al.. W3C.
[XMLNS]
Namespaces in XML, T. Bray, D. Hollander, A. Layman et al.. W3C.

Informative references

[DOM3CORE]
Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood et al.. W3C.
[DOM3EVENTS]
Document Object Model (DOM) Level 3 Events Specification, D. Schepers and J. Rossi. W3C.
[HTML]
HTML, I. Hickson. WHATWG.

Acknowledgements

Thanks to Adrian Bateman, Cameron McCormack, Dethe Elza, David Flanagan, Glenn Maynard, Jacob Rossi, Jonas Sicking, Henri Sivonen, Ojan Vafai, Olli Pettay, and Shiki Okasaka for their useful comments.

Special thanks to Sam Sneddon and Simon Pieters for editing the initial version 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]

Finally, while this specification has been written from scratch, special thanks should also be extended to the editors of the various specifications that previously defined the features in this specification. In particular: