text:
<!DOCTYPE html>

    <meta charset="utf-8">
    <title>W3C DOM4</title>

    <link rel="stylesheet" href="style.css">
  <link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/W3C-WD">

W3C DOM4

W3C Last Call Working Draft <time class="dt-published" datetime="2014-07-10">10 July 2014</time>

This version:

http://www.w3.org/TR/2014/WD-dom-20140710/

Latest published version:

http://www.w3.org/TR/dom/

Latest editor's draft:

http://w3c.github.io/dom/

Bug tracker:

file a bug (open bugs)

Previous version:

http://www.w3.org/TR/2014/CR-dom-20140508/

Editors:

Anne van Kesteren, Mozilla (Upstream WHATWG version)

Aryeh Gregor, Mozilla (Upstream WHATWG version)

Ms2ger, Mozilla (Upstream WHATWG version)

Alex Russell, Google

Robin Berjon, W3C

        Copyright ©
        2014

        W3C®
        (MIT,
        ERCIM,
        Keio, Beihang),

          Some Rights Reserved: this document is dual-licensed,
          CC-BY and
          W3C Document License.

        W3C liability,
        trademark and

          document use

        rules apply.

Abstract

DOM defines a platform-neutral model for events and node trees.

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 document is published as a snapshot of the
        DOM Living Standard with the intent of keeping
        the differences from the original to a strict minimum, and only through subsetting (only
        things that are not implemented were removed for this publication).

        Since this document has already been through the Candidate Recommendation stage, the Working
        Group expects to advance it to Proposed Recommendation at the end of this Last Call period.

          This document was published by the HTML Working Group as a Last Call Working Draft.

            This document is intended to become a W3C Recommendation.

            If you wish to make comments regarding this document, please send them to
            www-dom@w3.org
            (subscribe,
            archives).

          The Last Call period ends 31 July 2014.

            All comments are welcome.

            Publication as a Last Call 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.

            This is a Last Call Working Draft and thus the Working Group has determined that this
            document has satisfied the relevant technical requirements and is sufficiently stable to
            advance through the Technical Recommendation process.

            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.

Table of Contents

Goals

1 Conformance

1.1 Dependencies

1.2 Extensibility

2 Terminology

2.1 Trees

2.2 Strings

2.3 Ordered sets

2.4 Namespaces

3 Errors

3.1 Exception DOMException

3.2 Interface DOMError

3.3 Error names

4 Events

4.1 Introduction to "DOM Events"

4.2 Interface Event

4.3 Interface CustomEvent

4.4 Constructing events

4.5 Defining event interfaces

4.6 Interface EventTarget

4.7 Dispatching events

4.8 Firing events

5 Nodes

5.1 Introduction to "The DOM"

5.2 Node tree

5.2.1 Mutation algorithms

5.2.2 Interface NonElementParentNode

5.2.3 Interface ParentNode

5.2.4 Interface NonDocumentTypeChildNode

5.2.5 Interface ChildNode

5.2.6 Old-style collections: NodeList and HTMLCollection

5.2.6.1 Interface NodeList

5.2.6.2 Interface HTMLCollection

5.3 Mutation observers

5.3.1 Interface MutationObserver

5.3.2 Queuing a mutation record

5.3.3 Interface MutationRecord

5.3.4 Garbage collection

5.4 Interface Node

5.5 Interface Document

5.5.1 Interface DOMImplementation

5.6 Interface DocumentFragment

5.7 Interface DocumentType

5.8 Interface Element

5.8.1 Interface Attr

5.9 Interface CharacterData

5.10 Interface Text

5.11 Interface ProcessingInstruction

5.12 Interface Comment

6 Ranges

6.1 Introduction to "DOM Ranges"

6.2 Interface Range

7 Traversal

7.1 Interface NodeIterator

7.2 Interface TreeWalker

7.3 Interface NodeFilter

8 Sets

8.1 Interface DOMTokenList

8.2 Interface DOMSettableTokenList

9 Historical

9.1 DOM Events

9.2 DOM Core

9.3 DOM Ranges

9.4 DOM Traversal

References

Acknowledgments

Goals

This specification standardizes the DOM. It does so as follows:

By consolidating DOM Level 3 Core
  [DOM3CORE],
  Element Traversal
  [ELEMENTTRAVERSAL],
  Selectors API Level 2
  [SELECTORSAPI], the
  "DOM Event Architecture" and "Basic Event Interfaces" chapters of
  DOM Level 3 Events
  [DOM3EVENTS] (specific type
  of events do not belong in the base specification), and
  DOM Level 2 Traversal and Range
  [DOM2TR], and:

Aligning them with the needs of JavaScript where possible.

Aligning them with existing implementations.

Simplifying them as much as possible.

By moving features from the HTML standard that ought to be part of the DOM
 platform here. [HTML]

By defining a replacement for the "Mutation Events" and
  "Mutation Name Event Types" chapters of DOM Level 3 Events
  [DOM3EVENTS] as the old model
  was problematic.

The old model is expected to be removed from implementations
  in due course.

By defining new features that simplify common DOM operations.

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", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in RFC 2119.
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 JavaScript.

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
Encoding, Selectors, Web IDL, XML, and
Namespaces in XML.
[ENCODING]
[SELECTORS]
[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 recognize
the requirements of such an extension specification, it becomes an
<dfn id="other-applicable-specifications" title="other applicable specifications">applicable
specification</dfn> for the purposes of conformance requirements in
this specification.

2 Terminology

The term <dfn id="context-object">context object</dfn> means the object on which the algorithm,
attribute getter, attribute setter, or method being discussed was called. When the
context object is unambiguous, the term can be omitted.

2.1 Trees

A <dfn id="concept-tree" title="concept-tree">tree</dfn> is a finite hierarchical tree structure. In
<dfn id="concept-tree-order" title="concept-tree-order">tree order</dfn> is preorder, depth-first
traversal of a tree.

An object that <dfn id="concept-tree-participate" title="concept-tree-participate">participates</dfn> in
a tree has a
<dfn id="concept-tree-parent" title="concept-tree-parent">parent</dfn>, which is either another object
or null, and an ordered list of zero or more
<dfn id="concept-tree-child" title="concept-tree-child">child</dfn> objects. An object <var title="">A</var> whose
parent is object <var title="">B</var> is a
child of <var title="">B</var>.

The <dfn id="concept-tree-root" title="concept-tree-root">root</dfn> of an object is itself, if its
parent is null, or else it is the
root of its
parent.

An object <var title="">A</var> is called a
<dfn id="concept-tree-descendant" title="concept-tree-descendant">descendant</dfn> of an object
<var title="">B</var>, if either <var title="">A</var> is a
child of <var title="">B</var> or
<var title="">A</var> is a child of an
object <var title="">C</var> that is a
descendant of <var title="">B</var>.

An
<dfn id="concept-tree-inclusive-descendant" title="concept-tree-inclusive-descendant">inclusive descendant</dfn> is
an object or one of its
descendants.

An object <var title="">A</var> is called an
<dfn id="concept-tree-ancestor" title="concept-tree-ancestor">ancestor</dfn> of an object
<var title="">B</var> if and only if <var title="">B</var> is a
descendant of
<var title="">A</var>.

An <dfn id="concept-tree-inclusive-ancestor" title="concept-tree-inclusive-ancestor">inclusive ancestor</dfn> is
an object or one of its ancestors.

An object <var title="">A</var> is called a
<dfn id="concept-tree-sibling" title="concept-tree-sibling">sibling</dfn> of an object
<var title="">B</var>, if and only if <var title="">B</var> and <var title="">A</var>
share the same non-null parent.

An object <var title="">A</var> is
<dfn id="concept-tree-preceding" title="concept-tree-preceding">preceding</dfn> an object
<var title="">B</var> if <var title="">A</var> and <var title="">B</var> are in the
same tree and <var title="">A</var> comes
before <var title="">B</var> in
tree order.

An object <var title="">A</var> is
<dfn id="concept-tree-following" title="concept-tree-following">following</dfn> an object
<var title="">B</var> if <var title="">A</var> and <var title="">B</var> are in the
same tree and <var title="">A</var> comes
after <var title="">B</var> in
tree order.

The <dfn id="concept-tree-first-child" title="concept-tree-first-child">first child</dfn> of an object is
its first child or null if it has no
child.

The <dfn id="concept-tree-last-child" title="concept-tree-last-child">last child</dfn> of an object is
its last child or null if it has no
child.

The <dfn id="concept-tree-previous-sibling" title="concept-tree-previous-sibling">previous sibling</dfn> of an
object is its first preceding
sibling or null if it has no
preceding
sibling.

The <dfn id="concept-tree-next-sibling" title="concept-tree-next-sibling">next sibling</dfn> of an
object is its first following
sibling or null if it has no
following
sibling.

The <dfn id="concept-tree-index" title="concept-tree-index">index</dfn> of an object is its number
of preceding
siblings.

2.2 Strings

Comparing two strings in a <dfn id="case-sensitive">case-sensitive</dfn> manner means comparing them exactly, code point for code point.

Comparing two strings in a <dfn id="ascii-case-insensitive">ASCII case-insensitive</dfn> manner means comparing them exactly, code point for code point, 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.

<dfn id="converted-to-ascii-uppercase" title="converted to ascii uppercase">Converting a string to ASCII uppercase</dfn> means replacing all characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).

<dfn id="converted-to-ascii-lowercase" title="converted to ascii lowercase">Converting a string to ASCII lowercase</dfn> means replacing all characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) with the corresponding characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).

A string <var title="">pattern</var> is a <dfn id="prefix-match">prefix match</dfn> for a string
<var title="">s</var> when <var title="">pattern</var> is not longer than
<var title="">s</var> and truncating <var title="">s</var> to
<var title="">pattern</var>'s length leaves the two strings as matches of each
other.

2.3 Ordered sets

The <dfn id="concept-ordered-set-parser" title="concept-ordered-set-parser">ordered set parser</dfn> takes a string
<var title="">input</var> and then runs these steps:

Let <var title="">position</var> be a pointer into <var title="">input</var>,
 initially pointing at the start of the string.

Let <var title="">tokens</var> be an ordered set of tokens, initially empty.

Skip ASCII whitespace.

While <var title="">position</var> is not past the end of
 <var title="">input</var>:

Collect a code point sequence of code points that are
   not ASCII whitespace.

If the collected string is not in <var title="">tokens</var>, append the
   collected string to <var title="">tokens</var>.

Skip ASCII whitespace.

Return <var title="">tokens</var>.

To <dfn id="collect-a-code-point-sequence">collect a code point sequence</dfn> of
<var title="">code points</var>, run these steps:

Let <var title="">input</var> and <var title="">position</var> be the same
 variables as those of the same name in the algorithm that invoked these
 steps.

Let <var title="">result</var> be the empty string.

While <var title="">position</var> does not point past the end of
 <var title="">input</var> and the code point at <var title="">position</var> is
 one of <var title="">code points</var>, append that code point to the end
 of <var title="">result</var> and advance <var title="">position</var> to the
 next code point in <var title="">input</var>.

Return <var title="">result</var>.

To <dfn id="skip-ascii-whitespace">skip ASCII whitespace</dfn> means to
collect a code point sequence of
ASCII whitespace and discard the
return value.

The <dfn id="concept-ordered-set-serializer" title="concept-ordered-set-serializer">ordered set serializer</dfn> takes a
<var title="">set</var> and returns the concatenation of the strings in
<var title="">set</var>, separated from each other by U+0020.

2.4 Namespaces

The <dfn id="html-namespace">HTML namespace</dfn> is
http://www.w3.org/1999/xhtml.

The <dfn id="xml-namespace">XML namespace</dfn> is
http://www.w3.org/XML/1998/namespace.

The <dfn id="xmlns-namespace">XMLNS namespace</dfn> is
http://www.w3.org/2000/xmlns/.

3 Errors

This entire section will move out of DOM into IDL. Use this standard as
reference for DOMException until that has happened. Replace instances of
DOMError with DOMException as DOMError will be
nuked from orbit soon.

3.1 Exception DOMException

exception <dfn id="domexception">DOMException</dfn> {
  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; // historical; use JavaScript's TypeError instead
  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;
};

The <dfn id="dom-domexception-code" title="dom-DOMException-code">code</dfn> exception
field must return the value it was initialized to.

To <dfn id="concept-throw" title="concept-throw">throw</dfn> a <var title="">name</var> exception
run these steps:

Let <var title="">code</var> be zero.

If <var title="">name</var> is in the first column of the
 error names table and has a corresponding legacy
 code exception field value in the
 third column, set <var title="">code</var> to that value.

Throw a new
 DOMException exception, whose
 message is a user agent-defined value,
 name is <var title="">name</var>, and
 whose code exception field is
 <var title="">code</var>.

To
throw a "TimeoutError" exception, a
user agent would construct a DOMException exception whose
name is
"TimeoutError" and
code exception field value is 23,
and actually throw that object as an exception. In JavaScript, this
exception will have a name property whose value is
"TimeoutError".

3.2 Interface DOMError

[Constructor(DOMString <var title="">name</var>, optional DOMString <var title="">message</var> = "")]
interface <dfn id="domerror">DOMError</dfn> {
  readonly attribute DOMString name;
  readonly attribute DOMString message;
};

DOMError will be nuked. Replace your usage with
DOMException now.

The <dfn id="dom-domerror" title="dom-DOMError">DOMError(<var title="">name</var>, <var title="">message</var>)</dfn>
constructor must return a new DOMError object whose
name attribute is initialized to
<var title="">name</var> and whose message attribute
is initialized to <var title="">message</var>.

The <dfn id="dom-domerror-name" title="dom-DOMError-name">name</dfn> attribute must
return the value it was initialized to.

The <dfn id="dom-domerror-message" title="dom-DOMError-message">message</dfn> attribute must
return the value it was initialized to.

The value of the message will
typically be implementation-dependent and for informational purposes only.

A
<dfn id="concept-domerror" title="concept-DOMError"><var title="">name</var> DOMError</dfn>
means a DOMError object whose
name attribute is initialized to
<var title="">name</var> and whose message attribute
is initialized to a helpful implementation-dependent message that explains the error.

A specification could say that an error
attribute must return a
"SyntaxError" DOMError.

3.3 Error names

The <dfn id="error-names-table">error names table</dfn> below lists all the allowed error names,
a description, and legacy code
exception field values (when the error name is used for
throwing an exception).

If an error name is not listed here, please file a bug as
indicated at the top of this specification and it will be addressed shortly.
Thanks!

NameDescriptionLegacy code exception field value (if any)

  "<dfn id="indexsizeerror">IndexSizeError</dfn>"
  The index is not in the allowed range.
  <dfn id="dom-domexception-index_size_err" title="dom-DOMException-INDEX_SIZE_ERR">INDEX_SIZE_ERR</dfn> (1)

  "<dfn id="hierarchyrequesterror">HierarchyRequestError</dfn>"
  The operation would yield an incorrect node tree.
  <dfn id="dom-domexception-hierarchy_request_err" title="dom-DOMException-HIERARCHY_REQUEST_ERR">HIERARCHY_REQUEST_ERR</dfn> (3)

  "<dfn id="wrongdocumenterror">WrongDocumentError</dfn>"
  The object is in the wrong document.
  <dfn id="dom-domexception-wrong_document_err" title="dom-DOMException-WRONG_DOCUMENT_ERR">WRONG_DOCUMENT_ERR</dfn> (4)

  "<dfn id="invalidcharactererror">InvalidCharacterError</dfn>"
  The string contains invalid characters.
  <dfn id="dom-domexception-invalid_character_err" title="dom-DOMException-INVALID_CHARACTER_ERR">INVALID_CHARACTER_ERR</dfn> (5)

  "<dfn id="nomodificationallowederror">NoModificationAllowedError</dfn>"
  The object can not be modified.
  <dfn id="dom-domexception-no_modification_allowed_err" title="dom-DOMException-NO_MODIFICATION_ALLOWED_ERR">NO_MODIFICATION_ALLOWED_ERR</dfn> (7)

  "<dfn id="notfounderror">NotFoundError</dfn>"
  The object can not be found here.
  <dfn id="dom-domexception-not_found_err" title="dom-DOMException-NOT_FOUND_ERR">NOT_FOUND_ERR</dfn> (8)

  "<dfn id="notsupportederror">NotSupportedError</dfn>"
  The operation is not supported.
  <dfn id="dom-domexception-not_supported_err" title="dom-DOMException-NOT_SUPPORTED_ERR">NOT_SUPPORTED_ERR</dfn> (9)

  "<dfn id="invalidstateerror">InvalidStateError</dfn>"
  The object is in an invalid state.
  <dfn id="dom-domexception-invalid_state_err" title="dom-DOMException-INVALID_STATE_ERR">INVALID_STATE_ERR</dfn> (11)

  "<dfn id="syntaxerror">SyntaxError</dfn>"
  The string did not match the expected pattern.
  <dfn id="dom-domexception-syntax_err" title="dom-DOMException-SYNTAX_ERR">SYNTAX_ERR</dfn> (12)

  "<dfn id="invalidmodificationerror">InvalidModificationError</dfn>"
  The object can not be modified in this way.
  <dfn id="dom-domexception-invalid_modification_err" title="dom-DOMException-INVALID_MODIFICATION_ERR">INVALID_MODIFICATION_ERR</dfn> (13)

  "<dfn id="namespaceerror">NamespaceError</dfn>"
  The operation is not allowed by Namespaces in XML. [XMLNS]
  <dfn id="dom-domexception-namespace_err" title="dom-DOMException-NAMESPACE_ERR">NAMESPACE_ERR</dfn> (14)

  "<dfn id="invalidaccesserror">InvalidAccessError</dfn>"
  The object does not support the operation or argument.
  <dfn id="dom-domexception-invalid_access_err" title="dom-DOMException-INVALID_ACCESS_ERR">INVALID_ACCESS_ERR</dfn> (15)

  "<dfn id="securityerror">SecurityError</dfn>"
  The operation is insecure.
  <dfn id="dom-domexception-security_err" title="dom-DOMException-SECURITY_ERR">SECURITY_ERR</dfn> (18)

  "<dfn id="networkerror">NetworkError</dfn>"
  A network error occurred.
  <dfn id="dom-domexception-network_err" title="dom-DOMException-NETWORK_ERR">NETWORK_ERR</dfn> (19)

  "<dfn id="aborterror">AbortError</dfn>"
  The operation was aborted.
  <dfn id="dom-domexception-abort_err" title="dom-DOMException-ABORT_ERR">ABORT_ERR</dfn> (20)

  "<dfn id="urlmismatcherror">URLMismatchError</dfn>"
  The given URL does not match another URL.
  <dfn id="dom-domexception-url_mismatch_err" title="dom-DOMException-URL_MISMATCH_ERR">URL_MISMATCH_ERR</dfn> (21)

  "<dfn id="quotaexceedederror">QuotaExceededError</dfn>"
  The quota has been exceeded.
  <dfn id="dom-domexception-quota_exceeded_err" title="dom-DOMException-QUOTA_EXCEEDED_ERR">QUOTA_EXCEEDED_ERR</dfn> (22)

  "<dfn id="timeouterror">TimeoutError</dfn>"
  The operation timed out.
  <dfn id="dom-domexception-timeout_err" title="dom-DOMException-TIMEOUT_ERR">TIMEOUT_ERR</dfn> (23)

  "<dfn id="invalidnodetypeerror">InvalidNodeTypeError</dfn>"
  The supplied node is incorrect or has an incorrect ancestor for this operation.
  <dfn id="dom-domexception-invalid_node_type_err" title="dom-DOMException-INVALID_NODE_TYPE_ERR">INVALID_NODE_TYPE_ERR</dfn> (24)

  "<dfn id="datacloneerror">DataCloneError</dfn>"
  The object can not be cloned.
  <dfn id="dom-domexception-data_clone_err" title="dom-DOMException-DATA_CLONE_ERR">DATA_CLONE_ERR</dfn> (25)

  "<dfn id="encodingerror">EncodingError</dfn>"
  The encoding operation (either encoded or decoding) failed.
  —

  "<dfn id="notreadableerror">NotReadableError</dfn>"
  The I/O read operation failed.
  —

4 Events

4.1 Introduction to "DOM Events"

Throughout the web platform events are
dispatched to objects to signal an
occurrence, such as network activity or user interaction. These objects
implement the EventTarget interface and can therefore add
event listeners to observe
events:

obj.addEventListener("load", imgFetched)

function imgFetched(ev) {
  // great success
  …
}

Event listeners can be removed
by utilizing the
removeEventListener()
method, passing the same arguments.

Events are objects too and implement the
Event interface (or a derived interface). In the example above
<var title="">ev</var> is the event. It is
passed as argument to
event listener's callback
(typically a JavaScript Function as shown above).
Event listeners key off the
event's
type attribute value
("load" in the above example). The
event's
target attribute value returns the
object to which the event was
dispatched (<var title="">obj</var>
above).

Now while typically events are
dispatched by the user agent as
the result of user interaction or the completion of some task, applications
can dispatch
events themselves, commonly known as
synthetic events:

// add an appropriate event listener
obj.addEventListener("cat", function(e) { process(e.detail) })

// create and dispatch the event
var event = new CustomEvent("cat", {"detail":{"hazcheeseburger":true}})
obj.dispatchEvent(event)

Apart from signaling, events are
sometimes also used to let an application control what happens next in an
operation. For instance as part of form submission an
event whose
type attribute value is
"submit" is
dispatched. If this
event's
preventDefault() method is
invoked, form submission will be terminated. Applications who wish to make
use of this functionality through events
dispatched by the application
(synthetic events) can make use of the return value of the
dispatchEvent() method:

if(obj.dispatchEvent(event)) {
  // event was not canceled, time for some magic
  …
}

When an event is
dispatched to an object that
participates in a
tree (e.g. an
element), it can reach
event listeners on that object's
ancestors too. First all object's
ancestor
event listeners whose
capture variable is set to true are invoked, in
tree order. Second, object's own
event listeners are invoked. And
finally, and only if event's
bubbles attribute value is true,
object's  ancestor
event listeners are invoked again,
but now in reverse tree order.

Lets look at an example on how events
work in a tree:

<!doctype html>
<html>
 <head>
  <title>Boring example</title>
 </head>
 <body>
  <p>Hello <span id=x>world</span>!</p>
  <script>
   function test(e) {
     debug(e.target, e.currentTarget, e.eventPhase)
   }
   document.addEventListener("hey", test, true)
   document.body.addEventListener("hey", test)
   var ev = new Event("hey", {bubbles:true})
   document.getElementById("x").dispatchEvent(ev)
  </script>
 </body>
</html>

The debug function will be invoked twice. Each time
the events's
target attribute value will be the
span element. The
first time currentTarget attribute's
value will be the document, the second
time the body element.
eventPhase attribute's value
switches from CAPTURING_PHASE
to BUBBLING_PHASE. If an
event listener was registered for
the span element,
eventPhase attribute's value
would have been AT_TARGET.

4.2 Interface Event

[Constructor(DOMString <var title="">type</var>, optional EventInit <var title="">eventInitDict</var>),
 Exposed=Window,Worker]
interface <dfn id="event">Event</dfn> {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? currentTarget;

  const unsigned short NONE = 0;
  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;

  [Unforgeable] readonly attribute boolean isTrusted;
  readonly attribute DOMTimeStamp timeStamp;

  void initEvent(DOMString <var title="">type</var>, boolean <var title="">bubbles</var>, boolean <var title="">cancelable</var>);
};

dictionary <dfn id="eventinit">EventInit</dfn> {
  boolean bubbles = false;
  boolean cancelable = false;
};

An <dfn id="concept-event" title="concept-event">event</dfn> allows for signaling that
something has occurred. E.g. that an image has completed downloading. It is
represented by the Event interface or an interface that
inherits from the Event interface.

<var title="">event</var> = new Event(<var title="">type</var> [, <var title="">eventInitDict</var>])

Returns a new <var title="">event</var> whose
 type attribute value is set to
 <var title="">type</var>. The optional <var title="">eventInitDict</var> argument
 allows for setting the bubbles and
 cancelable attributes via object
 members of the same name.

<var title="">event</var> . type

Returns the type of <var title="">event</var>, e.g.
 "click", "hashchange", or
 "submit".

<var title="">event</var> . target

Returns the object <var title="">event</var> is
 dispatched to.

<var title="">event</var> . currentTarget

Returns the object whose
 event listener's callback
 is invoked.

<var title="">event</var> . eventPhase

Returns the event's phase, which is
 one of NONE,
 CAPTURING_PHASE,
 AT_TARGET, and
 BUBBLING_PHASE.

<var title="">event</var> . stopPropagation()

When dispatched in a
 tree, invoking this method prevents
 <var title="">event</var> from reaching any other objects than the current.

<var title="">event</var> . stopImmediatePropagation()

Invoking this method prevents <var title="">event</var> from reaching
 any event listeners registered
 after the current one and when
 dispatched in a
 tree also prevents
 <var title="">event</var> from reaching any other objects.

<var title="">event</var> . bubbles

Returns true if <var title="">event</var>'s goes through its target attribute value's ancestors in reverse tree order, and false otherwise.

<var title="">event</var> . cancelable

Returns true or false depending on how <var title="">event</var> was
 initialized. Its return value does not always carry meaning, but true can
 indicate that part of the operation during which <var title="">event</var> was
 dispatched, can be canceled by
 invoking the preventDefault()
 method.

<var title="">event</var> . preventDefault()

If invoked when the
 cancelable attribute value is true,
 signals to the operation that caused <var title="">event</var> to be
 dispatched that it needs to be
 canceled.

<var title="">event</var> . defaultPrevented

Returns true if
 preventDefault() was invoked
 while the cancelable attribute
 value is true, and false otherwise.

<var title="">event</var> . isTrusted

Returns true if <var title="">event</var> was
 dispatched by the user agent, and
 false otherwise.

<var title="">event</var> . timeStamp

Returns the creation time of <var title="">event</var> in the number of
 milliseconds that passed since 00:00:00 UTC on 1 January 1970.

The <dfn id="dom-event-type" title="dom-Event-type">type</dfn> attribute must
return the value it was initialized to. When an
event is created the attribute must be
initialized to the empty string.

The <dfn id="dom-event-target" title="dom-Event-target">target</dfn> and
<dfn id="dom-event-currenttarget" title="dom-Event-currentTarget">currentTarget</dfn>
attributes must return the values they were initialized to. When an
event is created the attributes must be
initialized to null.

The <dfn id="dom-event-eventphase" title="dom-Event-eventPhase">eventPhase</dfn>
attribute must return the value it was initialized to, which must be one of
the following:

<dfn id="dom-event-none" title="dom-Event-NONE">NONE</dfn> (numeric value 0)

Events not currently
 dispatched are in this phase.

<dfn id="dom-event-capturing_phase" title="dom-Event-CAPTURING_PHASE">CAPTURING_PHASE</dfn> (numeric value 1)

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

<dfn id="dom-event-at_target" title="dom-Event-AT_TARGET">AT_TARGET</dfn> (numeric value 2)

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

<dfn id="dom-event-bubbling_phase" title="dom-Event-BUBBLING_PHASE">BUBBLING_PHASE</dfn> (numeric value 3)

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

Initially the attribute must be initialized to
NONE.

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

<dfn id="stop-propagation-flag">stop propagation flag</dfn>

<dfn id="stop-immediate-propagation-flag">stop immediate propagation flag</dfn>

<dfn id="canceled-flag">canceled flag</dfn>

<dfn id="initialized-flag">initialized flag</dfn>

<dfn id="dispatch-flag">dispatch flag</dfn>

The
<dfn id="dom-event-stoppropagation" title="dom-Event-stopPropagation">stopPropagation()</dfn>
method must set the stop propagation flag.

The
<dfn id="dom-event-stopimmediatepropagation" title="dom-Event-stopImmediatePropagation">stopImmediatePropagation()</dfn>
method must set both the stop propagation flag and
stop immediate propagation flag.

The <dfn id="dom-event-bubbles" title="dom-Event-bubbles">bubbles</dfn> and
<dfn id="dom-event-cancelable" title="dom-Event-cancelable">cancelable</dfn> attributes
must return the values they were initialized to. When an
event is created, they must be initialized
to false. The EventInit dictionary is not sufficient due to
the existence of the legacy
createEvent().

The
<dfn id="dom-event-preventdefault" title="dom-Event-preventDefault">preventDefault()</dfn>
method must set the canceled flag if the
cancelable attribute value is true.

The
<dfn id="dom-event-defaultprevented" title="dom-Event-defaultPrevented">defaultPrevented</dfn>
attribute must return true if the canceled flag is set and
false otherwise.

The <dfn id="dom-event-istrusted" title="dom-Event-isTrusted">isTrusted</dfn> attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to false.

The <dfn id="dom-event-timestamp" title="dom-Event-timeStamp">timeStamp</dfn> attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to the number of milliseconds that have passed since
00:00:00 UTC on 1 January 1970, ignoring leap seconds.

To <dfn id="concept-event-initialize" title="concept-event-initialize">initialize</dfn> an
<var title="">event</var>, with <var title="">type</var>,
<var title="">bubbles</var>, and <var title="">cancelable</var>, run these steps:

Set the initialized flag.

If the dispatch flag is set, terminate these steps.

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

Set the isTrusted attribute
 to false.

Set the target attribute to
 null.

Set the type attribute to
 <var title="">type</var>.

Set the bubbles attribute to
 <var title="">bubbles</var>.

Set the cancelable attribute
 to <var title="">cancelable</var>.

The
<dfn id="dom-event-initevent" title="dom-Event-initEvent">initEvent(<var title="">type</var>, <var title="">bubbles</var>, <var title="">cancelable</var>)</dfn>
method must initialize the
context object with <var title="">type</var>,
<var title="">bubbles</var>, and <var title="">cancelable</var>.

As events have constructors
initEvent() is superfluous. However,
it has to be supported for legacy content.

4.3 Interface CustomEvent

[Constructor(DOMString <var title="">type</var>, optional CustomEventInit <var title="">eventInitDict</var>),
 Exposed=Window,Worker]
interface <dfn id="customevent">CustomEvent</dfn> : Event {
  readonly attribute any detail;

  void initCustomEvent(DOMString <var title="">type</var>, boolean <var title="">bubbles</var>, boolean <var title="">cancelable</var>, any <var title="">detail</var>);
};

dictionary <dfn id="customeventinit">CustomEventInit</dfn> : EventInit {
  any detail = null;
};

Events using the
CustomEvent interface can be used to carry custom data.

<var title="">event</var> = new CustomEvent(<var title="">type</var> [, <var title="">eventInitDict</var>])

Works analogously to the constructor for Event except
 that the optional <var title="">eventInitDict</var> argument now
 allows for setting the detail attribute
 too.

<var title="">event</var> . detail

Returns any custom data <var title="">event</var> was created with.
 Typically used for synthetic events.

The <dfn id="dom-customevent-detail" title="dom-CustomEvent-detail">detail</dfn> attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to null. The CustomEventInit dictionary is not
sufficient due to the existence of the legacy
createEvent().

The
<dfn id="dom-customevent-initcustomevent" title="dom-CustomEvent-initCustomEvent">initCustomEvent(<var title="">type</var>, <var title="">bubbles</var>, <var title="">cancelable</var>, <var title="">detail</var>)</dfn>
method must initialize the
context object with <var title="">type</var>,
<var title="">bubbles</var>, and <var title="">cancelable</var>, and then set its
detail attribute to
<var title="">detail</var>.

4.4 Constructing events

When a <dfn id="concept-event-constructor" title="concept-event-constructor">constructor</dfn> of the Event
interface, or of an interface that inherits from the Event interface, is
invoked, these steps must be run:

Create an event that uses the
 interface the constructor was invoked upon.

Set its initialized flag.

Initialize the type attribute to
 the <var title="">type</var> argument.

If there is an <var title="">eventInitDict</var> argument then for each
 dictionary member defined therein find
 the attribute on event whose
 identifier matches the key of
 the dictionary member and then
 set the attribute to the value of that
 dictionary member.

Return the event.

4.5 Defining event interfaces

In general, when defining a new interface that inherits from
Event please always ask feedback from the WHATWG or the
W3C WebApps WG community.

The CustomEvent interface can be used as starting point.
However, do not introduce any init<var>*</var>Event()
methods as they are redundant with constructors. Interfaces that inherit
from the Event interface that have such a method only have it
for historical reasons.

4.6 Interface EventTarget

[Exposed=Window,Worker]
interface <dfn id="eventtarget">EventTarget</dfn> {
  void addEventListener(DOMString <var title="">type</var>, EventListener? <var title="">callback</var>, optional boolean <var title="">capture</var> = false);
  void removeEventListener(DOMString <var title="">type</var>, EventListener? <var title="">callback</var>, optional boolean <var title="">capture</var> = false);
  boolean dispatchEvent(Event <var title="">event</var>);
};

callback interface <dfn id="eventlistener">EventListener</dfn> {
  void handleEvent(Event <var title="">event</var>);
};

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

An <dfn id="concept-event-listener" title="concept-event-listener">event listener</dfn> associates a
callback with a specific event. Each
event listener consists of a
type (of the event),
callback, and capture variable.

The callback is named EventListener for
historical reasons. As can be seen from the definition above, an
event listener is a more broad
concept.

<var title="">target</var> . addEventListener(<var title="">type</var>, <var title="">callback</var> [, <var title="">capture</var> = false])

Appends an event listener
  for events whose
  type attribute value is
  <var title="">type</var>. The <var title="">callback</var> argument sets the
  callback that will be invoked when the
  event is
  dispatched. When set to true,
  the <var title="">capture</var> argument prevents callback from being invoked when
  the event's
  eventPhase attribute value is
  BUBBLING_PHASE. When false, callback
  will not be invoked when event's
  eventPhase attribute value is
  CAPTURING_PHASE. Either way,
  callback will be invoked when event's
  eventPhase attribute value is
  AT_TARGET.

The event listener is
  appended to <var title="">target</var>'s list of
  event listeners and is not
  appended if it is a duplicate (the
  event listeners in the list are
  unique).

<var title="">target</var> . removeEventListener(<var title="">type</var>, <var title="">callback</var> [, <var title="">capture</var> = false])

Remove the event listener
 in <var title="">target</var>'s list of
 event listeners with the same
 <var title="">type</var>, <var title="">callback</var>, and
 <var title="">capture</var>.

<var title="">target</var> . dispatchEvent(<var title="">event</var>)

Dispatches a synthetic
 event <var title="">event</var> to <var title="">target</var> and returns true
 if either <var title="">event</var>'s
 cancelable attribute value is false
 or it's preventDefault() method
 was not invoked, and false otherwise.

The
<dfn id="dom-eventtarget-addeventlistener" title="dom-EventTarget-addEventListener">addEventListener(<var title="">type</var>, <var title="">callback</var>, <var title="">capture</var>)</dfn>
method must run these steps:

If <var title="">callback</var> is null, terminate these steps.

Append an event listener
 to the associated list of
 event listeners with type
 set to <var title="">type</var>, callback set to <var title="">callback</var>, and
 capture set to <var title="">capture</var>, unless there
 already is an event listener in
 that list with the same type, callback, and capture.

The
<dfn id="dom-eventtarget-removeeventlistener" title="dom-EventTarget-removeEventListener">removeEventListener(<var title="">type</var>, <var title="">callback</var>, <var title="">capture</var>)</dfn>
method must run these steps:

Remove an event listener
 from the associated list of
 event listeners, whose
 type is <var title="">name</var>, callback is <var title="">callback</var>, and
 capture is <var title="">capture</var>.

The
<dfn id="dom-eventtarget-dispatchevent" title="dom-EventTarget-dispatchEvent">dispatchEvent(<var title="">event</var>)</dfn>
method must run these steps:

If <var title="">event</var>'s dispatch flag is set, or if
 its initialized flag is not set,
 throw an
 "InvalidStateError" exception.

Initialize <var title="">event</var>'s
 isTrusted attribute to false.

Dispatch the
 <var title="">event</var> and return the value that returns.

4.7 Dispatching events

To <dfn id="concept-event-dispatch" title="concept-event-dispatch">dispatch</dfn> an
event to a given object, optionally with
a <var title="">target override</var>, run these steps:

Let <var title="">event</var> be the
 event that is dispatched.

Set <var title="">event</var>'s dispatch flag.

Initialize <var title="">event</var>'s
 target attribute to
 <var title="">target override</var>, if it is given, or the object to which
 <var title="">event</var> is dispatched otherwise.

If <var title="">event</var>'s
 target attribute value is
 participating in a
 tree, let <var title="">event path</var> be a
 static ordered list of all its
 ancestors in
 tree order, and let
 <var title="">event path</var> be the empty list otherwise.

Initialize <var title="">event</var>'s
 eventPhase attribute to
 CAPTURING_PHASE.

For each object in <var title="">event path</var>,
 invoke its
 event listeners with event
 <var title="">event</var>, as long as <var title="">event</var>'s
 stop propagation flag is unset.

Initialize <var title="">event</var>'s
 eventPhase attribute to
 AT_TARGET.

Invoke the
 event listeners of
 <var title="">event</var>'s target
 attribute value with <var title="">event</var>, if <var title="">event</var>'s
 stop propagation flag is unset.

If <var title="">event</var>'s
  bubbles attribute value is true, run
  these substeps:

Reverse the order of <var title="">event path</var>.

Initialize <var title="">event</var>'s
   eventPhase attribute to
   BUBBLING_PHASE.

For each object in <var title="">event path</var>,
   invoke its
   event listeners, with event
   <var title="">event</var> as long as <var title="">event</var>'s
   stop propagation flag is unset.

Unset <var title="">event</var>'s dispatch flag.

Initialize <var title="">event</var>'s
 eventPhase attribute to
 NONE.

Initialize <var title="">event</var>'s
 currentTarget attribute to null.

Return false if <var title="">event</var>'s canceled flag
 is set, and true otherwise.

To <dfn id="concept-event-listener-invoke" title="concept-event-listener-invoke">invoke</dfn> the
event listeners for an object with an
event run these steps:

Let <var title="">event</var> be the
 event for which the
 event listeners are invoked.

Let <var title="">listeners</var> be a copy of the
 event listeners associated with
 the object for which these steps are run.

Initialize <var title="">event</var>'s
 currentTarget attribute to the
 object for which these steps are run.

Then run these substeps for each
  event listener in
  <var title="">listeners</var>:

If <var title="">event</var>'s
   stop immediate propagation flag is set, terminate the
   invoke algorithm.

Let <var title="">listener</var> be the
   event listener.

If <var title="">event</var>'s type
   attribute value is not <var title="">listener</var>'s type, terminate
   these substeps (and run them for the next
   event listener).

If <var title="">event</var>'s
   eventPhase attribute value is
   CAPTURING_PHASE and
   <var title="">listener</var>'s capture is false, terminate these
   substeps (and run them for the next
   event listener).

If <var title="">event</var>'s
   eventPhase attribute value is
   BUBBLING_PHASE and
   <var title="">listener</var>'s capture is true, terminate these
   substeps (and run them for the next
   event listener).

Call <var title="">listener</var>'s callback's
   handleEvent, with the event passed to
   this algorithm as the first argument and <var title="">event</var>'s
   currentTarget attribute value as
   callback this value.

4.8 Firing events

To
<dfn id="concept-event-fire" title="concept-event-fire">fire an event named <var title="">e</var></dfn>
means that a new event using the
Event interface, with its
type attribute initialized to
<var title="">e</var>, and its isTrusted
attribute initialized to true, is to be
dispatched to the given object.

Fire in the context of DOM is short for creating, initializing, and
dispatching an
event.
Fire an event makes that process easier to write
down. If the event needs its bubbles or
cancelable attribute initialized, one could write
"fire an event named
submit with its cancelable attribute
initialized to true".

5 Nodes

5.1 Introduction to "The DOM"

In its original sense, "The DOM" is an API for
accessing and manipulating documents (in particular, HTML and XML
documents). In this specification, the term "document" is used for any
markup-based resource, ranging from short static documents to long essays or
reports with rich multimedia, as well as to fully-fledged interactive
applications.

These documents are presented as a
node tree. Some of the
nodes in the
tree can have
children, while others are leaves.

To illustrate, consider this HTML document:

<!DOCTYPE html>
<html class=e>
 <head><title>Aliens?</title></head>
 <body>Why yes.</body>
</html>

It is represented as follows:

  Document

Doctype: html

Element: html class="e"

      Element: head

        Element: title

Text: Aliens?

Text: ⏎␣

      Element: body

Text: Why yes.⏎

Note that, due to the magic that is
HTML parsing, not all
ASCII whitespace were turned into
Text nodes, but the general
concept is clear. Markup goes in, a tree of
nodes comes out.

The most excellent
Live DOM Viewer
can be used to explore this matter in more detail.

5.2 Node tree

Objects implementing the Document,
DocumentFragment, DocumentType,
Element, Text, ProcessingInstruction,
or Comment interface (simply called
<dfn id="concept-node" title="concept-node">nodes</dfn>)
participate in a
tree, simply named the
<dfn id="concept-node-tree" title="concept-node-tree">node tree</dfn>.

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

Document

In tree order:

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

Optionally one DocumentType node.

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

Optionally one Element node.

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

Text

ProcessingInstruction

Comment

None.

The <dfn id="concept-node-length" title="concept-node-length">length</dfn> of a
node <var title="">node</var> depends on
<var title="">node</var>:

DocumentType

Zero.

Text

ProcessingInstruction

Comment

Its length attribute
 value.

Any other node

Its number of children.

A node is considered
<dfn id="concept-node-empty" title="concept-node-empty">empty</dfn> if its
length is zero.

5.2.1 Mutation algorithms

At certain points in the algorithms below it is said that a
<dfn id="node-is-inserted">node is inserted</dfn> or a <dfn id="node-is-removed">node is removed</dfn>. These are
hooks for other applicable specifications to process the
nodes that have been inserted or removed
further and ensures that when multiple nodes
are inserted or removed this happens atomically.

To <dfn id="concept-node-pre-insert" title="concept-node-pre-insert">pre-insert</dfn> a
<var title="">node</var> into a <var title="">parent</var> before a
<var title="">child</var>, run these steps:

If <var title="">parent</var> is not a Document,
 DocumentFragment, or Element
 node,
 throw a
 "HierarchyRequestError".

If <var title="">node</var> is a
 host-including inclusive ancestor
 of <var title="">parent</var>, throw a
 "HierarchyRequestError".

If <var title="">child</var> is not null and its
 parent is not
 <var title="">parent</var>, throw a
 "NotFoundError" exception.

If <var title="">node</var> is not a
 DocumentFragment, DocumentType,
 Element, Text,
 ProcessingInstruction, or Comment
 node,
 throw a
 "HierarchyRequestError".

If either <var title="">node</var> is a Text
 node and <var title="">parent</var> is a
 document, or <var title="">node</var> is a
 doctype and <var title="">parent</var> is
 not a document,
 throw a
 "HierarchyRequestError".

If <var title="">parent</var> is a
  document, and any of the statements below, switched
  on <var title="">node</var>, are true, throw a
  "HierarchyRequestError".

DocumentFragment node

If <var title="">node</var> has more than one
    element child
    or has a Text node
    child.

Otherwise, if <var title="">node</var> has one
    element
    child, and <var title="">parent</var> has an
    element
    child, <var title="">child</var> is a
    doctype, or <var title="">child</var> is not null and
    a doctype is
    following <var title="">child</var>.

element

<var title="">parent</var> has an element
   child, <var title="">child</var> is a
   doctype, or <var title="">child</var> is not null and a
   doctype is
   following <var title="">child</var>.

doctype

<var title="">parent</var> has a doctype
   child, an
   element is
   preceding <var title="">child</var>, or
   <var title="">child</var> is null and <var title="">parent</var> has an
   element child.

Let <var title="">reference child</var> be <var title="">child</var>.

If <var title="">reference child</var> is <var title="">node</var>, set it
 to <var title="">node</var>'s
 next sibling.

Adopt
 <var title="">node</var> into <var title="">parent</var>'s
 node document.

Insert <var title="">node</var>
 into <var title="">parent</var> before <var title="">reference child</var>.

Return <var title="">node</var>.

To <dfn id="concept-node-insert" title="concept-node-insert">insert</dfn> a <var title="">node</var>
into a <var title="">parent</var> before a <var title="">child</var>, optionally
with a suppress observers flag, run these steps:

Let <var title="">count</var> be the number of
 children of <var title="">node</var> if
 it is a DocumentFragment node,
 and one otherwise.

For each range whose
 start node is
 <var title="">parent</var> and
 start offset is greater than
 <var title="">child</var>'s index,
 increase its start offset by
 <var title="">count</var>.

For each range whose
 end node is
 <var title="">parent</var> and
 end offset is greater than
 <var title="">child</var>'s index,
 increase its end offset by
 <var title="">count</var>.

Let <var title="">nodes</var> be <var title="">node</var>'s
 children if <var title="">node</var> is
 a DocumentFragment node, and a
 list containing solely <var title="">node</var> otherwise.

If <var title="">node</var> is a DocumentFragment
  node, queue a mutation record
  of "childList" for <var title="">node</var> with removedNodes
  <var title="">nodes</var>.

This step does intentionally not pay attention to the
  suppress observers flag.

If <var title="">node</var> is a DocumentFragment
 node,
 remove its
 children with the
 suppress observers flag set.

If suppress observers flag is unset,
 queue a mutation record of "childList" for
 <var title="">parent</var> with addedNodes <var title="">nodes</var>,
 nextSibling <var title="">child</var>, and previousSibling
 <var title="">child</var>'s
 previous sibling
 or <var title="">parent</var>'s
 last child if
 <var title="">child</var> is null.

Insert all nodes in
 <var title="">nodes</var> before <var title="">child</var> or at the end of
 <var title="">parent</var> if <var title="">child</var> is null.

If suppress observers flag is unset, for each
 node in <var title="">nodes</var>, in
 tree order run
 node is inserted.

To <dfn id="concept-node-append" title="concept-node-append">append</dfn> a <var title="">node</var>
to a <var title="">parent</var>,
pre-insert <var title="">node</var>
into <var title="">parent</var> before null.

To <dfn id="concept-node-replace" title="concept-node-replace">replace</dfn> a <var title="">child</var>
with <var title="">node</var> within a <var title="">parent</var>, run these
steps:

If <var title="">parent</var> is not a Document,
 DocumentFragment, or Element
 node,
 throw a
 "HierarchyRequestError".

If <var title="">node</var> is a
 host-including inclusive ancestor
 of <var title="">parent</var>, throw a
 "HierarchyRequestError".

If <var title="">child</var>'s
 parent is not
 <var title="">parent</var>, throw a
 "NotFoundError" exception.

If <var title="">node</var> is not a
 DocumentFragment, DocumentType,
 Element, Text,
 ProcessingInstruction, or Comment
 node,
 throw a
 "HierarchyRequestError".

If either <var title="">node</var> is a Text
 node and <var title="">parent</var> is a
 document, or <var title="">node</var> is a
 doctype and <var title="">parent</var> is
 not a document,
 throw a
 "HierarchyRequestError".

If <var title="">parent</var> is a
  document, and any of the statements below, switched
  on <var title="">node</var>, are true, throw a
  "HierarchyRequestError".

DocumentFragment node

If <var title="">node</var> has more than one
    element child
    or has a Text node
    child.

Otherwise, if <var title="">node</var> has one
    element child
    and either <var title="">parent</var> has an element
    child that is not <var title="">child</var> or a
    doctype is
    following <var title="">child</var>.

element

<var title="">parent</var> has an element
   child that is not <var title="">child</var> or a
   doctype is
   following <var title="">child</var>.

doctype

<var title="">parent</var> has a doctype
   child that is not <var title="">child</var>, or an
   element is
   preceding <var title="">child</var>.

The above statements differ from the
  pre-insert algorithm.

Let <var title="">reference child</var> be <var title="">child</var>'s
 next sibling.

If <var title="">reference child</var> is <var title="">node</var>, set it
 to <var title="">node</var>'s
 next sibling.

Adopt
 <var title="">node</var> into <var title="">parent</var>'s
 node document.

Remove <var title="">child</var>
 from its <var title="">parent</var> with the
 suppress observers flag set.

Insert <var title="">node</var>
 into <var title="">parent</var> before <var title="">reference child</var> with
 the suppress observers flag set.

Let <var title="">nodes</var> be <var title="">node</var>'s
 children if <var title="">node</var> is
 a DocumentFragment node, and a
 list containing solely <var title="">node</var> otherwise.

Queue a mutation record of "childList" for
 target <var title="">parent</var> with addedNodes
 <var title="">nodes</var>, removedNodes a list solely containing
 <var title="">child</var>, nextSibling <var title="">reference child</var>, and
 previousSibling <var title="">child</var>'s
 previous sibling.

Run node is removed for <var title="">child</var>, and
 then for each node in
 <var title="">nodes</var>, in
 tree order, run
 node is inserted.

Return <var title="">child</var>.

To <dfn id="concept-node-replace-all" title="concept-node-replace-all">replace all</dfn> with a
<var title="">node</var> within a <var title="">parent</var>, run these steps:

If <var title="">node</var> is not null,
 adopt <var title="">node</var> into
 <var title="">parent</var>'s
 node document.

Let <var title="">removedNodes</var> be <var title="">parent</var>'s
 children.

Let <var title="">addedNodes</var> be the empty list if <var title="">node</var> is
 null, <var title="">node</var>'s children if
 <var title="">node</var> is a DocumentFragment
 node, and a list containing <var title="">node</var>
 otherwise.

Remove all
 <var title="">parent</var>'s children,
 with the suppress observers flag set.

If <var title="">node</var> is not null,
 insert <var title="">node</var> into
 <var title="">parent</var> before null with the suppress observers flag set.

Queue a mutation record of "childList" for
 <var title="">parent</var> with addedNodes <var title="">addedNodes</var> and
 removedNodes <var title="">removedNodes</var>.

Run node is removed for each node in
 <var title="">removedNodes</var>, in tree order, and
 then run node is inserted for each node in
 <var title="">addedNodes</var>, in tree order.

This algorithm does not make any checks with regards to the
node tree constraints. Use it wisely.

To <dfn id="concept-node-pre-remove" title="concept-node-pre-remove">pre-remove</dfn> a
<var title="">child</var> from a <var title="">parent</var>, run these steps:

If <var title="">child</var>'s
 parent is not
 <var title="">parent</var>, throw a
 "NotFoundError" exception.

Remove <var title="">child</var>
 from <var title="">parent</var>.

Return <var title="">child</var>.

To <dfn id="concept-node-remove" title="concept-node-remove">remove</dfn> a <var title="">node</var>
from a <var title="">parent</var>, optionally with
suppress observers flag set, run these steps:

Let <var title="">index</var> be <var title="">node</var>'s
 index.

For each range whose
 start node is a
 descendant of
 <var title="">node</var>, set its
 start to
 (<var title="">parent</var>, <var title="">index</var>).

For each range whose
 end node is a
 descendant of
 <var title="">node</var>, set its
 end to
 (<var title="">parent</var>, <var title="">index</var>).

For each range whose
 start node is
 <var title="">parent</var> and
 start offset is greater than
 <var title="">index</var>, decrease its
 start offset by one.

For each range whose
 end node is
 <var title="">parent</var> and
 end offset is greater than
 <var title="">index</var>, decrease its
 end offset by one.

If suppress observers flag is unset,
 queue a mutation record of "childList" for
 <var title="">parent</var> with removedNodes a list solely containing
 <var title="">node</var>, nextSibling <var title="">node</var>'s
 next sibling,
 and previousSibling <var title="">node</var>'s
 previous sibling.

For each ancestor
 <var title="">ancestor</var> of <var title="">node</var>, if
 <var title="">ancestor</var> has any
 registered observers whose
 options's
 subtree is true, then
 for each such registered observer <var title="">registered</var>, append a
 transient registered observer whose observer and
 options are identical to those of <var title="">registered</var> and source
 which is <var title="">registered</var> to <var title="">node</var>'s list of
 registered observers.

Remove <var title="">node</var> from its <var title="">parent</var>.

If suppress observers flag is unset, run
 node is removed for <var title="">node</var>.

5.2.2 Interface NonElementParentNode

The
getElementById() method is not
on elements for compatibility with older versions of
jQuery. If a time comes where that version of jQuery has disappeared, we might be able to
support it.

[NoInterfaceObject]
interface <dfn id="nonelementparentnode">NonElementParentNode</dfn> {
  Element? getElementById(DOMString <var title="">elementId</var>);
};
Document implements NonElementParentNode;
DocumentFragment implements NonElementParentNode;

<var title="">node</var> . getElementById(<var title="">elementId</var>)

Returns the first element within
 <var title="">node</var>'s descendants whose
 ID is <var title="">elementId</var>.

The
<dfn id="dom-nonelementparentnode-getelementbyid" title="dom-NonElementParentNode-getElementById">getElementById(<var>elementId</var>)</dfn>
method must return the first element, in
tree order, within context object's
descendants, whose
ID is <var title="">elementId</var>, and null if there is no
such element otherwise.

5.2.3 Interface ParentNode

The <dfn id="mutation-method-macro">mutation method macro</dfn>:

Let <var title="">node</var> be null.

Replace each string in <var title="">nodes</var> with a
 Text node whose
 data is the string value.

If <var title="">nodes</var> contains more than one
  node, set <var title="">node</var> to a new
  DocumentFragment and
  append each
  node in <var title="">nodes</var> to it. If
  this throws an exception, re-throw the exception.

Otherwise, set <var title="">node</var> to the single
  node <var title="">nodes</var> contains.

[NoInterfaceObject]
interface <dfn id="parentnode">ParentNode</dfn> {
  readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute unsigned long childElementCount;

  Element? querySelector(DOMString <var title="">selectors</var>);
  [NewObject] NodeList querySelectorAll(DOMString <var title="">selectors</var>);
};
Document implements ParentNode;
DocumentFragment implements ParentNode;
Element implements ParentNode;

<var title="">collection</var> = <var title="">node</var> . children

Returns the child
 elements.

<var title="">element</var> = <var title="">node</var> . firstElementChild

Returns the first child that
 is an element, and null otherwise.

<var title="">element</var> = <var title="">node</var> . lastElementChild

Returns the last child that
 is an element, and null otherwise.

<var title="">node</var> . querySelector(<var title="">selectors</var>)

Returns the first element that is a
  descendant of <var title="">node</var> that
  matches <var title="">selectors</var>.

<var title="">node</var> . querySelectorAll(<var title="">selectors</var>)

Returns all element
  descendants of <var title="">node</var> that
  match <var title="">selectors</var>.

The <dfn id="dom-parentnode-children" title="dom-ParentNode-children">children</dfn>
attribute must return an HTMLCollection
collection rooted at the
context object matching only
element
children.

The
<dfn id="dom-parentnode-firstelementchild" title="dom-ParentNode-firstElementChild">firstElementChild</dfn>
attribute must return the first child
that is an element, and null otherwise.

The
<dfn id="dom-parentnode-lastelementchild" title="dom-ParentNode-lastElementChild">lastElementChild</dfn>
attribute must return the last child
that is an element, and null otherwise.

The
<dfn id="dom-parentnode-childelementcount" title="dom-ParentNode-childElementCount">childElementCount</dfn>
attribute must return the number of
children of the
context object that are
elements.

To <dfn id="scope-match-a-selectors-string">scope-match a selectors string</dfn> <var title="">selectors</var> against a
<var title="">node</var>, run these steps:

Let <var title="">s</var> be the result of
 parse a selector <var title="">selectors</var>.
 [SELECTORS]

If <var title="">s</var> is failure, throw a
 JavaScript TypeError.

Return the result of evaluate a selector
 <var title="">s</var> against
 <var title="">node</var>'s root using
 scoping root <var title="">node</var> and
 scoping method
 scope-filtered.
 [SELECTORS].

The
<dfn id="dom-parentnode-queryselector" title="dom-ParentNode-querySelector">querySelector(<var>selectors</var>)</dfn>
method must return the first result of running scope-match a selectors string
<var title="">selectors</var> against the context object, and null if the result
is an empty list otherwise.

The
<dfn id="dom-parentnode-queryselectorall" title="dom-ParentNode-querySelectorAll">querySelectorAll(<var>selectors</var>)</dfn>
method must return the static result of
running scope-match a selectors string <var title="">selectors</var> against the
context object.

5.2.4 Interface NonDocumentTypeChildNode

The
previousElementSibling
and nextElementSibling
attributes have been removed from DocumentType nodes for compatibility
reasons. If these additions are deemed compatible enough in the future, they could be
reinstated.

[NoInterfaceObject]
interface <dfn id="nondocumenttypechildnode">NonDocumentTypeChildNode</dfn> {
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
};
Element implements NonDocumentTypeChildNode;
CharacterData implements NonDocumentTypeChildNode;

<var title="">element</var> = <var title="">node</var> . previousElementSibling

Returns the first
 preceding
 sibling that
 is an element, and null otherwise.

<var title="">element</var> = <var title="">node</var> . nextElementSibling

Returns the first
 following
 sibling that
 is an element, and null otherwise.

The
<dfn id="dom-nondocumenttypechildnode-previouselementsibling" title="dom-NonDocumentTypeChildNode-previousElementSibling">previousElementSibling</dfn>
attribute must return the first
preceding
sibling that is an
element, and null otherwise.

The
<dfn id="dom-nondocumenttypechildnode-nextelementsibling" title="dom-NonDocumentTypeChildNode-nextElementSibling">nextElementSibling</dfn>
attribute must return the first
following
sibling that is an
element, and null otherwise.

5.2.5 Interface ChildNode

[NoInterfaceObject]
interface <dfn id="childnode">ChildNode</dfn> {
  void remove();
};
DocumentType implements ChildNode;
Element implements ChildNode;
CharacterData implements ChildNode;

<var title="">node</var> . remove()

Removes <var title="">node</var>.

The
<dfn id="dom-childnode-remove" title="dom-ChildNode-remove">remove()</dfn>
method must run these steps:

If the context object does not have a
 parent, terminate these steps.

Remove the
 context object from the
 context object's
 parent.

5.2.6 Old-style collections: NodeList and HTMLCollection

A <dfn id="concept-collection" title="concept-collection">collection</dfn> is an object that
represents a lists of DOM nodes. A
collection can be either
<dfn id="concept-collection-live" title="concept-collection-live">live</dfn> or
<dfn id="concept-collection-static" title="concept-collection-static">static</dfn>. 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
<dfn id="represented-by-the-collection" title="represented by the collection">represents</dfn> 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.

5.2.6.1 Interface NodeList

A NodeList object is a
collection of
nodes.

interface <dfn id="nodelist">NodeList</dfn> {
  getter Node? item(unsigned long <var title="">index</var>);
  readonly attribute unsigned long length;
};

<var title="">collection</var> . length

Returns the number of nodes in the
  collection.

<var title="">element</var> = <var title="">collection</var> . item(<var title="">index</var>)

<var title="">element</var> = <var title="">collection</var>[<var title="">index</var>]

Returns the node with index
  <var title="">index</var> from the
  collection. The
  nodes are sorted in
  tree order.

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 <dfn id="dom-nodelist-length" title="dom-NodeList-length">length</dfn> attribute must
return the number of nodes represented by the collection.

The
<dfn id="dom-nodelist-item" title="dom-NodeList-item">item(<var title="">index</var>)</dfn>
method must return the <var title="">index</var>th
node in the collection. If there is no
<var title="">index</var>th node in the collection, then the method must return null.

5.2.6.2 Interface HTMLCollection

interface <dfn id="htmlcollection">HTMLCollection</dfn> {
  readonly attribute unsigned long length;
  getter Element? item(unsigned long <var title="">index</var>);
  getter Element? namedItem(DOMString <var title="">name</var>);
};

An HTMLCollection object is a
collection of
elements.

<var title="">collection</var> . length

Returns the number of elements in
  the collection.

<var title="">element</var> = <var title="">collection</var> . item(<var title="">index</var>)

<var title="">element</var> = <var title="">collection</var>[<var title="">index</var>]

Returns the element with index
  <var title="">index</var> from the collection.
  The elements are sorted in tree order.

<var title="">element</var> = <var title="">collection</var> . namedItem(<var title="">name</var>)

<var title="">element</var> = <var title="">collection</var>[<var title="">name</var>]

Returns the first element with ID or name <var title="">name</var>
  from the collection.

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 <dfn id="dom-htmlcollection-length" title="dom-HTMLCollection-length">length</dfn> attribute
must return the number of nodes represented by the collection.

The
<dfn id="dom-htmlcollection-item" title="dom-HTMLCollection-item">item(<var title="">index</var>)</dfn>
method must return the <var title="">index</var>th
element in the collection. If there is no
<var title="">index</var>th element in the collection, then the method must return null.

The supported property names, all
unenumerable, are the values from the list returned
by these steps:

Let <var title="">result</var> be an empty list.

For each <var title="">element</var>
  represented by the collection, in
  tree order, run these substeps:

If <var title="">element</var> has an
   ID which is neither the empty string nor is
   in <var title="">result</var>, append <var title="">element</var>'s
   ID to <var title="">result</var>.

If <var title="">element</var> is in the HTML namespace
   and has a
   name attribute
   whose value is neither the
   empty string nor is in <var title="">result</var>, append
   <var title="">element</var>'s
   name attribute
   value to <var title="">result</var>.

Return <var title="">result</var>.

The
<dfn id="dom-htmlcollection-nameditem" title="dom-HTMLCollection-namedItem">namedItem(<var title="">key</var>)</dfn>
method must run these steps:

If <var title="">key</var> is the empty string, return null.

Return the first element in the
  collection for which at least one of
  the following is true:

it has an ID which is <var title="">key</var>.

it has a
   name attribute
   whose value is
   <var title="">key</var>;

or null if there is no such element.

5.3 Mutation observers

Each
unit of related similar-origin browsing contexts has a
<dfn id="mutation-observer-compound-microtask-queued-flag">mutation observer compound microtask queued flag</dfn> and an associated list of
MutationObserver objects which is initially empty.
[HTML]

To <dfn id="queue-a-mutation-observer-compound-microtask">queue a mutation observer compound microtask</dfn>, run these steps:

If mutation observer compound microtask queued flag is set, terminate
 these steps.

Set mutation observer compound microtask queued flag.

Queue a
 compound microtask to
 notify mutation observers.

To <dfn id="notify-mutation-observers">notify mutation observers</dfn>, run these steps:

Unset mutation observer compound microtask queued flag.

Let <var title="">notify list</var> be a copy of
 unit of related similar-origin browsing contexts's
 list of MutationObserver objects.

For each MutationObserver object <var title="">mo</var>
  in <var title="">notify list</var>,
  execute a compound microtask subtask to run these
  steps:
  [HTML]

Let <var title="">queue</var> be a copy of <var title="">mo</var>'s
   record queue.

Empty <var title="">mo</var>'s
   record queue.

Remove all
   transient registered observers
   whose observer is <var title="">mo</var>.

If <var title="">queue</var> is non-empty, invoke
   <var title="">mo</var>'s callback
   with <var title="">queue</var> as first argument, and
   <var title="">mo</var> (itself) as second argument and
   callback this value.

Each node has an associated list of
registered observers.

A <dfn id="registered-observer">registered observer</dfn> consists of an observer (a
MutationObserver object) and options (a
MutationObserverInit dictionary). A
<dfn id="transient-registered-observer">transient registered observer</dfn> is a specific type of
registered observer that has a source which is a
registered observer.

5.3.1 Interface MutationObserver

[Constructor(MutationCallback <var>callback</var>)]
interface <dfn id="mutationobserver">MutationObserver</dfn> {
  void observe(Node <var>target</var>, MutationObserverInit <var>options</var>);
  void disconnect();
  sequence<MutationRecord> takeRecords();
};

callback <dfn id="mutationcallback">MutationCallback</dfn> = void (sequence<MutationRecord> <var>mutations</var>, MutationObserver <var>observer</var>);

dictionary <dfn id="mutationobserverinit">MutationObserverInit</dfn> {
  boolean childList = false;
  boolean attributes;
  boolean characterData;
  boolean subtree = false;
  boolean attributeOldValue;
  boolean characterDataOldValue;
  sequence<DOMString> attributeFilter;
};

A MutationObserver object can be used to observe mutations
to the tree of
nodes.

Each MutationObserver object has these associated concepts:

A <dfn id="concept-mo-callback" title="concept-MO-callback">callback</dfn> set on creation.

A list of nodes on which it is a registered observer's observer that is initially empty.

A list of MutationRecord objects called the
 <dfn id="concept-mo-queue" title="concept-MO-queue">record queue</dfn> that is initially empty.

<var title="">observer</var> = new MutationObserver(<var title="">callback</var>)

Constructs a MutationObserver object and sets its
 callback to
 <var title="">callback</var>. The <var title="">callback</var> is invoked with a
 list of MutationRecord objects as first argument and the
 constructed MutationObserver object as second argument. It is
 invoked after nodes registered with the
 observe() method, are
 mutated.

<var title="">observer</var> . observe(<var title="">target</var>, <var title="">options</var>)

Instructs the user agent to observe a given <var title="">target</var>
  (a node) and report any mutations based on
  the criteria given by <var title="">options</var> (an object).

The <var title="">options</var> argument allows for setting mutation
  observation options via object members. These are the object members that
  can be used:

childList

Set to true if mutations to <var title="">target</var>'s
   children are to be observed.

attributes

Set to true if mutations to <var title="">target</var>'s
   attributes are to be observed. Can be omitted if
   attributeOldValue and/or
   attributeFilter is
   specified.

characterData

Set to true if mutations to <var title="">target</var>'s
   data are to be observed. Can be omitted if
   characterDataOldValue
   is specified.

subtree

Set to true if mutations to not just <var title="">target</var>, but
   also <var title="">target</var>'s
   descendants are to be
   observed.

attributeOldValue

Set to true if
   attributes is true or omitted
   and <var title="">target</var>'s
   attribute
   value before the mutation
   needs to be recorded.

characterDataOldValue

Set to true if
   characterData
   is set to true or omitted and <var title="">target</var>'s
   data before the mutation
   needs to be recorded.

attributeFilter

Set to a list of attribute
   local names (without
   namespace) if not all
   attribute mutations need to be
   observed and attributes is true
   or omitted.

<var title="">observer</var> . disconnect()

Stops <var title="">observer</var> from observing any mutations.
 Until the observe() method
 is used again, <var title="">observer</var>'s
 callback will not be invoked.

<var title="">observer</var> . takeRecords()

Empties the record queue and
 returns what was in there.

The
<dfn id="dom-mutationobserver" title="dom-MutationObserver">MutationObserver(<var>callback</var>)</dfn>
constructor must create a new MutationObserver object with
callback set to <var>callback</var>,
append it to the
unit of related similar-origin browsing contexts's list
of MutationObserver objects, and then return it.

The
<dfn id="dom-mutationobserver-observe" title="dom-MutationObserver-observe">observe(<var title="">target</var>, <var title="">options</var>)</dfn>
method must run these steps:

If either <var title="">options</var>'
 attributeOldValue or
 attributeFilter is present
 and <var title="">options</var>'
 attributes is omitted, set
 <var title="">options</var>'
 attributes to true.

If <var title="">options</var>'
 characterDataOldValue
 is present and <var title="">options</var>'
 characterData is omitted, set
 <var title="">options</var>'
 characterData to true.

If <var title="">options</var>'
 attributeOldValue is true
 and <var title="">options</var>'
 attributes is false,
 throw a JavaScript TypeError.

If <var title="">options</var>'
 attributeFilter is present
 and <var title="">options</var>'
 attributes is false,
 throw a JavaScript TypeError.

If <var title="">options</var>'
 characterDataOldValue
 is true and <var title="">options</var>'
 characterData is false,
 throw a JavaScript TypeError.

For each registered observer <var title="">registered</var> in
  <var title="">target</var>'s list of
  registered observers whose observer is
  the context object:

Remove all
   transient registered observers whose
   source is <var title="">registered</var>.

Replace <var title="">registered</var>'s options with
   <var title="">options</var>.

Otherwise, add a new registered observer to
 <var title="">target</var>'s list of
 registered observers with the
 context object as the observer and <var title="">options</var> as the options,
 and add <var title="">target</var> to context object's list of nodes on which it is registered.

The
<dfn id="dom-mutationobserver-disconnect" title="dom-MutationObserver-disconnect">disconnect()</dfn>
method must, for each node
<var title="">node</var> in the context object's list of
nodes, remove any
registered observer on <var title="">node</var>
for which the context object is the observer, and also
empty context object's
record queue.

The
<dfn id="dom-mutationobserver-takerecords" title="dom-MutationObserver-takeRecords">takeRecords()</dfn>
method must return a copy of the
record queue and then empty the
record queue.

5.3.2 Queuing a mutation record

To <dfn id="queue-a-mutation-record">queue a mutation record</dfn> of <var title="">type</var> for
<var title="">target</var> with one or more of (depends on
<var title="">type</var>) name <var title="">name</var>, namespace
<var title="">namespace</var>, oldValue <var title="">oldValue</var>, addedNodes
<var title="">addedNodes</var>, removedNodes <var title="">removedNodes</var>,
previousSibling <var title="">previousSibling</var>, and nextSibling
<var title="">nextSibling</var>, run these steps:

Let <var title="">interested observers</var> be an initially empty set
 of MutationObserver objects optionally paired with a string.

Let <var title="">nodes</var> be the
 inclusive ancestors of
 <var title="">target</var>.

Then, for each <var title="">node</var> in <var title="">nodes</var>, and
  then for each <var title="">registered observer</var> (with
  <var title="">registered observer</var>'s options as
  <var title="">options</var>) in <var title="">node</var>'s list of
  registered observers:

If <var title="">node</var> is not <var title="">target</var> and
   <var title="">options</var>'s subtree is false, continue.

If <var title="">type</var> is "attributes" and
   <var title="">options</var>'s attributes is not true, continue.

If <var title="">type</var> is "attributes",
   <var title="">options</var>'s attributeFilter is present, and either
   <var title="">options</var>'s attributeFilter does not contain
   <var title="">name</var> or <var title="">namespace</var> is non-null, continue.

If <var title="">type</var> is "characterData" and
   <var title="">options</var>'s characterData is not true, continue.

If <var title="">type</var> is "childList" and
   <var title="">options</var>'s childList is false, continue.

If <var title="">registered observer</var>'s observer is
   not in <var title="">interested observers</var>, append
   <var title="">registered observer</var>'s observer to
   <var title="">interested observers</var>.

If either <var title="">type</var> is "attributes"
   and <var title="">options</var>'s attributeOldValue is true, or
   <var title="">type</var> is "characterData" and
   <var title="">options</var>'s characterDataOldValue is true,
   set the paired string of
   <var title="">registered observer</var>'s observer in
   <var title="">interested observers</var> to <var title="">oldValue</var>.

Then, for each <var title="">observer</var> in
  <var title="">interested observers</var>:

Let <var title="">record</var> be a new MutationRecord
   object with its type set to
   <var title="">type</var> and
   target set to
   <var title="">target</var>.

If <var title="">name</var> and <var title="">namespace</var> are given,
   set <var title="">record</var>'s
   attributeName to
   <var title="">name</var>, and <var title="">record</var>'s
   attributeNamespace
   to <var title="">namespace</var>.

If <var title="">addedNodes</var> is given, set <var title="">record</var>'s
   addedNodes to
   <var title="">addedNodes</var>.

If <var title="">removedNodes</var> is given, set <var title="">record</var>'s
   removedNodes to
   <var title="">removedNodes</var>,

If <var title="">previousSibling</var> is given, set <var title="">record</var>'s
   previousSibling to
   <var title="">previousSibling</var>.

If <var title="">nextSibling</var> is given, set <var title="">record</var>'s
   nextSibling to
   <var title="">nextSibling</var>.

If <var title="">observer</var> has a paired string,
   set <var title="">record</var>'s oldValue to
   <var title="">observer</var>'s paired string.

Append <var title="">record</var> to <var title="">observer</var>'s
   record queue.

Queue a mutation observer compound microtask.

5.3.3 Interface MutationRecord

interface <dfn id="mutationrecord">MutationRecord</dfn> {
  readonly attribute DOMString type;
  readonly attribute Node target;
  [SameObject] readonly attribute NodeList addedNodes;
  [SameObject] readonly attribute NodeList removedNodes;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;
  readonly attribute DOMString? attributeName;
  readonly attribute DOMString? attributeNamespace;
  readonly attribute DOMString? oldValue;
};

<var title="">record</var> . type

Returns "attributes" if it was an
 attribute mutation.
 "characterData" if it was a mutation to a
 CharacterData node. And
 "childList" if it was a mutation to the
 tree of
 nodes.

<var title="">record</var> . target

Returns the node the mutation
 affected, depending on the type.
 For "attributes", it is the
 element whose
 attribute changed. For
 "characterData", it is the CharacterData
 node. For "childList",
 it is the  node whose
 children changed.

<var title="">record</var> . addedNodes

<var title="">record</var> . removedNodes

Return the nodes added and removed
 respectively.

<var title="">record</var> . previousSibling

<var title="">record</var> . nextSibling

Return the previous
 and next sibling respectively
 of the added or removed nodes, and null
 otherwise.

<var title="">record</var> . attributeName

Returns the
 local name of the
 changed attribute, and null otherwise.

<var title="">record</var> . attributeNamespace

Returns the namespace of the
 changed attribute, and null otherwise.

<var title="">record</var> . oldValue

The return value depends on
 type. For
 "attributes", it is the
 value of the
 changed attribute before the change.
 For "characterData", it is the
 data of the changed
 node before the change. For
 "childList", it is null.

The <dfn id="dom-mutationrecord-type" title="dom-MutationRecord-type">type</dfn> and
<dfn id="dom-mutationrecord-target" title="dom-MutationRecord-target">target</dfn>
attributes must return the values they were initialized to.

The
<dfn id="dom-mutationrecord-addednodes" title="dom-MutationRecord-addedNodes">addedNodes</dfn> and
<dfn id="dom-mutationrecord-removednodes" title="dom-MutationRecord-removedNodes">removedNodes</dfn>
attributes must return the values they were initialized to. Unless stated
otherwise, when a MutationRecord object is created, they must
both be initialized to an empty NodeList.

The
<dfn id="dom-mutationrecord-previoussibling" title="dom-MutationRecord-previousSibling">previousSibling</dfn>,
<dfn id="dom-mutationrecord-nextsibling" title="dom-MutationRecord-nextSibling">nextSibling</dfn>,
<dfn id="dom-mutationrecord-attributename" title="dom-MutationRecord-attributeName">attributeName</dfn>,
<dfn id="dom-mutationrecord-attributenamespace" title="dom-MutationRecord-attributeNamespace">attributeNamespace</dfn>, and
<dfn id="dom-mutationrecord-oldvalue" title="dom-MutationRecord-oldValue">oldValue</dfn>
attributes must return the values they were initialized to. Unless stated
otherwise, when a MutationRecord object is created, they must
be initialized to null.

5.3.4 Garbage collection

Nodes have a strong reference to
registered observers in their
list of registered observers.

Registered observers in a
node's list of
registered observers have a weak
reference to the node.

5.4 Interface Node

interface <dfn id="node">Node</dfn> : 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();
  [SameObject] readonly attribute NodeList childNodes;
  readonly attribute Node? firstChild;
  readonly attribute Node? lastChild;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;

           attribute DOMString? nodeValue;
           attribute DOMString? textContent;
  void normalize();

  Node cloneNode(optional boolean <var title="">deep</var> = false);
  boolean isEqualNode(Node? <var title="">node</var>);

  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 <var title="">other</var>);
  boolean contains(Node? <var title="">other</var>);

  DOMString? lookupPrefix(DOMString? <var title="">namespace</var>);
  DOMString? lookupNamespaceURI(DOMString? <var title="">prefix</var>);
  boolean isDefaultNamespace(DOMString? <var title="">namespace</var>);

  Node insertBefore(Node <var title="">node</var>, Node? <var title="">child</var>);
  Node appendChild(Node <var title="">node</var>);
  Node replaceChild(Node <var title="">node</var>, Node <var title="">child</var>);
  Node removeChild(Node <var title="">child</var>);
};

Node is an abstract interface and does not exist
as node. It is used by all
nodes (Document,
DocumentFragment, DocumentType,
Element, Text, ProcessingInstruction,
and Comment).

Each node has an associated
<dfn id="concept-node-document" title="concept-node-document">node document</dfn>, set upon creation,
that is a document.

A node's
node document can be changed by
the adopt algorithm.

Each node also has an associated
<dfn id="concept-node-base-url" title="concept-node-base-url">base URL</dfn>.

Other specifications define the value of the
base URL and its observable
behavior. This specification solely defines the concept and the
baseURI attribute.

<var title="">node</var> . nodeType

Returns the type of <var title="">node</var>, represented by a number from the following list:

Node . ELEMENT_NODE (1)

<var title="">node</var> is an
   element.

Node . TEXT_NODE (3)

<var title="">node</var> is a Text
   node.

Node . PROCESSING_INSTRUCTION_NODE (7)

<var title="">node</var> is a ProcessingInstruction
   node.

Node . COMMENT_NODE (8)

<var title="">node</var> is a Comment
   node.

Node . DOCUMENT_NODE (9)

<var title="">node</var> is a
   document.

Node . DOCUMENT_TYPE_NODE (10)

<var title="">node</var> is a
   doctype.

Node . DOCUMENT_FRAGMENT_NODE (11)

<var title="">node</var> is a DocumentFragment
   node.

<var title="">node</var> . nodeName

Returns a string appropriate for the type of <var title="">node</var>, as
  follows:

Element

Its tagName attribute value.

Text

"#text".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

The <dfn id="dom-node-nodetype" title="dom-Node-nodeType">nodeType</dfn> attribute
must return the type of the node, which must be one of the following:

<dfn id="dom-node-element_node" title="dom-Node-ELEMENT_NODE">ELEMENT_NODE</dfn> (1);

<dfn id="dom-node-text_node" title="dom-Node-TEXT_NODE">TEXT_NODE</dfn> (3);

<dfn id="dom-node-processing_instruction_node" title="dom-Node-PROCESSING_INSTRUCTION_NODE">PROCESSING_INSTRUCTION_NODE</dfn> (7);

<dfn id="dom-node-comment_node" title="dom-Node-COMMENT_NODE">COMMENT_NODE</dfn> (8);

<dfn id="dom-node-document_node" title="dom-Node-DOCUMENT_NODE">DOCUMENT_NODE</dfn> (9);

<dfn id="dom-node-document_type_node" title="dom-Node-DOCUMENT_TYPE_NODE">DOCUMENT_TYPE_NODE</dfn> (10);

<dfn id="dom-node-document_fragment_node" title="dom-Node-DOCUMENT_FRAGMENT_NODE">DOCUMENT_FRAGMENT_NODE</dfn> (11).

The <dfn id="dom-node-nodename" title="dom-Node-nodeName">nodeName</dfn> attribute
must return the following, depending on the context object:

Element

Its tagName attribute value.

Text

"#text".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

<var title="">node</var> . baseURI

Returns the base URL.

The <dfn id="dom-node-baseuri" title="dom-Node-baseURI">baseURI</dfn> attribute must return the associated base URL.

<var title="">node</var> . ownerDocument

Returns the node document.

Returns null for documents.

<var title="">node</var> . parentNode

Returns the parent.

<var title="">node</var> . parentElement

Returns the parent element.

<var title="">node</var> . hasChildNodes()

Returns whether <var title="">node</var> has
 children.

<var title="">node</var> . childNodes

Returns the children.

<var title="">node</var> . firstChild

Returns the first child.

<var title="">node</var> . lastChild

Returns the last child.

<var title="">node</var> . previousSibling

Returns the
 previous sibling.

<var title="">node</var> . nextSibling

Returns the
 next sibling.

The <dfn id="dom-node-ownerdocument" title="dom-Node-ownerDocument">ownerDocument</dfn>
attribute must run these steps:

If the context object is a
 document, return null.

Return the node document.

The node document of a
document is that
document itself.

All nodes have a
document at all times.

The <dfn id="dom-node-parentnode" title="dom-Node-parentNode">parentNode</dfn>
attribute must return the parent.

The <dfn id="dom-node-parentelement" title="dom-Node-parentElement">parentElement</dfn>
attribute must return the parent element.

The <dfn id="dom-node-haschildnodes" title="dom-Node-hasChildNodes">hasChildNodes()</dfn>
method must return true if the context object has
children, and false otherwise.

The <dfn id="dom-node-childnodes" title="dom-Node-childNodes">childNodes</dfn>
attribute must return a NodeList rooted at the
context object matching only
children.

The <dfn id="dom-node-firstchild" title="dom-Node-firstChild">firstChild</dfn>
attribute must return the
first child.

The <dfn id="dom-node-lastchild" title="dom-Node-lastChild">lastChild</dfn> attribute must return the last child.

The
<dfn id="dom-node-previoussibling" title="dom-Node-previousSibling">previousSibling</dfn>
attribute must return the
previous sibling.

The <dfn id="dom-node-nextsibling" title="dom-Node-nextSibling">nextSibling</dfn>
attribute must return the
next sibling.

The <dfn id="dom-node-nodevalue" title="dom-Node-nodeValue">nodeValue</dfn> attribute
must return the following, depending on the context object:

Text

Comment

ProcessingInstruction

The context object's
 data.

Any other node

Null.

The nodeValue attribute must,
on setting, if the new value is null, act as if it was the empty string
instead, and then do as described below, depending on the context object:

Text

Comment

ProcessingInstruction

Replace data with node
 context object, offset 0, count
 length attribute value, and
 data new value.

Any other node

Do nothing.

The <dfn id="dom-node-textcontent" title="dom-Node-textContent">textContent</dfn>
attribute must return the following, depending on the
context object:

DocumentFragment

Element

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

Text

ProcessingInstruction

Comment

The context object's
 data.

Any other node

Null.

The textContent attribute must,
on setting, if the new value is null, act as if it was the empty string
instead, and then do as described below, depending on the context object:

DocumentFragment

Element

Let <var title="">node</var> be null.

If new value is not the empty string, set <var title="">node</var> to
   a new Text node whose
   data is new value.

Replace all with
   <var title="">node</var> within the context object.

Text

ProcessingInstruction

Comment

Replace data with node
 context object, offset 0, count
 length attribute value, and
 data new value.

Any other node

Do nothing.

<var title="">node</var> . normalize()

Removes empty
 Text nodes and concatenates
 the data of remaining
 contiguous Text nodes into the first of their
 nodes.

The <dfn id="dom-node-normalize" title="dom-Node-normalize">normalize()</dfn> method
must run these steps:

For each Text node
descendant of the
context object:

Let <var title="">node</var> be the Text
 node
 descendant.

Let <var title="">length</var> be <var title="">node</var>'s
 length attribute value.

If <var title="">length</var> is zero,
 remove <var title="">node</var> and
 continue with the next Text
 node, if any.

Let <var title="">data</var> be the concatenation of the
 data of <var title="">node</var>'s
 contiguous Text nodes (excluding itself), in
 tree order.

Replace data with node
 <var title="">node</var>, offset <var title="">length</var>,
 count 0, and data <var title="">data</var>.

Let <var title="">current node</var> be <var title="">node</var>'s
 next sibling.

While <var title="">current node</var> is a Text node:

For each range whose
  start node is
  <var title="">current node</var>, add <var title="">length</var> to its
  start offset and set its
  start node to
  <var title="">node</var>.

For each range whose
  end node is
  <var title="">current node</var>, add <var title="">length</var> to its
  end offset and set its
  end node to
  <var title="">node</var>.

For each range whose
  start node is
  <var title="">current node</var>'s
  parent and
  start offset is
  <var title="">current node</var>'s
  index, set its
  start node to
  <var title="">node</var> and its
  start offset to
  <var title="">length</var>.

For each range whose
  end node is
  <var title="">current node</var>'s
  parent and
  end offset is
  <var title="">current node</var>'s
  index, set its
  end node to
  <var title="">node</var> and its
  end offset to
  <var title="">length</var>.

Add <var title="">current node</var>'s
  length attribute value to
  <var title="">length</var>.

Set <var title="">current node</var> to its
  next sibling.

Remove
 <var title="">node</var>'s
 contiguous Text nodes (excluding itself), in
 tree order.

<var title="">node</var> . cloneNode([<var title="">deep</var> = false])

Returns a copy of <var title="">node</var>. If
 <var title="">deep</var> is true, the copy also includes the
 <var title="">node</var>'s descendants.

<var title="">node</var> . isEqualNode(<var title="">other</var>)

Returns whether <var title="">node</var> and <var title="">other</var>
 have the same properties.

Specifications may define
<dfn id="concept-node-clone-ext" title="concept-node-clone-ext">cloning steps</dfn> for all or some
nodes. The algorithm is passed <var title="">copy</var>,
<var title="">node</var>, <var title="">document</var>, and optionally a
clone children flag, as indicated in the
clone algorithm.

HTML defines
cloning steps for
script and
input elements. SVG ought to do the same
for its script elements, but does not call this out at
the moment.

To <dfn id="concept-node-clone" title="concept-node-clone">clone</dfn> a <var title="">node</var>,
optionally with a <var title="">document</var> and a clone children flag, run
these steps:

If <var title="">document</var> is not given, let <var title="">document</var> be
 <var title="">node</var>'s node document.

Let <var title="">copy</var> be a node
 that implements the same interfaces as <var title="">node</var>.

If <var title="">copy</var> is a
  document, set its
  node document and
  <var title="">document</var> to <var title="">copy</var>.

Otherwise, set <var title="">copy</var>'s
  node document to
  <var title="">document</var>.

Copy the following from <var title="">node</var> to <var title="">copy</var>, depending on
  the type of <var title="">node</var>:

Document

Its encoding,
   content type,
   URL, its mode
   (quirks mode,
   limited quirks mode, or
   no-quirks mode), and its type
   (XML document or HTML document).

DocumentType

Its name,
   public ID, and
   system ID.

Element

Its namespace,
   namespace prefix,
   local name, and its
   attribute list.

Text

Comment

Its data.

ProcessingInstruction

Its target and
   data.

Any other node

—

Run any cloning steps
 defined for <var title="">node</var> in other applicable specifications and
 pass <var title="">copy</var>, <var title="">node</var>, <var title="">document</var> and the
 clone children flag if set, as parameters.

If the clone children flag is set,
 clone all the
 children of <var title="">node</var> and
 append them to <var title="">copy</var>, with <var title="">document</var>
 as specified and the clone children flag being set.

Return <var title="">copy</var>.

The
<dfn id="dom-node-clonenode" title="dom-Node-cloneNode">cloneNode(<var title="">deep</var>)</dfn>
method must return a clone of the
context object, with the clone children flag set
if <var title="">deep</var> is true.

A node <var title="">A</var>
<dfn id="concept-node-equals" title="concept-node-equals">equals</dfn> a node
<var title="">B</var> if all of the following conditions are true:

<var title="">A</var> and <var title="">B</var>'s
 nodeType attribute value is identical.

The following are also equal, depending on <var title="">A</var>:

DocumentType

Its name,
   public ID, and
   system ID.

Element

Its namespace,
    namespace prefix,
    local name, and its
    number of attributes in its
    attribute list.

ProcessingInstruction

Its target and
   data.

Text

Comment

Its data.

Any other node

—

If <var title="">A</var> is an element, each
 attribute in its
 attribute list has an
 attribute with the same
 namespace,
 local name, and
 value in <var title="">B</var>'s
 attribute list.

<var title="">A</var> and <var title="">B</var> have the same number of
 children.

Each child of <var title="">A</var>
 equals the
 child of <var title="">B</var> at the identical
 index.

The
<dfn id="dom-node-isequalnode" title="dom-Node-isEqualNode">isEqualNode(<var title="">node</var>)</dfn>
method must return true if <var title="">node</var> is not null and
context object equals
<var title="">node</var>, and false otherwise.

<var title="">node</var> . compareDocumentPosition(<var title="">other</var>)

Returns a bitmask indicating the position of <var title="">other</var>
  relative to <var title="">node</var>. These are the bits that can be set:

Node . DOCUMENT_POSITION_DISCONNECTED (1)

Set when <var title="">node</var> and <var>other</var> are not in the
   same tree.

Node . DOCUMENT_POSITION_PRECEDING (2)

Set when <var title="">other</var> is
   preceding
   <var title="">node</var>.

Node . DOCUMENT_POSITION_FOLLOWING (4)

Set when <var title="">other</var> is
   following
   <var title="">node</var>.

Node . DOCUMENT_POSITION_CONTAINS (8)

Set when <var title="">other</var> is an
   ancestor of
   <var title="">node</var>.

Node . DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)

Set when <var title="">other</var> is a
   descendant of
   <var title="">node</var>.

<var title="">node</var> . contains(<var title="">other</var>)

Returns true if <var title="">other</var> is an
 inclusive descendant
 of <var title="">node</var>, and false otherwise.

These are the constants
compareDocumentPosition()
returns as mask:

<dfn id="dom-node-document_position_disconnected" title="dom-Node-DOCUMENT_POSITION_DISCONNECTED">DOCUMENT_POSITION_DISCONNECTED</dfn> (1);

<dfn id="dom-node-document_position_preceding" title="dom-Node-DOCUMENT_POSITION_PRECEDING">DOCUMENT_POSITION_PRECEDING</dfn> (2);

<dfn id="dom-node-document_position_following" title="dom-Node-DOCUMENT_POSITION_FOLLOWING">DOCUMENT_POSITION_FOLLOWING</dfn> (4);

<dfn id="dom-node-document_position_contains" title="dom-Node-DOCUMENT_POSITION_CONTAINS">DOCUMENT_POSITION_CONTAINS</dfn> (8);

<dfn id="dom-node-document_position_contained_by" title="dom-Node-DOCUMENT_POSITION_CONTAINED_BY">DOCUMENT_POSITION_CONTAINED_BY</dfn> (16, 10 in hexadecimal);

<dfn id="dom-node-document_position_implementation_specific" title="dom-Node-DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC">DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC</dfn> (32, 20 in hexadecimal).

The <dfn id="dom-node-comparedocumentposition" title="dom-Node-compareDocumentPosition">compareDocumentPosition(<var>other</var>)</dfn>
method must run these steps:

Let <var title="">reference</var> be the context object.

If <var title="">other</var> and <var title="">reference</var> are the
 same object, return zero.

If <var title="">other</var> and <var title="">reference</var> are not
  in the same tree, return the result of
  adding
  DOCUMENT_POSITION_DISCONNECTED,
  DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC,
  and either
  DOCUMENT_POSITION_PRECEDING or
  DOCUMENT_POSITION_FOLLOWING,
  with the constraint that this is to be consistent, together.

Whether to return
  DOCUMENT_POSITION_PRECEDING or
  DOCUMENT_POSITION_FOLLOWING
  is typically implemented via pointer comparison. In JavaScript
  implementations Math.random() can be used.

If <var title="">other</var> is an
 ancestor of
 <var title="">reference</var>, return the result of adding
 DOCUMENT_POSITION_CONTAINS
 to
 DOCUMENT_POSITION_PRECEDING.

If <var title="">other</var> is a
 descendant of
 <var title="">reference</var>, return the result of adding
 DOCUMENT_POSITION_CONTAINED_BY
 to
 DOCUMENT_POSITION_FOLLOWING.

If <var title="">other</var> is
 preceding
 <var title="">reference</var> return
 DOCUMENT_POSITION_PRECEDING.

Return
 DOCUMENT_POSITION_FOLLOWING.

The
<dfn id="dom-node-contains" title="dom-Node-contains">contains(<var title="">other</var>)</dfn>
method must return true if <var title="">other</var> is an
inclusive descendant of
the context object, and false otherwise (including when
<var title="">other</var> is null).

To <dfn id="locate-a-namespace-prefix">locate a namespace prefix</dfn> for an <var title="">element</var> using
<var title="">namespace</var> run these steps:

If <var title="">element</var>'s
 namespace is
 <var title="">namespace</var> and its
 namespace prefix is not
 null, return its
 namespace prefix.

If, <var title="">element</var>
 has an
 attribute whose
 namespace prefix is
 "xmlns" and
 value is
 <var title="">namespace</var>, then return <var title="">element</var>'s first
 such attribute's
 local name.

If <var title="">element</var>'s parent element is not null,
 return the result of running locate a namespace prefix on that
 element using <var title="">namespace</var>.
 Otherwise, return null.

To <dfn id="locate-a-namespace">locate a namespace</dfn> for a <var title="">node</var> using
<var title="">prefix</var> depends on <var title="">node</var>:

Element

If its namespace is
   not null and its
   namespace prefix is
   <var title="">prefix</var>, return
   namespace.

If it has an
    attribute whose
    namespace is the
    XMLNS namespace,
    namespace prefix
    is "xmlns" and
    local name is
    <var title="">prefix</var>, or if <var title="">prefix</var> is null and it
    has an
    attribute whose
    namespace is the
    XMLNS namespace,
    namespace prefix
    is null and local name
    is "xmlns":

Let <var title="">value</var> be its
     value if it is not the empty
     string, and null otherwise.

Return <var title="">value</var>.

If its parent element is null, return null.

Return the result of running locate a namespace on
   its parent element using <var title="">prefix</var>.

Document

If its document element is null, return null.

Return the result of running locate a namespace on
   its document element using <var title="">prefix</var>.

DocumentType

DocumentFragment

Return null.

Any other node

If its parent element is null, return null.

Return the result of running locate a namespace on
   its parent element using <var title="">prefix</var>.

The
<dfn id="dom-node-lookupprefix" title="dom-Node-lookupPrefix">lookupPrefix(<var title="">namespace</var>)</dfn>
method must run these steps:

If <var title="">namespace</var> is null or the empty string, return null.

Otherwise it depends on the context object:

Element

Return the result of
   locating a namespace prefix
   for the node using <var title="">namespace</var>.

Document

Return the result of
   locating a namespace prefix
   for its document element, if that is not null, and 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
<dfn id="dom-node-lookupnamespaceuri" title="dom-Node-lookupNamespaceURI">lookupNamespaceURI(<var title="">prefix</var>)</dfn>
method must run these steps:

If <var title="">prefix</var> is the empty string, set it to null.

Return the result of running locate a namespace for the
 context object using <var title="">prefix</var>.

The
<dfn id="dom-node-isdefaultnamespace" title="dom-Node-isDefaultNamespace">isDefaultNamespace(<var title="">namespace</var>)</dfn>
method must run these steps:

If <var title="">namespace</var> is the empty string, set it to null.

Let <var title="">defaultNamespace</var> be the result of running
 locate a namespace for the context object using
 null.

Return true if <var title="">defaultNamespace</var> is the same as
 <var title="">namespace</var>, and false otherwise.

The
<dfn id="dom-node-insertbefore" title="dom-Node-insertBefore">insertBefore(<var>node</var>, <var>child</var>)</dfn>
method must return the result of
pre-inserting
<var title="">node</var> into the context object before
<var title="">child</var>.

The
<dfn id="dom-node-appendchild" title="dom-Node-appendChild">appendChild(<var>node</var>)</dfn>
method must return the result of
appending <var title="">node</var> to
the context object.

The
<dfn id="dom-node-replacechild" title="dom-Node-replaceChild">replaceChild(<var>node</var>, <var>child</var>)</dfn>
method must return the result of
replacing <var title="">child</var>
with <var title="">node</var> within the context object.

The
<dfn id="dom-node-removechild" title="dom-Node-removeChild">removeChild(<var>child</var>)</dfn>
method must return the result of
pre-removing
<var title="">child</var> from the context object.

The
<dfn id="concept-getelementsbytagname" title="concept-getElementsByTagName">list of elements with local name <var title="">localName</var></dfn>
for a node <var title="">root</var> is the
HTMLCollection returned by the following algorithm:

If <var title="">localName</var> is "*" (U+002A),
 return a HTMLCollection rooted at <var title="">root</var>,
 whose filter matches only elements.

Otherwise, if <var title="">root</var>'s
  node document is an
  HTML document, return a HTMLCollection rooted at
  <var title="">root</var>, whose filter matches only the following
  elements:

Whose namespace is the
   HTML namespace and whose
   local name is
   <var title="">localName</var> converted to ASCII lowercase.

Whose namespace is
   not the HTML namespace and whose
   local name is
   <var title="">localName</var>.

Otherwise, return a HTMLCollection rooted at
 <var title="">root</var>, whose filter matches only
 elements whose
 local name is
 <var title="">localName</var>.

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

The
<dfn id="concept-getelementsbytagnamens" title="concept-getElementsByTagNameNS">list of elements with namespace <var title="">namespace</var> and local name <var title="">localName</var></dfn>
for a node <var title="">root</var> is the
HTMLCollection returned by the following algorithm:

If <var title="">namespace</var> is the empty string, set it to null.

If both <var title="">namespace</var> and <var title="">localName</var>
 are "*" (U+002A) return a HTMLCollection rooted at
 <var title="">root</var>, whose filter matches only
 elements.

Otherwise, if just <var title="">namespace</var> is "*"
 (U+002A), return a HTMLCollection rooted at
 <var title="">root</var>, whose filter matches only
 elements whose
 local name is
 <var title="">localName</var>.

Otherwise, if just <var title="">localName</var> is "*"
 (U+002A), return a HTMLCollection rooted at
 <var title="">root</var>, whose filter matches only
 elements whose
 namespace is
 <var title="">namespace</var>.

Otherwise, return a HTMLCollection rooted at
 <var title="">root</var>, whose filter matches only
 elements whose
 namespace is
 <var title="">namespace</var> and
 local name is
 <var title="">localName</var>.

When invoked with the same arguments, the same HTMLCollection
object may be returned as returned by an earlier call.

The
<dfn id="concept-getelementsbyclassname" title="concept-getElementsByClassName">list of elements with class names <var title="">classNames</var></dfn>
for a node <var title="">root</var> is the
HTMLCollection returned by the following algorithm:

Let <var title="">classes</var> be the result of running the
  ordered set parser on
  <var title="">classNames</var>.

If <var title="">classes</var> is the empty set, return an empty
  HTMLCollection.

Return a HTMLCollection rooted at <var title="">root</var>,
  whose filter matches only
  elements that have all the
  classes in <var title="">classes</var>.

If <var title="">root</var>'s
  node document is in
  quirks mode, then the
  comparisons for the classes must be done
  in an ASCII case-insensitive manner, and in a
  case-sensitive manner otherwise.

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

5.5 Interface Document

[Constructor]
interface <dfn id="document">Document</dfn> : Node {
  [SameObject] readonly attribute DOMImplementation implementation;
  readonly attribute DOMString URL;
  readonly attribute DOMString documentURI;
  readonly attribute DOMString compatMode;
  readonly attribute DOMString characterSet;
  readonly attribute DOMString contentType;

  readonly attribute DocumentType? doctype;
  readonly attribute Element? documentElement;
  HTMLCollection getElementsByTagName(DOMString <var title="">localName</var>);
  HTMLCollection getElementsByTagNameNS(DOMString? <var title="">namespace</var>, DOMString <var title="">localName</var>);
  HTMLCollection getElementsByClassName(DOMString <var title="">classNames</var>);

  [NewObject] Element createElement(DOMString <var title="">localName</var>);
  [NewObject] Element createElementNS(DOMString? <var title="">namespace</var>, DOMString <var title="">qualifiedName</var>);
  [NewObject] DocumentFragment createDocumentFragment();
  [NewObject] Text createTextNode(DOMString <var title="">data</var>);
  [NewObject] Comment createComment(DOMString <var title="">data</var>);
  [NewObject] ProcessingInstruction createProcessingInstruction(DOMString <var title="">target</var>, DOMString <var title="">data</var>);

  Node importNode(Node <var title="">node</var>, optional boolean <var title="">deep</var> = false);
  Node adoptNode(Node <var title="">node</var>);

  [NewObject] Event createEvent(DOMString <var title="">interface</var>);

  [NewObject] Range createRange();

  // NodeFilter.SHOW_ALL = 0xFFFFFFFF
  [NewObject] NodeIterator createNodeIterator(Node <var title="">root</var>, optional unsigned long <var title="">whatToShow</var> = 0xFFFFFFFF, optional NodeFilter? <var title="">filter</var> = null);
  [NewObject] TreeWalker createTreeWalker(Node <var title="">root</var>, optional unsigned long <var title="">whatToShow</var> = 0xFFFFFFFF, optional NodeFilter? <var title="">filter</var> = null);
};

interface <dfn id="xmldocument">XMLDocument</dfn> : Document {};

Document nodes are simply
known as <dfn id="concept-document" title="concept-document">documents</dfn>.

Each document has an associated
<dfn id="concept-document-encoding" title="concept-document-encoding">encoding</dfn>,
<dfn id="concept-document-content-type" title="concept-document-content-type">content type</dfn>, and
<dfn id="concept-document-url" title="concept-document-url">URL</dfn>.
[ENCODING]
[URL]

Unless stated otherwise, a document's
encoding is the
utf-8
encoding, its
content type is
"application/xml", and its
URL is
"about:blank".

Unless stated otherwise, a document's
origin is a globally unique identifier
and its effective script origin is an
alias of that
origin.
[HTML]

A document is assumed to be an
<dfn id="xml-document">XML document</dfn> unless it is flagged as being an
<dfn id="html-document">HTML document</dfn>. Whether a
document is an
HTML document or an XML document affects the
behavior of certain APIs.

A document is always set to one of
three modes: <dfn id="concept-document-no-quirks" title="concept-document-no-quirks">no-quirks mode</dfn>, the
default; <dfn id="concept-document-quirks" title="concept-document-quirks">quirks mode</dfn>, used
typically for legacy documents; and
<dfn id="concept-document-limited-quirks" title="concept-document-limited-quirks">limited-quirks mode</dfn>. Unless stated
otherwise, a document must be in
no-quirks mode.

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

No-quirks mode
was originally known as "standards mode" and
limited-quirks mode was
once known as "almost standards mode". They have been renamed because their
details are now defined by standards. (And because Ian Hickson vetoed their
original names on the basis that they are nonsensical.)

<var title="">document</var> = new Document()

Returns a new document.

<var title="">document</var> . implementation

Returns <var title="">document</var>'s DOMImplementation object.

<var title="">document</var> . URL

<var title="">document</var> . documentURI

Returns <var title="">document</var>'s URL.

<var title="">document</var> . compatMode

Returns the string "CSS1Compat" if
  <var title="">document</var> is in
  no-quirks mode or
  limited-quirks mode, and
  "BackCompat", if <var title="">document</var> is in
  quirks mode.

<var title="">document</var> . characterSet

Returns <var title="">document</var>'s
 encoding.

<var title="">document</var> . contentType

Returns <var title="">document</var>'s
 content type.

The <dfn id="dom-document" title="dom-Document">Document()</dfn> constructor
must return a new document whose
origin is an
alias to the
origin of the global object's associated
document, and
effective script origin is an
alias to the
effective script origin of the
global object's associated document.
[HTML]

Unlike
createDocument()
this constructor does not return an XMLDocument object, but a
document (Document object).

The
<dfn id="dom-document-implementation" title="dom-Document-implementation">implementation</dfn>
attribute must return the DOMImplementation object that is
associated with the document.

The <dfn id="dom-document-url" title="dom-Document-URL">URL</dfn> and
<dfn id="dom-document-documenturi" title="dom-Document-documentURI">documentURI</dfn>
attributes must return the URL.

The <dfn id="dom-document-compatmode" title="dom-Document-compatMode">compatMode</dfn>
attribute must return "BackCompat" if the
context object is in
quirks mode, and
"CSS1Compat" otherwise.

The <dfn id="dom-document-characterset" title="dom-Document-characterSet">characterSet</dfn>
attribute must return the name of the
encoding.

The <dfn id="dom-document-contenttype" title="dom-Document-contentType">contentType</dfn>
attribute must return the
content type.

<var title="">document</var> . doctype

Returns the doctype or null if
 there is none.

<var title="">document</var> . documentElement

Returns the document element.

<var title="">collection</var> = <var title="">document</var> . getElementsByTagName(<var>localName</var>)

If <var>localName</var> is "*" returns a
  HTMLCollection of all
  descendant
  elements.

Otherwise, returns a HTMLCollection of all
  descendant
  elements whose
  local name is
  <var title="">localName</var>. (Matches case-insensitively against
  elements in the
  HTML namespace within an HTML document.)

<var title="">collection</var> = <var title="">document</var> . getElementsByTagNameNS(<var>namespace</var>, <var>localName</var>)

If <var>namespace</var> and <var>localName</var> are
  "*" returns a HTMLCollection of all
  descendant
  elements.

If only <var>namespace</var> is "*" returns a
  HTMLCollection of all
  descendant
  elements whose
  local name is
  <var title="">localName</var>.

If only <var>localName</var> is "*" returns a
  HTMLCollection of all
  descendant
  elements whose
  namespace is
  <var title="">namespace</var>.

Otherwise, returns a HTMLCollection of all
  descendant
  elements whose
  namespace is
  <var title="">namespace</var> and
  local name is
  <var title="">localName</var>.

<var title="">collection</var> = <var title="">document</var> . getElementsByClassName(<var>classes</var>)

<var title="">collection</var> = <var title="">element</var> . getElementsByClassName(<var>classes</var>)

Returns a HTMLCollection of the
  elements in the object on which
  the method was invoked (a document or
  an element) that have all the classes
  given by <var title="">classes</var>.

The <var title="">classes</var> argument is interpreted as a
  space-separated list of classes.

The <dfn id="dom-document-doctype" title="dom-Document-doctype">doctype</dfn> attribute
must return the child of the
document that is a
doctype, and null otherwise.

The
<dfn id="dom-document-documentelement" title="dom-Document-documentElement">documentElement</dfn>
attribute must return the document element.

The
<dfn id="dom-document-getelementsbytagname" title="dom-Document-getElementsByTagName">getElementsByTagName(<var title="">localName</var>)</dfn>
method must return the
list of elements with local name <var title="">localName</var>
for the context object.

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
<dfn id="dom-document-getelementsbytagnamens" title="dom-Document-getElementsByTagNameNS">getElementsByTagNameNS(<var title="">namespace</var>, <var title="">localName</var>)</dfn>
method must return the
list of elements with namespace <var title="">namespace</var> and local name <var title="">localName</var>
for the context object.

The
<dfn id="dom-document-getelementsbyclassname" title="dom-Document-getElementsByClassName">getElementsByClassName(<var>classNames</var>)</dfn>
method must return the
list of elements with class names <var title="">classNames</var>
for the context object.

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

<var title="">element</var> = <var title="">document</var> . createElement(<var>localName</var>)

Returns an element in the
  HTML namespace with <var title="">localName</var> as
  local name. (In an
  HTML document <var title="">localName</var> is lowercased.)

If <var title="">localName</var> does not match the
  Name production an
  "InvalidCharacterError"
  exception will be thrown.

<var title="">element</var> = <var title="">document</var> . createElementNS(<var>namespace</var>, <var>qualifiedName</var>)

Returns an element with
  namespace
  <var title="">namespace</var>. Its
  namespace prefix will
  be everything before ":" (U+003E) in
  <var title="">qualifiedName</var> or null. Its
  local name will be
  everything after ":" (U+003E) in
  <var title="">qualifiedName</var> or <var title="">qualifiedName</var>.

If <var title="">localName</var> does not match the
  Name production an
  "InvalidCharacterError"
  exception will be thrown.

If one of the following conditions is true a
  "NamespaceError" exception
  will be thrown:

<var title="">localName</var> does not match the
   QName production.

Namespace prefix
   is not null and <var title="">namespace</var> is the empty string.

Namespace prefix
   is "xml" and <var title="">namespace</var> is not the
   XML namespace.

<var title="">qualifiedName</var> or
   namespace prefix
   is "xmlns" and <var title="">namespace</var> is not the
   XMLNS namespace.

<var title="">namespace</var> is the XMLNS namespace and
   neither <var title="">qualifiedName</var> nor
   namespace prefix
   is "xmlns".

<var title="">documentFragment</var> = <var title="">document</var> . createDocumentFragment()

Returns a DocumentFragment
 node.

<var title="">text</var> = <var title="">document</var> . createTextNode(<var>data</var>)

Returns a Text node
 whose data is <var title="">data</var>.

<var title="">comment</var> = <var title="">document</var> . createComment(<var>data</var>)

Returns a Comment node
 whose data is <var title="">data</var>.

<var title="">processingInstruction</var> = <var title="">document</var> . createProcessingInstruction(<var>target</var>, <var>data</var>)

Returns a ProcessingInstruction
  node whose
  target is <var title="">target</var> and
  data is <var title="">data</var>.

If <var title="">target</var> does not match the
  Name production an
  "InvalidCharacterError"
  exception will be thrown.

If <var title="">data</var> contains "?>" an
  "InvalidCharacterError"
  exception will be thrown.

The <dfn id="concept-element-interface" title="concept-element-interface">element interface</dfn> for any
<var title="">name</var> and <var title="">namespace</var> is Element, unless
stated otherwise.

The HTML Standard will e.g. define that for html and the
HTML namespace, the HTMLHtmlElement interface is used.
[HTML]

The <dfn id="dom-document-createelement" title="dom-Document-createElement">createElement(<var title="">localName</var>)</dfn> method must run the these steps:

If <var title="">localName</var> does not match the
 Name production,
 throw an
 "InvalidCharacterError" exception.

If the context object is an HTML document,
 let <var title="">localName</var> be
 converted to ASCII lowercase.

Let <var title="">interface</var> be the
 element interface for
 <var title="">localName</var> and the HTML namespace.

Return a new element that implements <var title="">interface</var>,
 with no attributes,
 namespace set to the HTML namespace,
 local name set to <var title="">localName</var>, and
 node document set to the context object.

The
<dfn id="dom-document-createelementns" title="dom-Document-createElementNS">createElementNS(<var title="">namespace</var>, <var title="">qualifiedName</var>)</dfn>
method must run these steps:

If <var title="">namespace</var> is the empty string, set it to null.

If <var title="">qualifiedName</var> does not match the
 Name production,
 throw an
 "InvalidCharacterError" exception.

If <var title="">qualifiedName</var> does not match the
 QName production,
 throw a
 "NamespaceError" exception.

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

If <var title="">prefix</var> is not null and
 <var title="">namespace</var> is null, throw
 a "NamespaceError" exception.

If <var title="">prefix</var> is "xml" and
 <var title="">namespace</var> is not the XML namespace,
 throw a
 "NamespaceError" exception.

If <var title="">qualifiedName</var> or <var title="">prefix</var> is
 "xmlns" and <var title="">namespace</var> is not the
 XMLNS namespace, throw a
 "NamespaceError" exception.

If <var title="">namespace</var> is the XMLNS namespace
 and neither <var title="">qualifiedName</var> nor <var title="">prefix</var> is
 "xmlns", throw a
 "NamespaceError" exception.

Let <var title="">interface</var> be the
 element interface for
 <var title="">localName</var> and <var title="">namespace</var>.

Return a new element that implements <var title="">interface</var>,
 with no attributes,
 namespace set to <var title="">namespace</var>,
 namespace prefix set to <var title="">prefix</var>,
 local name set to <var title="">localName</var>, and
 node document set to the context object.

The
<dfn id="dom-document-createdocumentfragment" title="dom-Document-createDocumentFragment">createDocumentFragment()</dfn>
method must return a new DocumentFragment
node with its
node document set to the
context object.

The
<dfn id="dom-document-createtextnode" title="dom-Document-createTextNode">createTextNode(<var title="">data</var>)</dfn>
method must return a new Text
node with its
data set to <var title="">data</var> and
node document set to the
context object.

No check is performed that <var title="">data</var> consists of
characters that match the Char production.

The
<dfn id="dom-document-createcomment" title="dom-Document-createComment">createComment(<var title="">data</var>)</dfn>
method must return a new Comment
node with its
data set to <var title="">data</var> and
node document set to the
context object.

No check is performed that <var title="">data</var> consists of
characters that match the Char production
or that it contains two adjacent hyphens or ends with a hyphen.

The <dfn id="dom-document-createprocessinginstruction" title="dom-Document-createProcessingInstruction">createProcessingInstruction(<var title="">target</var>, <var title="">data</var>)</dfn> method must run these steps:

If <var title="">target</var> does not match the

 Name production,
 throw an
 "InvalidCharacterError" exception.

If <var title="">data</var> contains the string
 "?>", throw an
 "InvalidCharacterError" exception.

Return a new ProcessingInstruction
 node, with
 target set to <var title="">target</var>,
 data set to <var title="">data</var>, and
 node document set to the
 context object.

No check is performed that <var title="">target</var> contains
"xml" or ":", or that
<var title="">data</var> contains characters that match the
Char production.

<var title="">clone</var> = <var title="">document</var> . importNode(<var>node</var> [, <var>deep</var> = false])

Returns a copy of <var title="">node</var>. If
  <var title="">deep</var> is true, the copy also includes the
  <var title="">node</var>'s descendants.

If <var title="">node</var> is a
  document throws a
  "NotSupportedError"
  exception.

<var title="">node</var> = <var title="">document</var> . adoptNode(<var>node</var>)

Moves <var title="">node</var> from another
  document and returns it.

If <var title="">node</var> is a
  document throws a
  "NotSupportedError"
  exception.

The
<dfn id="dom-document-importnode" title="dom-Document-importNode">importNode(<var title="">node</var>, <var title="">deep</var>)</dfn>
method must run these steps:

If <var title="">node</var> is a
 document,
 throw a
 "NotSupportedError" exception.

Return a clone of
 <var title="">node</var>, with context object and the
 clone children flag set if <var title="">deep</var> is true.

Specifications may define
<dfn id="concept-node-adopt-ext" title="concept-node-adopt-ext">adopting steps</dfn> for all or some
nodes. The algorithm is passed <var title="">node</var> and
<var title="">oldDocument</var>, as indicated in the
adopt algorithm.

To <dfn id="concept-node-adopt" title="concept-node-adopt">adopt</dfn> a <var title="">node</var> into
a <var title="">document</var>, run these steps:

Let <var title="">oldDocument</var> be <var title="">node</var>'s
 node document.

If <var title="">node</var>'s
 parent is not null,
 remove <var title="">node</var> from
 its parent.

Set <var title="">node</var>'s
 inclusive descendants's
 node document to <var title="">document</var>.

Run any adopting steps defined for
 <var title="">node</var> in other applicable specifications and pass
 <var title="">node</var> and <var title="">oldDocument</var> as parameters.

The
<dfn id="dom-document-adoptnode" title="dom-Document-adoptNode">adoptNode(<var title="">node</var>)</dfn>
method must run these steps:

If <var title="">node</var> is a
 document,
 throw a
 "NotSupportedError" exception.

Adopt <var title="">node</var>
 into the context object.

Return <var title="">node</var>.

The
<dfn id="dom-document-createevent" title="dom-Document-createEvent">createEvent(<var title="">interface</var>)</dfn>
method must run these steps:

Let <var title="">event</var> be null.

If <var title="">interface</var> is an
  ASCII case-insensitive match for any of the strings in the
  first column in the following table, let <var title="">event</var> be the
  interface in the second column on the same row as the matching string:

StringInterfaceNotes

"customevent"CustomEvent

"event"Event

"events"

"htmlevents"

"mouseevent"MouseEvent[UIEVENTS]

"mouseevents"

"uievent"UIEvent

"uievents"

If <var title="">event</var> is null, throw a
 "NotSupportedError".

Return a new event implementing the
 <var title="">event</var> interface.

Event constructors can be used instead.

The <dfn id="dom-document-createrange" title="dom-Document-createRange">createRange()</dfn>
method must return a new range with
(context object, 0) as its
start and
end.

The Range() constructor can be used instead.

The
<dfn id="dom-document-createnodeiterator" title="dom-Document-createNodeIterator">createNodeIterator(<var>root</var>, <var>whatToShow</var>, <var>filter</var>)</dfn>
method must run these steps:

Create a NodeIterator object.

Set root and initialize
 the referenceNode
 attribute to the <var title="">root</var> argument.

Initialize the
 pointerBeforeReferenceNode
 attribute to true.

Set whatToShow to
 the <var title="">whatToShow</var> argument.

Set filter to
 <var title="">filter</var>.

Return the newly created NodeIterator object.

The
<dfn id="dom-document-createtreewalker" title="dom-Document-createTreeWalker">createTreeWalker(<var>root</var>, <var>whatToShow</var>, <var>filter</var>)</dfn>
method must run these steps:

Create a TreeWalker object.

Set root and initialize
 the currentNode attribute to
 the <var title="">root</var> argument.

Set whatToShow to
 the <var title="">whatToShow</var> argument.

Set filter to
 <var title="">filter</var>.

Return the newly created TreeWalker object.

5.5.1 Interface DOMImplementation

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

interface <dfn id="domimplementation">DOMImplementation</dfn> {
  [NewObject] DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
  [NewObject] XMLDocument createDocument(DOMString? <var title="">namespace</var>, [TreatNullAs=EmptyString] DOMString <var title="">qualifiedName</var>, optional DocumentType? <var title="">doctype</var> = null);
  [NewObject] Document createHTMLDocument(optional DOMString <var title="">title</var>);

  boolean hasFeature(); // useless; always returns true
};

<var title="">doctype</var> = <var title="">document</var> . implementation . createDocumentType(<var title="">qualifiedName</var>, <var title="">publicId</var>, <var title="">systemId</var>)

Returns a doctype, with the given
  <var title="">qualifiedName</var>, <var title="">publicId</var>, and
  <var title="">systemId</var>. If <var title="">qualifiedName</var> does not
  match the Name production, an
  "InvalidCharacterError"
  exception is thrown, and if it does not match the
  QName production, a
  "NamespaceError" exception
  is thrown.

<var title="">doc</var> = <var title="">document</var> . implementation . createDocument(<var title="">namespace</var>, <var title="">qualifiedName</var> [, <var title="">doctype</var> = null])

Returns an XMLDocument, with a
  document element whose
  local name is
  <var title="">qualifiedName</var> and whose
  namespace is
  <var title="">namespace</var> (unless <var title="">qualifiedName</var> is the
  empty string), and with <var title="">doctype</var>, if it is given, as its
  doctype.

This method throws the same exceptions as the createElementNS method, when
  invoked with the same arguments.

<var title="">doc</var> = <var title="">document</var> . implementation . createHTMLDocument([<var title="">title</var>])

Returns a document, with a basic
  tree already constructed including a
  title element, unless the <var title="">title</var>
  argument is omitted.

The
<dfn id="dom-domimplementation-createdocumenttype" title="dom-DOMImplementation-createDocumentType">createDocumentType(<var>qualifiedName</var>, <var>publicId</var>, <var>systemId</var>)</dfn>
method must run these steps:

If <var title="">qualifiedName</var> does not match the
 Name production,
 throw an
 "InvalidCharacterError" exception.

If <var title="">qualifiedName</var> does not match the QName production,
 throw a
 "NamespaceError" exception.

Return a new doctype, with
 <var title="">qualifiedName</var> as its
 name, <var title="">publicId</var> as
 its public ID, and
 <var title="">systemId</var> as its
 system ID, and with its
 node document set to the
 associated document of the
 context object.

No check is performed that <var title="">publicId</var>
matches the PublicChar production or that
<var title="">systemId</var> does not contain both a '"' and
"'".

The
<dfn id="dom-domimplementation-createdocument" title="dom-DOMImplementation-createDocument">createDocument(<var>namespace</var>, <var>qualifiedName</var>, <var>doctype</var>)</dfn>
method must run these steps:

Let <var title="">document</var> be a new XMLDocument.

This method creates an XMLDocument rather than
  a normal document. They are identical
  except for the addition of the
  load()
  method deployed content relies upon.
  [HTML]

Let <var title="">element</var> be null.

If <var title="">qualifiedName</var> is not the empty string, set
 <var title="">element</var> to the result of invoking the
 createElementNS() method
 with the arguments <var title="">namespace</var> and
 <var title="">qualifiedName</var> on <var title="">document</var>. If that threw
 an exception, re-throw the exception.

If <var title="">doctype</var> is not null,
 append
 <var title="">doctype</var> to <var title="">document</var>.

If <var title="">element</var> is not null,
 append
 <var title="">element</var> to <var title="">document</var>.

<var title="">document</var>'s
 origin is an
 alias to the
 origin of the
 context object's associated
 document, and
 <var title="">document</var>'s
 effective script origin is an
 alias to the
 effective script origin of the
 context object's associated
 document.
 [HTML]

Return <var title="">document</var>.

The
<dfn id="dom-domimplementation-createhtmldocument" title="dom-DOMImplementation-createHTMLDocument">createHTMLDocument(<var>title</var>)</dfn>
method must run these steps:

Let <var title="">doc</var> be a new
 document that is an
 HTML document.

Set <var title="">doc</var>'s
 content type to
 "text/html".

Create a doctype, with
 "html"
 as its name and with its
 node document set to
 <var title="">doc</var>. Append
 the newly created node to <var title="">doc</var>.

Create an html element in the HTML
 namespace, and append
 it to <var title="">doc</var>.

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

If the <var title="">title</var> argument is not omitted:

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

Create a Text node,
   set its data to <var title="">title</var>
   (which could be the empty string), and
   append it to the
   title element created in the previous step.

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

<var title="">doc</var>'s
 origin is an
 alias to the
 origin of the
 context object's associated
 document, and
 <var title="">doc</var>'s
 effective script origin is an
 alias to the
 effective script origin of the
 context object's associated
 document.
 [HTML]

Return <var title="">doc</var>.

The <dfn id="dom-domimplementation-hasfeature" title="dom-DOMImplementation-hasFeature">hasFeature()</dfn> method
must return true.

hasFeature()
originally would report whether the user agent claimed to support a given DOM
feature, but experience proved it was not nearly as reliable or granular as
simply checking whether the desired objects, attributes, or methods existed.
As such, it should no longer be used, but continues to exist (and simply
returns true) so that old pages don't stop working.

5.6 Interface DocumentFragment

[Constructor]
interface <dfn id="documentfragment">DocumentFragment</dfn> : Node {
};

A DocumentFragment node can have an
associated element named
<dfn id="concept-documentfragment-host" title="concept-DocumentFragment-host">host</dfn>.

An object <var title="">A</var> is a
<dfn id="concept-tree-host-including-inclusive-ancestor" title="concept-tree-host-including-inclusive-ancestor">host-including inclusive ancestor</dfn>
of an object <var title="">B</var>, if either <var title="">A</var> is an
inclusive ancestor of
<var title="">B</var>, or if <var title="">B</var>'s root
has an associated host and
<var title="">A</var> is a
host-including inclusive ancestor
of <var title="">B</var>'s root's
host.

The DocumentFragment node's
host concept is useful for HTML's
template element and the ShadowRoot object and impacts the
pre-insert and
replace algorithms.

<var title="">tree</var> = new DocumentFragment()

Returns a new DocumentFragment node.

The <dfn id="dom-documentfragment" title="dom-DocumentFragment">DocumentFragment()</dfn> constructor
must return a new DocumentFragment node whose
node document is the global object's associated
document.

5.7 Interface DocumentType

interface <dfn id="documenttype">DocumentType</dfn> : Node {
  readonly attribute DOMString name;
  readonly attribute DOMString publicId;
  readonly attribute DOMString systemId;
};

DocumentType nodes are
simply known as <dfn id="concept-doctype" title="concept-doctype">doctypes</dfn>.

Doctypes have an associated
<dfn id="concept-doctype-name" title="concept-doctype-name">name</dfn>,
<dfn id="concept-doctype-publicid" title="concept-doctype-publicid">public ID</dfn>, and
<dfn id="concept-doctype-systemid" title="concept-doctype-systemid">system ID</dfn>.

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

The <dfn id="dom-documenttype-name" title="dom-DocumentType-name">name</dfn> attribute
must return the name.

The <dfn id="dom-documenttype-publicid" title="dom-DocumentType-publicId">publicId</dfn>
attribute must return the
public ID.

The <dfn id="dom-documenttype-systemid" title="dom-DocumentType-systemId">systemId</dfn>
attribute must return the
system ID.

5.8 Interface Element

interface <dfn id="element">Element</dfn> : Node {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString tagName;

           attribute DOMString id;
           attribute DOMString className;
  [SameObject] readonly attribute DOMTokenList classList;

  [SameObject] readonly attribute Attr[] attributes;
  DOMString? getAttribute(DOMString <var title="">name</var>);
  DOMString? getAttributeNS(DOMString? <var title="">namespace</var>, DOMString <var title="">localName</var>);
  void setAttribute(DOMString <var title="">name</var>, DOMString <var title="">value</var>);
  void setAttributeNS(DOMString? <var title="">namespace</var>, DOMString <var title="">name</var>, DOMString <var title="">value</var>);
  void removeAttribute(DOMString <var title="">name</var>);
  void removeAttributeNS(DOMString? <var title="">namespace</var>, DOMString <var title="">localName</var>);
  boolean hasAttribute(DOMString <var title="">name</var>);
  boolean hasAttributeNS(DOMString? <var title="">namespace</var>, DOMString <var title="">localName</var>);

  boolean matches(DOMString <var title="">selectors</var>);

  HTMLCollection getElementsByTagName(DOMString <var title="">localName</var>);
  HTMLCollection getElementsByTagNameNS(DOMString? <var title="">namespace</var>, DOMString <var title="">localName</var>);
  HTMLCollection getElementsByClassName(DOMString <var title="">classNames</var>);
};

Element nodes are simply
known as <dfn id="concept-element" title="concept-element">elements</dfn>.

Elements have an associated
<dfn id="concept-element-namespace" title="concept-element-namespace">namespace</dfn>,
<dfn id="concept-element-namespace-prefix" title="concept-element-namespace-prefix">namespace prefix</dfn>, and
<dfn id="concept-element-local-name" title="concept-element-local-name">local name</dfn>. 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 ordered
<dfn id="concept-element-attribute" title="concept-element-attribute">attribute list</dfn>. Unless
explicitly given when an element is
created, its
attribute list is empty. An
element
<dfn id="concept-element-attribute-has" title="concept-element-attribute-has">has</dfn> an
attribute <var title="">A</var> if
<var title="">A</var> is in its
attribute list.

Applicable specifications
and this specification (can) use the hooks an <dfn id="attribute-is-set">attribute is set</dfn>,
an <dfn id="attribute-is-changed">attribute is changed</dfn>, an <dfn id="attribute-is-added">attribute is added</dfn>, and
an <dfn id="attribute-is-removed">attribute is removed</dfn>, for further processing of the
attribute's
value.

To <dfn id="concept-element-attributes-get" title="concept-element-attributes-get">get an attribute</dfn> for
an element <var title="">element</var>
using a <var title="">localName</var> and optionally a
<var title="">namespace</var>, run these steps:

If <var title="">namespace</var> is not given, set it to null.

Return the value of the
 attribute in <var title="">element</var>'s
 attribute list whose
 namespace is
 <var title="">namespace</var> and
 local name is
 <var title="">localName</var>, if it has one, and null otherwise.

To <dfn id="concept-element-attributes-set" title="concept-element-attributes-set">set an attribute</dfn> for
an element <var title="">element</var>
using a <var title="">localName</var> and <var title="">value</var>, and
optionally a <var title="">name</var>, <var title="">prefix</var>, and
<var title="">namespace</var>, run these steps:

If <var title="">name</var> is not given, set it to
 <var title="">localName</var>.

If <var title="">prefix</var> is not given, set it to null.

If <var title="">namespace</var> is not given, set it to null.

Let <var title="">attribute</var> be the
 attribute in
 <var title="">element</var>'s
 attribute list
 whose namespace is
 <var title="">namespace</var> and whose
 local name
 is <var title="">localName</var>, or null if there is no such
 attribute.

If <var title="">attribute</var> is null, create an
 attribute whose
 local name is
 <var title="">localName</var>,
 value is <var title="">value</var>,
 name is <var title="">name</var>,
 namespace is
 <var title="">namespace</var>, and
 namespace prefix is
 <var title="">prefix</var>, and then
 append this
 attribute to <var title="">element</var>
 and terminate these steps.

Change
 <var title="">attribute</var> from <var title="">element</var> to
 <var title="">value</var>.

To <dfn id="concept-element-attributes-change" title="concept-element-attributes-change">change</dfn> an
attribute <var title="">attribute</var>
from an element <var title="">element</var>
to <var title="">value</var>, run these steps:

Queue a mutation record of "attributes"
 for <var title="">element</var> with name <var title="">attribute</var>'s
 local name, namespace
 <var title="">attribute</var>'s
 namespace, and oldValue
 <var title="">attribute</var>'s
 value.

Set <var title="">attribute</var>'s
 value to <var title="">value</var>.

An attribute is set and an
 attribute is changed.

To <dfn id="concept-element-attributes-append" title="concept-element-attributes-append">append</dfn> an
attribute <var title="">attribute</var> to
an element <var title="">element</var>,
run these steps:

Queue a mutation record of "attributes"
 for <var title="">element</var> with name <var title="">attribute</var>'s
 local name, namespace
 <var title="">attribute</var>'s
 namespace, and oldValue
 null.

Append the <var title="">attribute</var> to the <var title="">element</var>'s
 attribute list.

An attribute is set and an
 attribute is added.

To <dfn id="concept-element-attributes-remove" title="concept-element-attributes-remove">remove</dfn> an
attribute <var title="">attribute</var>
from an element <var title="">element</var>,
run these steps:

Queue a mutation record of "attributes"
 for <var title="">element</var> with name <var title="">attribute</var>'s
 local name, namespace
 <var title="">attribute</var>'s
 namespace, and oldValue
 <var title="">attribute</var>'s
 value.

Remove <var title="">attribute</var> from the
 <var title="">element</var>'s
 attribute list.

An attribute is removed.

Elements can have an associated
<dfn id="concept-id" title="concept-id">unique identifier (ID)</dfn> and have an associated
DOMTokenList object. The DOMTokenList object's
associated attribute's
local name is
class and its associated ordered set of tokens is called
the element's
<dfn id="concept-class" title="concept-class">classes</dfn>.

Historically elements could
have multiple identifiers e.g. by using the HTML id
attribute and a DTD. This specification
makes ID a concept of the DOM and allows for
only one per element, given by an
id attribute.

Either when an element is created that
has an
id attribute whose
value is not the empty string or
when an element's
id attribute is
set to a
value other than the empty
string, set the element's
ID to the new
value.

When an element's
id attribute is
removed, unset the
element's
ID.

Either when an element is created that
has a
class attribute or
when an element's
class attribute is
set, set the
element's
classes to the new
value,
parsed.

When an element's
class attribute is
removed, set the
element's
classes to the empty set.

While this specification defines user agent processing
requirements for id and class
attributes on any
element, it makes no claims as to whether
using them is conforming or not.

A node's
parent of type
Element is known as a <dfn id="parent-element">parent element</dfn>. If the
node has a
parent of a different type, its
parent element is null.

The <dfn id="document-element">document element</dfn> of a
document is the
element whose
parent is that
document, if it exists, and null otherwise.

Per the node tree
constraints, there can only be one such
element.

When an element or one of its
ancestors is the
document element, it is <dfn id="in-a-document">in a document</dfn>.

<var title="">namespace</var> = <var title="">element</var> . namespaceURI

Returns the namespace.

<var title="">prefix</var> = <var title="">element</var> . prefix

Returns the
 namespace prefix.

<var title="">localName</var> = <var title="">element</var> . localName

Returns the
 local name.

<var title="">qualifiedName</var> = <var title="">element</var> . tagName

If
 namespace prefix is not
 null, returns the concatenation of
 namespace prefix,
 ":", and
 local name. Otherwise it
 returns the local name.
 (The return value is uppercased in an HTML document.)

The <dfn id="dom-element-namespaceuri" title="dom-Element-namespaceURI">namespaceURI</dfn>
attribute must return the context object's
namespace.

The <dfn id="dom-element-prefix" title="dom-Element-prefix">prefix</dfn> attribute must return the context object's
namespace prefix.

The <dfn id="dom-element-localname" title="dom-Element-localName">localName</dfn>
attribute must return the context object's
local name.

The <dfn id="dom-element-tagname" title="dom-Element-tagName">tagName</dfn> attribute
must run these steps:

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

If the context object is in the HTML namespace and
 its node document is an
 HTML document, let <var title="">qualified name</var> be
 converted to ASCII uppercase.

Return <var title="">qualified name</var>.

Some attributes are defined to <dfn id="concept-reflect" title="concept-reflect">reflect</dfn> a
particular content attribute. This means that on getting, these
steps must be run:

Get an attribute
 for the context object using content attribute's name and let
 <var title="">value</var> be the result.

If <var title="">value</var> is null, return the empty string.

Return <var title="">value</var>.

On setting,
set an attribute for the
context object using the name of the attribute and the given
value.

The <dfn id="dom-element-id" title="dom-Element-id">id</dfn> attribute must
reflect the "id"
content attribute.

The <dfn id="dom-element-classname" title="dom-Element-className">className</dfn>
attribute must reflect the
"class" content attribute.

The <dfn id="dom-element-classlist" title="dom-Element-classList">classList</dfn>
attribute must return the associated DOMTokenList object
representing the context object's
classes.

The <dfn id="dom-element-attributes" title="dom-Element-attributes">attributes</dfn>
attribute must return a read only array
of the context object's
attribute list.
The returned read only array must be
live. I.e. changes to the associated
attributes are reflected.

The <dfn id="dom-element-getattribute" title="dom-Element-getAttribute">getAttribute(<var title="">name</var>)</dfn> method must run these steps:

If the context object is in the
 HTML namespace and its
 node document is an
 HTML document, let <var title="">name</var> be
 converted to ASCII lowercase.

Return the value of the
 first attribute in the
 context object's
 attribute list whose
 name is
 <var title="">name</var>, and null otherwise.

The
<dfn id="dom-element-getattributens" title="dom-Element-getAttributeNS">getAttributeNS(<var title="">namespace</var>, <var title="">localName</var>)</dfn>
method must return the following steps:

If <var title="">namespace</var> is the empty string, set it to null.

Return
  getting an attribute for
  the context object using <var title="">localName</var> and
  <var title="">namespace</var>.

The
<dfn id="dom-element-setattribute" title="dom-Element-setAttribute">setAttribute(<var title="">name</var>, <var title="">value</var>)</dfn>
method must run these steps:

If <var title="">name</var> does not match the
 Name production in XML,
 throw an
 "InvalidCharacterError" exception.

If the context object is in the HTML namespace
 and its node document is an
 HTML document, let <var title="">name</var> be
 converted to ASCII lowercase.

Let <var title="">attribute</var> be the
 first attribute in the
 context object's attribute list
 whose name is
 <var title="">name</var>, or null if there is no such
 attribute.

If <var title="">attribute</var> is null, create an
 attribute whose
 local name is
 <var title="">name</var> and
 value is <var title="">value</var>,
 and then append this
 attribute to the
 context object and terminate these steps.

Change
 <var title="">attribute</var> from context object to
 <var title="">value</var>.

The
<dfn id="dom-element-setattributens" title="dom-Element-setAttributeNS">setAttributeNS(<var title="">namespace</var>, <var title="">name</var>, <var title="">value</var>)</dfn>
method must run these steps:

If <var title="">namespace</var> is the empty string, set it to null.

If <var title="">name</var> does not match the
 Name production in XML,
 throw an
 "InvalidCharacterError" exception.

If <var title="">name</var> does not match the
 QName production in Namespaces in XML,
 throw a
 "NamespaceError" exception.

If <var title="">name</var> contains a ":" (U+003E),
 then split the string on it and let <var title="">prefix</var> be the part
 before and <var title="">localName</var> the part after. Otherwise, let
 <var title="">prefix</var> be null and <var title="">localName</var> be
 <var title="">name</var>.

If <var title="">prefix</var> is not null and
 <var title="">namespace</var> is null, throw
 a "NamespaceError" exception.

If <var title="">prefix</var> is "xml" and
 <var title="">namespace</var> is not the XML namespace,
 throw a
 "NamespaceError" exception.

If <var title="">name</var> or <var title="">prefix</var> is
 "xmlns" and <var title="">namespace</var> is not the
 XMLNS namespace, throw a
 "NamespaceError" exception.

If <var title="">namespace</var> is the XMLNS namespace
 and neither <var title="">name</var> nor <var title="">prefix</var> is
 "xmlns", throw a
 "NamespaceError" exception.

Set an attribute
 for the context object using
 <var title="">localName</var>, <var title="">value</var>, and also
 <var title="">name</var>, <var title="">prefix</var>, and
 <var title="">namespace</var>.

The
<dfn id="dom-element-removeattribute" title="dom-Element-removeAttribute">removeAttribute(<var>name</var>)</dfn>
method must run these steps:

If the context object is in the
 HTML namespace and its
 node document is an
 HTML document, let <var title="">name</var> be
 converted to ASCII lowercase.

Remove the
 first attribute from the
 context object whose
 name is <var title="">name</var>,
 if any.

The
<dfn id="dom-element-removeattributens" title="dom-Element-removeAttributeNS">removeAttributeNS(<var>namespace</var>, <var>localName</var>)</dfn>
method must return the following steps:

If <var title="">namespace</var> is the empty string, set it to null.

Remove the
  attribute from the
  context object whose
  namespace is
  <var title="">namespace</var> and
  local name is
  <var title="">localName</var>, if any.

The
<dfn id="dom-element-hasattribute" title="dom-Element-hasAttribute">hasAttribute(<var>name</var>)</dfn>
method must run these steps:

If the context object is in the
 HTML namespace and its
 node document is an
 HTML document, let <var title="">name</var> be
 converted to ASCII lowercase.

Return true if the context object
 has an
 attribute whose
 name is
 <var title="">name</var>, and false otherwise.

The
<dfn id="dom-element-hasattributens" title="dom-Element-hasAttributeNS">hasAttributeNS(<var>namespace</var>, <var>localName</var>)</dfn>
method must run these steps:

If <var title="">namespace</var> is the empty string, set it to null.

Return true if the context object
 has an
 attribute whose
 namespace is <var title="">namespace</var>
 and local name is
 <var title="">localName</var>, and false otherwise.

<var title="">element</var> . matches(<var title="">selectors</var>)

Returns true if matching <var title="">selectors</var> against
 <var title="">element</var>'s root yields
 <var title="">element</var>, and false otherwise.

To <dfn id="match-a-selectors-string">match a selectors string</dfn> <var title="">selectors</var> against a
<var title="">set</var>, run these steps:

Let <var title="">s</var> be the result of
 parse a selector from <var title="">selectors</var>.
 [SELECTORS]

If <var title="">s</var> is failure, throw a
 JavaScript TypeError.

Return the result of evaluate a selector
 <var title="">s</var> using
 :scope elements
 <var title="">set</var>. [SELECTORS]

The <dfn id="dom-element-matches" title="dom-Element-matches">matches(<var>selectors</var>)</dfn>
method must return true if the context object is in the result of running
match a selectors string <var title="">selectors</var> against a set consisting
of context object, and false otherwise.

The
<dfn id="dom-element-getelementsbytagname" title="dom-Element-getElementsByTagName">getElementsByTagName(<var>localName</var>)</dfn>
method must return the
list of elements with local name <var title="">localName</var>
for the context object.

The
<dfn id="dom-element-getelementsbytagnamens" title="dom-Element-getElementsByTagNameNS">getElementsByTagNameNS(<var>namespace</var>, <var>localName</var>)</dfn>
method must return the
list of elements with namespace <var title="">namespace</var> and local name <var title="">localName</var>
for the context object.

The
<dfn id="dom-element-getelementsbyclassname" title="dom-Element-getElementsByClassName">getElementsByClassName(<var title="">classNames</var>)</dfn>
method must return the
list of elements with class names <var title="">classNames</var>
for the context object.

5.8.1 Interface Attr

interface <dfn id="attr">Attr</dfn> {
  readonly attribute DOMString localName;
           attribute DOMString value;

  readonly attribute DOMString name;
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;

  readonly attribute boolean specified; // useless; always returns true
};

Attr objects are simply known as
<dfn id="concept-attribute" title="concept-attribute">attributes</dfn>. They are sometimes referred
to as content attributes to avoid confusion with IDL attributes.

Attributes have a
<dfn id="concept-attribute-local-name" title="concept-attribute-local-name">local name</dfn> and
<dfn id="concept-attribute-value" title="concept-attribute-value">value</dfn>.

For legacy reasons, attributes also
have an associated <dfn id="concept-attribute-name" title="concept-attribute-name">name</dfn>,
<dfn id="concept-attribute-namespace" title="concept-attribute-namespace">namespace</dfn>, and
<dfn id="concept-attribute-namespace-prefix" title="concept-attribute-namespace-prefix">namespace prefix</dfn>.

When an attribute is created, its
local name and
value are always given. Unless
explicitly given when an attribute is
created, its name is
identical to its local name,
and its namespace and
namespace prefix are
null.

An
<dfn id="concept-named-attribute" title="concept-named-attribute"><var title="">A</var> attribute</dfn>
is an attribute whose
local name is
<var title="">A</var> and whose
namespace and
namespace prefix are
null.

The <dfn id="dom-attr-localname" title="dom-Attr-localName">localName</dfn> attribute
must return the local name.

The <dfn id="dom-attr-value" title="dom-Attr-value">value</dfn> attribute must
return the value.

Setting the value attribute must
change
value to the new value.

The <dfn id="dom-attr-name" title="dom-Attr-name">name</dfn> attribute must
return the name.

The <dfn id="dom-attr-namespaceuri" title="dom-Attr-namespaceURI">namespaceURI</dfn>
attribute must return the
namespace.

The <dfn id="dom-attr-prefix" title="dom-Attr-prefix">prefix</dfn> attribute must
return the
namespace prefix.

The <dfn id="dom-attr-specified" title="dom-Attr-specified">specified</dfn> attribute must return
true.

5.9 Interface CharacterData

interface <dfn id="characterdata">CharacterData</dfn> : Node {
  [TreatNullAs=EmptyString] attribute DOMString data;
  readonly attribute unsigned long length;
  DOMString substringData(unsigned long <var title="">offset</var>, unsigned long <var title="">count</var>);
  void appendData(DOMString <var title="">data</var>);
  void insertData(unsigned long <var title="">offset</var>, DOMString <var title="">data</var>);
  void deleteData(unsigned long <var title="">offset</var>, unsigned long <var title="">count</var>);
  void replaceData(unsigned long <var title="">offset</var>, unsigned long <var title="">count</var>, DOMString <var title="">data</var>);
};

CharacterData is an abstract interface and does
not exist as node. It is used by
Text, Comment, and
ProcessingInstruction nodes.

Each node inheriting from the
CharacterData interface has an associated mutable string
called <dfn id="concept-cd-data" title="concept-CD-data">data</dfn>.

To <dfn id="concept-cd-replace" title="concept-CD-replace">replace data</dfn> of node
<var title="">node</var> with offset <var title="">offset</var>, count
<var title="">count</var>, and data <var title="">data</var>, run these steps:

Let <var title="">length</var> be <var title="">node</var>'s
 length attribute value.

If <var title="">offset</var> is greater than <var title="">length</var>,
 throw an
 "IndexSizeError" exception.

If <var title="">offset</var> plus <var title="">count</var> is greater
 than <var title="">length</var> let <var title="">count</var> be
 <var title="">length</var> minus <var title="">offset</var>.

Queue a mutation record of "characterData"
 for <var title="">node</var> with oldValue <var title="">node</var>'s
 data.

Insert <var title="">data</var> into <var title="">node</var>'s
 data after <var title="">offset</var>
 code units.

Let <var title="">delete offset</var> be <var title="">offset</var> plus
 the number of
 code units in
 <var title="">data</var>.

Starting from <var title="">delete offset</var>
 code units, remove
 <var title="">count</var>
 code units from
 <var title="">node</var>'s data.

For each range whose
 start node is
 <var title="">node</var> and
 start offset is greater than
 <var title="">offset</var> but less than or equal to <var title="">offset</var>
 plus <var title="">count</var>, set its
 start offset to
 <var title="">offset</var>.

For each range whose
 end node is
 <var title="">node</var> and
 end offset is greater than
 <var title="">offset</var> but less than or equal to <var title="">offset</var>
 plus <var title="">count</var>, set its
 end offset to
 <var title="">offset</var>.

For each range whose
 start node is
 <var title="">node</var> and
 start offset is greater than
 <var title="">offset</var> plus <var title="">count</var>, increase its
 start offset by the number of
 code units in
 <var title="">data</var>, then decrease it by <var title="">count</var>.

For each range whose
 end node is
 <var title="">node</var> and
 end offset is greater than
 <var title="">offset</var> plus <var title="">count</var>, increase its
 end offset by the number of
 code units in
 <var title="">data</var>, then decrease it by <var title="">count</var>.

To <dfn id="concept-cd-substring" title="concept-CD-substring">substring data</dfn> with node
<var title="">node</var>, offset <var title="">offset</var>, and count
<var title="">count</var>, run these steps:

Let <var title="">length</var> be <var title="">node</var>'s
 length attribute value.

If <var title="">offset</var> is greater than <var title="">length</var>,
 throw an
 "IndexSizeError" exception.

If <var title="">offset</var> plus <var title="">count</var> is
 greater than <var title="">length</var>, return a string whose value is the
 code units from the
 <var title="">offset</var>th
 code unit to the end of
 <var title="">node</var>'s data, and then
 terminate these steps.

Return a string whose value is the
 code units from the
 <var title="">offset</var>th
 code unit to the
 <var title="">offset</var>+<var title="">count</var>th
 code unit in <var title="">node</var>'s
 data.

The <dfn id="dom-characterdata-data" title="dom-CharacterData-data">data</dfn> attribute
must return data, and on setting, must
replace data with node
context object offset 0, count
length attribute value, and data
new value.

The <dfn id="dom-characterdata-length" title="dom-CharacterData-length">length</dfn>
attribute must return the number of
code units in
data.

The
<dfn id="dom-characterdata-substringdata" title="dom-CharacterData-substringData">substringData(<var title="">offset</var>, <var title="">count</var>)</dfn>
method must substring data with node
context object, offset <var title="">offset</var>, and count
<var title="">count</var>.

The
<dfn id="dom-characterdata-appenddata" title="dom-CharacterData-appendData">appendData(<var title="">data</var>)</dfn>
method must replace data with node
context object, offset
length attribute value, count 0,
and data <var title="">data</var>.

The
<dfn id="dom-characterdata-insertdata" title="dom-CharacterData-insertData">insertData(<var title="">offset</var>, <var title="">data</var>)</dfn>
method must replace data with node
context object, offset <var title="">offset</var>, count 0, and
data <var title="">data</var>.

The
<dfn id="dom-characterdata-deletedata" title="dom-CharacterData-deleteData">deleteData(<var title="">offset</var>, <var title="">count</var>)</dfn>
method must replace data with node
context object, offset <var title="">offset</var>, count
<var title="">count</var>, and data the empty string.

The
<dfn id="dom-characterdata-replacedata" title="dom-CharacterData-replaceData">replaceData(<var title="">offset</var>, <var title="">count</var>, <var title="">data</var>)</dfn>
method must replace data with node
context object, offset <var title="">offset</var>, count
<var title="">count</var>, and data <var title="">data</var>.

5.10 Interface Text

[Constructor(optional DOMString <var title="">data</var> = "")]
interface <dfn id="text">Text</dfn> : CharacterData {
  [NewObject] Text splitText(unsigned long <var title="">offset</var>);
  readonly attribute DOMString wholeText;
};

<var title="">text</var> = new Text([<var title="">data</var> = ""])

Returns a new Text node whose
 data is <var title="">data</var>.

<var title="">text</var> . splitText(<var title="">offset</var>)

Splits data at the given
 <var title="">offset</var> and returns the remainder as Text
 node.

<var title="">text</var> . wholeText

Returns the combined data of all direct
 Text node
 siblings.

The <dfn id="dom-text" title="dom-Text">Text(<var title="">data</var>)</dfn> constructor
must return a new Text node whose
data is <var title="">data</var> and
node document is the global object's associated
document.

To <dfn id="concept-text-split" title="concept-Text-split">split</dfn> a Text
node <var title="">node</var> with offset
<var title="">offset</var>, run these steps:

Let <var title="">length</var> be <var title="">node</var>'s
 length attribute value.

If <var title="">offset</var> is greater than <var title="">length</var>,
 throw an
 "IndexSizeError" exception.

Let <var title="">count</var> be <var title="">length</var> minus
 <var title="">offset</var>.

Let <var title="">new data</var> be the result of
 substringing data with node
 <var title="">node</var>, offset <var title="">offset</var>, and count
 <var title="">count</var>.

Let <var title="">new node</var> be a new Text
 node, with the same
 node document as
 <var title="">node</var>. Set <var title="">new node</var>'s
 data to <var title="">new data</var>.

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is not null, run these substeps:

Insert
   <var title="">new node</var> into <var title="">parent</var> before
   <var title="">node</var>'s
   next sibling.

For each range whose
   start node is
   <var title="">node</var> and
   start offset is greater than
   <var title="">offset</var>, set its
   start node to
   <var title="">new node</var> and decrease its
   start offset by
   <var title="">offset</var>.

For each range whose
   end node is
   <var title="">node</var> and
   end offset is greater than
   <var title="">offset</var>, set its
   end node to
   <var title="">new node</var> and decrease its
   end offset by
   <var title="">offset</var>.

For each range whose
   start node is
   <var title="">parent</var> and
   start offset is equal to
   the index of
   <var title="">node</var> + 1, increase its
   start offset by one.

For each range whose
   end node is
   <var title="">parent</var> and
   end offset is equal to
   the index of
   <var title="">node</var> + 1, increase its
   end offset by one.

Replace data with node
 <var title="">node</var>, offset <var title="">offset</var>, count
 <var title="">count</var>, and data the empty string.

If <var title="">parent</var> is null, run these substeps:

For each range whose
   start node is
   <var title="">node</var> and
   start offset is greater
   than <var title="">offset</var>, set its
   start offset to
   <var title="">offset</var>.

For each range whose
   end node is
   <var title="">node</var> and
   end offset is greater than
   <var title="">offset</var>, set its
   end offset to
   <var title="">offset</var>.

Return <var title="">new node</var>.

The
<dfn id="dom-text-splittext" title="dom-Text-splitText">splitText(<var>offset</var>)</dfn>
method must split the
context object with offset <var title="">offset</var>.

The <dfn id="contiguous-text-nodes">contiguous Text nodes</dfn> 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 <dfn id="dom-text-wholetext" title="dom-Text-wholeText">wholeText</dfn>
attribute must return a concatenation of the
data of the
contiguous Text nodes of the
context object, in
tree order.

5.11 Interface ProcessingInstruction

interface <dfn id="processinginstruction">ProcessingInstruction</dfn> : CharacterData {
  readonly attribute DOMString target;
};

ProcessingInstruction nodes
have an associated <dfn id="concept-pi-target" title="concept-PI-target">target</dfn>.

The <dfn id="dom-processinginstruction-target" title="dom-ProcessingInstruction-target">target</dfn>
attribute must return the target.

5.12 Interface Comment

[Constructor(optional DOMString <var title="">data</var> = "")]
interface <dfn id="comment">Comment</dfn> : CharacterData {
};

<var title="">comment</var> = new Comment([<var title="">data</var> = ""])

Returns a new Comment node whose
 data is <var title="">data</var>.

The <dfn id="dom-comment" title="dom-Comment">Comment(<var title="">data</var>)</dfn>
constructor must return a new Comment node
whose data is <var title="">data</var> and
node document is the global object's associated
document.

6 Ranges

6.1 Introduction to "DOM Ranges"

A Range object (range)
represents a sequence of content within a
node tree. Each
range has a
start and an
end which are
boundary points. A
boundary point is a tuple consisting of
a node and a non-negative numeric
offset. So in other words, a
range represents a piece of content within
a node tree between two
boundary points.

Ranges are frequently used in editing
for selecting and copying content.

Element: p

Element: img src="insanity-wolf" alt="Little-endian BOM; decode as big-endian!"

Text:  CSS 2.1 syndata is

Element: em

Text: awesome

Text: !

In the node tree above, a
range can be used to represent the sequence
"syndata is awes". Assuming <var title="">p</var> is assigned to the
p element, and
<var title="">em</var> to the em
element, this would be done as follows:

var range = new Range(),
    firstText = p.childNodes[1],
    secondText = em.firstChild
range.setStart(firstText, 9) // do not forget the leading space
range.setEnd(secondText, 4)
// range now stringifies to the aforementioned quote

Attributes such as
src and alt in the
node tree above cannot be represented
by a range. The
ranges concept is only useful for
nodes.

Ranges are affected by mutations to the
node tree. Such mutations will not
invalidate a range and will try to ensure
that the range still represents the same
piece of content. Necessarily, a range
might itself be modified as part of the mutation to the
node tree when e.g. part of the content
it represents is mutated.

See the insert and
remove algorithms, the
normalize() method, and the
replace data and
split algorithms for the hairy
details.

6.2 Interface Range

[Constructor]
interface <dfn id="range">Range</dfn> {
  readonly attribute Node startContainer;
  readonly attribute unsigned long startOffset;
  readonly attribute Node endContainer;
  readonly attribute unsigned long endOffset;
  readonly attribute boolean collapsed;
  readonly attribute Node commonAncestorContainer;

  void setStart(Node <var title="">node</var>, unsigned long <var title="">offset</var>);
  void setEnd(Node <var title="">node</var>, unsigned long <var title="">offset</var>);
  void setStartBefore(Node <var title="">node</var>);
  void setStartAfter(Node <var title="">node</var>);
  void setEndBefore(Node <var title="">node</var>);
  void setEndAfter(Node <var title="">node</var>);
  void collapse(optional boolean <var title="">toStart</var> = false);
  void selectNode(Node <var title="">node</var>);
  void selectNodeContents(Node <var title="">node</var>);

  const unsigned short <dfn id="dom-comparehow-start_to_start" title="dom-CompareHow-START_TO_START">START_TO_START</dfn> = 0;
  const unsigned short <dfn id="dom-comparehow-start_to_end" title="dom-CompareHow-START_TO_END">START_TO_END</dfn> = 1;
  const unsigned short <dfn id="dom-comparehow-end_to_end" title="dom-CompareHow-END_TO_END">END_TO_END</dfn> = 2;
  const unsigned short <dfn id="dom-comparehow-end_to_start" title="dom-CompareHow-END_TO_START">END_TO_START</dfn> = 3;
  short compareBoundaryPoints(unsigned short <var title="">how</var>, Range <var title="">sourceRange</var>);

  void deleteContents();
  [NewObject] DocumentFragment extractContents();
  [NewObject] DocumentFragment cloneContents();
  void insertNode(Node <var title="">node</var>);
  void surroundContents(Node <var title="">newParent</var>);

  [NewObject] Range cloneRange();
  void detach();

  boolean isPointInRange(Node <var title="">node</var>, unsigned long <var title="">offset</var>);
  short comparePoint(Node <var title="">node</var>, unsigned long <var title="">offset</var>);

  boolean intersectsNode(Node <var title="">node</var>);

  stringifier;
};

Range objects are simply known as
<dfn id="concept-range" title="concept-range">ranges</dfn>.

A <dfn id="concept-range-bp" title="concept-range-bp">boundary point</dfn> is a
(node,
<dfn id="concept-range-bp-offset" title="concept-range-bp-offset">offset</dfn>) tuple, where
offset is a non-negative
integer.

Generally speaking, a
boundary point's
offset will be between zero and
the boundary point's
node
length, inclusive. Algorithms that
modify a tree (in particular the
insert,
remove,
replace data, and
split algorithms) also modify
ranges associated with that
tree.

If the two nodes of
boundary points
(<var title="">node A</var>, <var title="">offset A</var>) and
(<var title="">node B</var>, <var title="">offset B</var>) have the same
root, the
<dfn id="concept-range-bp-position" title="concept-range-bp-position">position</dfn> of the first relative to
the second is either <dfn id="concept-range-bp-before" title="concept-range-bp-before">before</dfn>,
<dfn id="concept-range-bp-equal" title="concept-range-bp-equal">equal</dfn>, or
<dfn id="concept-range-bp-after" title="concept-range-bp-after">after</dfn>,
as returned by the following algorithm:

If <var title="">node A</var> is the same as <var title="">node B</var>,
 return equal if
 <var title="">offset A</var> is the same as <var title="">offset B</var>,
 before if
 <var title="">offset A</var> is less than <var title="">offset B</var>, and
 after if
 <var title="">offset A</var> is greater than <var title="">offset B</var>.

If <var title="">node A</var> is
 following
 <var title="">node B</var>, compute the
 position of
 (<var title="">node B</var>, <var title="">offset B</var>) relative to
 (<var title="">node A</var>, <var title="">offset A</var>). If it is
 before, return
 after. If it is
 after, return
 before.

If <var title="">node A</var> is an
  ancestor of
  <var title="">node B</var>:

Let <var title="">child</var> equal <var title="">node B</var>.

While <var title="">child</var> is not a
   child of <var title="">node A</var>,
   set <var title="">child</var> to its
   parent.

If the index of
   <var title="">child</var> is less than <var title="">offset A</var>, return
   after.

Return before.

Each range has two associated
boundary points — a
<dfn id="concept-range-start" title="concept-range-start">start</dfn> and
<dfn id="concept-range-end" title="concept-range-end">end</dfn>.

For convenience, <dfn id="concept-range-start-node" title="concept-range-start-node">start node</dfn> is
start's
node,
<dfn id="concept-range-start-offset" title="concept-range-start-offset">start offset</dfn> is
start's
offset,
<dfn id="concept-range-end-node" title="concept-range-end-node">end node</dfn> is
end's
node,  and
<dfn id="concept-range-end-offset" title="concept-range-end-offset">end offset</dfn> is
end's
offset.

The <dfn id="concept-range-root" title="concept-range-root">root</dfn> of a
range is the
root of its
start node.

A node <var title="">node</var> is
<dfn id="contained">contained</dfn> in a range
<var title="">range</var> if <var title="">node</var>'s
root is
the same as <var title="">range</var>'s
root, and (<var title="">node</var>, 0)
is after <var title="">range</var>'s
start, and (<var title="">node</var>,
length of <var title="">node</var>) is
before <var title="">range</var>'s
end.

A node is <dfn id="partially-contained">partially contained</dfn>
in a range if it is an
inclusive ancestor of the
range's
start node but not its
end node, or vice versa.

Some facts to better understand these definitions:

The content that one would think of as being within the
  range consists of all
  contained nodes, plus
  possibly some of the contents of the
  start node and
  end node if those are
  Text, ProcessingInstruction, or
  Comment nodes.

The nodes that are contained in a
  range will generally not be contiguous,
  because the parent of a
  contained node will not
  always be contained.

However, the descendants
  of a contained node are
  contained, and if two
  siblings are
  contained, so are any
  siblings that lie between them.

The first contained
  node (if there are any) will always be
  after the start node, and the
  last contained node will
  always be equal to or before the
  end node's last
  descendant.

The start node and
  end node of a
  range are never contained
  within it.

There exists some partially contained
  node if and only if the
  start node and
  end node are different.

The
  commonAncestorContainer
  attribute value is never contained or
  partially contained.

If the start node is an
  ancestor of the
  end node, the common
  inclusive ancestor will
  be the start node. Exactly one
  of its children will be
  partially contained, and a
  child will be contained
  if and only if it precedes the
  partially contained
  child. If the
  end node is an
  ancestor of the
  start node, the opposite
  holds.

If the start node is
  not an
  inclusive ancestor of
  the end node, nor vice versa,
  the common
  inclusive ancestor will
  be distinct from both of them. Exactly two of its
  children will be
  partially contained, and a
  child will be contained if and only
  if it lies between those two.

<var title="">range</var> = new Range()

Returns a new range.

The <dfn id="dom-range" title="dom-Range">Range()</dfn> constructor must return a new
range with
(global object's associated document, 0) as its
start and
end.

<var title="">node</var> = <var title="">range</var> . startContainer

Returns <var title="">range</var>'s
 start node.

<var title="">offset</var> = <var title="">range</var> . startOffset

Returns <var title="">range</var>'s
 start offset.

<var title="">node</var> = <var title="">range</var> . endContainer

Returns <var title="">range</var>'s
 end node.

<var title="">offset</var> = <var title="">range</var> . endOffset

Returns <var title="">range</var>'s
 end offset.

<var title="">collapsed</var> = <var title="">range</var> . collapsed

Returns true if <var title="">range</var>'s
 start and
 end are the same, and false otherwise.

<var title="">container</var> = <var title="">range</var> . commonAncestorContainer

Returns the node, furthest away from
 the document, that is an
 ancestor of both
 <var title="">range</var>'s
 start node and
 end node.

The <dfn id="dom-range-startcontainer" title="dom-Range-startContainer">startContainer</dfn>
attribute must return the
start node.

The <dfn id="dom-range-startoffset" title="dom-Range-startOffset">startOffset</dfn>
attribute must return the
start offset.

The <dfn id="dom-range-endcontainer" title="dom-Range-endContainer">endContainer</dfn>
attribute must return the
end node.

The <dfn id="dom-range-endoffset" title="dom-Range-endOffset">endOffset</dfn>
attribute must return the
end offset.

The <dfn id="dom-range-collapsed" title="dom-Range-collapsed">collapsed</dfn> attribute
must return true if start is the same
as end, and false otherwise.

The
<dfn id="dom-range-commonancestorcontainer" title="dom-Range-commonAncestorContainer">commonAncestorContainer</dfn>
attribute must run these steps:

Let <var title="">container</var> be
 start node.

While <var title="">container</var> is not an
 inclusive ancestor of
 end node, let
 <var title="">container</var> be <var title="">container</var>'s
 parent.

Return <var title="">container</var>.

To <dfn id="concept-range-bp-set" title="concept-range-bp-set">set the start or end</dfn> of a
<var title="">range</var> to a
boundary point
(<var title="">node</var>, <var title="">offset</var>), run these steps:

If <var title="">node</var> is a
 doctype,
 throw an
 "InvalidNodeTypeError" exception.

If <var title="">offset</var> is greater than
 <var title="">node</var>'s length,
 throw an
 "IndexSizeError" exception.

Let <var title="">bp</var> be the
 boundary point
 (<var title="">node</var>, <var title="">offset</var>).

If these steps were invoked as "set the start"

If <var title="">bp</var> is
     after the
     <var title="">range</var>'s end, or
     if <var title="">range</var>'s
     root is not equal to
     <var title="">node</var>'s root, set
     <var title="">range</var>'s end to
     <var title="">bp</var>.

Set <var title="">range</var>'s
     start to <var title="">bp</var>.

If these steps were invoked as "set the end"

If <var title="">bp</var> is
     before the
     <var title="">range</var>'s start,
     or if <var title="">range</var>'s
     root is not equal to
     <var title="">node</var>'s root, set
     <var title="">range</var>'s start
     to <var title="">bp</var>.

Set <var title="">range</var>'s
     end to <var title="">bp</var>.

The
<dfn id="dom-range-setstart" title="dom-Range-setStart">setStart(<var>node</var>, <var>offset</var>)</dfn>
method must set the start of the
context object to
boundary point
(<var title="">node</var>, <var title="">offset</var>).

The
<dfn id="dom-range-setend" title="dom-Range-setEnd">setEnd(<var>node</var>, <var>offset</var>)</dfn>
method must set the end of the
context object to
boundary point
(<var title="">node</var>, <var title="">offset</var>).

The
<dfn id="dom-range-setstartbefore" title="dom-Range-setStartBefore">setStartBefore(<var>node</var>)</dfn>
method must run these steps:

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is null,
 throw an
 "InvalidNodeTypeError" exception.

Set the start of the
 context object to
 boundary point
 (<var title="">parent</var>, <var title="">node</var>'s
 index).

The
<dfn id="dom-range-setstartafter" title="dom-Range-setStartAfter">setStartAfter(<var>node</var>)</dfn>
method must run these steps:

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is null,
 throw an
 "InvalidNodeTypeError" exception.

Set the start of the
 context object to
 boundary point
 (<var title="">parent</var>, <var title="">node</var>'s
 index plus one).

The
<dfn id="dom-range-setendbefore" title="dom-Range-setEndBefore">setEndBefore(<var>node</var>)</dfn>
method must run these steps:

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is null,
 throw an
 "InvalidNodeTypeError" exception.

Set the end of the
 context object to
 boundary point
 (<var title="">parent</var>, <var title="">node</var>'s
 index).

The
<dfn id="dom-range-setendafter" title="dom-Range-setEndAfter">setEndAfter(<var>node</var>)</dfn>
method must run these steps:

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is null,
 throw an
 "InvalidNodeTypeError" exception.

Set the end of the
 context object to
 boundary point
 (<var title="">parent</var>, <var title="">node</var>'s
 index plus one).

The
<dfn id="dom-range-collapse" title="dom-Range-collapse">collapse(<var>toStart</var>)</dfn>
method must if <var title="">toStart</var> is true, set
end to
start, and set
start to
end otherwise.

To <dfn id="concept-range-select" title="concept-range-select">select</dfn> a node
<var title="">node</var> within a range
<var title="">range</var>, run these steps:

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is null, throw an
 "InvalidNodeTypeError".

Let <var title="">index</var> be <var title="">node</var>'s
 index.

Set <var title="">range</var>'s start to
 boundary point
 (<var title="">parent</var>, <var title="">index</var>).

Set <var title="">range</var>'s end to
 boundary point
 (<var title="">parent</var>, <var title="">index</var> plus one).

The
<dfn id="dom-range-selectnode" title="dom-Range-selectNode">selectNode(<var>node</var>)</dfn>
method must select <var title="">node</var> within
context object.

The
<dfn id="dom-range-selectnodecontents" title="dom-Range-selectNodeContents">selectNodeContents(<var>node</var>)</dfn>
method must run these steps:

If <var title="">node</var> is a
 doctype,
 throw an
 "InvalidNodeTypeError".

Let <var title="">length</var> be the
 length of <var title="">node</var>.

Set start to the
 boundary point
 (<var title="">node</var>, 0).

Set end to the
 boundary point
 (<var title="">node</var>, <var title="">length</var>).

The
<dfn id="dom-range-compareboundarypoints" title="dom-Range-compareBoundaryPoints">compareBoundaryPoints(<var>how</var>, <var>sourceRange</var>)</dfn>
method must run these steps:

If <var>how</var> is not one of

START_TO_START,

START_TO_END,

END_TO_END, and

END_TO_START,

throw a
  "NotSupportedError" exception.

If context object's
 root is not the same as
 <var title="">sourceRange</var>'s root,
 throw a
 "WrongDocumentError" exception.

If <var title="">how</var> is:

START_TO_START:

Let <var title="">this point</var> be the context object's
    start.

Let <var title="">other point</var> be <var title="">sourceRange</var>'s
    start.

START_TO_END:

Let <var title="">this point</var> be the context object's
    end.

Let <var title="">other point</var> be <var title="">sourceRange</var>'s
    start.

END_TO_END:

Let <var title="">this point</var> be the context object's
     end.

Let <var title="">other point</var> be <var title="">sourceRange</var>'s
     end.

END_TO_START:

Let <var title="">this point</var> be the context object's
     start.

Let <var title="">other point</var> be <var title="">sourceRange</var>'s
     end.

If the position of
   <var title="">this point</var> relative to <var title="">other point</var> is

before

Return −1.

equal

Return 0.

after

Return 1.

The <dfn id="dom-range-deletecontents" title="dom-Range-deleteContents">deleteContents()</dfn>
method must run these steps:

If start equals
 end, terminate these steps.

Let <var title="">original start node</var>,
 <var title="">original start offset</var>, <var title="">original end node</var>,
 and <var title="">original end offset</var> be the
 context object's
 start node,
 start offset,
 end node, and
 end offset, respectively.

If <var title="">original start node</var> and
 <var title="">original end node</var> are the same, and they are a
 Text, ProcessingInstruction, or
 Comment node,
 replace data with node
 <var title="">original start node</var>, offset
 <var title="">original start offset</var>, count
 <var title="">original end offset</var> minus
 <var title="">original start offset</var>, and data the empty string, and then
 terminate these steps.

Let <var title="">nodes to remove</var> be a list of all the
 nodes that are contained in
 the context object, in
 tree order, omitting any
 node whose
 parent is also
 contained in the context object.

If <var title="">original start node</var> is an
 inclusive ancestor of
 <var title="">original end node</var>, set
 <var title="">new node</var> to <var title="">original start node</var> and
 <var title="">new offset</var> to <var title="">original start offset</var>.

Otherwise:

Let <var title="">reference node</var> equal
   <var title="">original start node</var>.

While <var title="">reference node</var>'s
   parent is not null and is not an
   inclusive ancestor of
   <var title="">original end node</var>, set <var title="">reference node</var>
   to its parent.

Set <var title="">new node</var> to the
    parent of
    <var title="">reference node</var>, and <var title="">new offset</var> to one
    plus the index of
    <var title="">reference node</var>.

If <var title="">reference node</var>'s
    parent were null, it would be the
    root of the
    context object, so would be an
    inclusive ancestor of
    <var title="">original end node</var>, and we could not reach this point.

If <var title="">original start node</var> is a Text,
 ProcessingInstruction, or Comment
 node,
 replace data with node
 <var title="">original start node</var>, offset
 <var title="">original start offset</var>, count
 <var title="">original start node</var>'s
 length minus
 <var title="">original start offset</var>, data the empty string.

For each <var title="">node</var> in <var title="">nodes to remove</var>,
 in tree order,
 remove <var title="">node</var> from
 its parent.

If <var title="">original end node</var> is a Text,
 ProcessingInstruction, or Comment
 node,
 replace data with node
 <var title="">original end node</var>, offset 0, count
 <var title="">original end offset</var> and data the empty string.

Set start and
 end to
 (<var title="">new node</var>, <var title="">new offset</var>).

To <dfn id="concept-range-extract" title="concept-range-extract">extract</dfn> a
range <var title="">range</var>, run these steps:

Let <var title="">fragment</var> be a new DocumentFragment
 node whose
 node document is <var title="">range</var>'s
 start node's
 node document.

If <var title="">range</var>'s start equals
 its end, return <var title="">fragment</var>.

Let <var title="">original start node</var>, <var title="">original start offset</var>,
 <var title="">original end node</var>, and <var title="">original end offset</var> be
 <var title="">range</var>'s start node,
 start offset,
 end node, and
 end offset, respectively.

If <var title="">original start node</var> equals
  <var title="">original end node</var>, and they are a Text,
  ProcessingInstruction, or Comment
  node:

Let <var title="">clone</var> be a
   clone of
   <var title="">original start node</var>.

Set the data of
   <var title="">clone</var> to the result of
   substringing data with node
   <var title="">original start node</var>, offset
   <var title="">original start offset</var>, and count
   <var title="">original end offset</var> minus
   <var title="">original start offset</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Replace data with node
   <var title="">original start node</var>, offset
   <var title="">original start offset</var>, count
   <var title="">original end offset</var> minus
   <var title="">original start offset</var>, and data the empty string.

Return <var title="">fragment</var>.

Let <var title="">common ancestor</var> be
 <var title="">original start node</var>.

While <var title="">common ancestor</var> is not an
 inclusive ancestor of
 <var title="">original end node</var>, set <var title="">common ancestor</var> to
 its own parent.

Let <var title="">first partially contained child</var> be null.

If <var title="">original start node</var> is not an
 inclusive ancestor of
 <var title="">original end node</var>, set <var title="">first partially contained child</var>
 to the first child of
 <var title="">common ancestor</var> that is partially contained in
 <var title="">range</var>.

Let <var title="">last partially contained child</var> be null.

If <var title="">original end node</var> is not an
  inclusive ancestor of
  <var title="">original start node</var>, set
  <var title="">last partially contained child</var> to the last
  child of <var title="">common ancestor</var> that is
  partially contained in <var title="">range</var>.

These variable assignments do actually always make sense.
  For instance, if <var title="">original start node</var> is not an
  inclusive ancestor of
  <var title="">original end node</var>, <var title="">original start node</var> is itself
  partially contained in <var title="">range</var>, and so are all its
  ancestors up until a
  child of <var title="">common ancestor</var>.
  <var title="">common ancestor</var> cannot be <var title="">original start node</var>, because
  it has to be an inclusive ancestor of
  <var title="">original end node</var>. The other case is similar. Also, notice that the two
  children will never be equal if both are defined.

Let <var title="">contained children</var> be a list of all
 children of
 <var title="">common ancestor</var> that are contained in
 <var title="">range</var>, in tree order.

If any member of <var title="">contained children</var> is a
  doctype, throw a
  "HierarchyRequestError" exception.

We do not have to worry about the first or last partially
  contained node, because a doctype can never be
  partially contained. It cannot be a boundary point of a range, and it
  cannot be the ancestor of anything.

If <var title="">original start node</var> is an
 inclusive ancestor of
 <var title="">original end node</var>, set <var title="">new node</var> to
 <var title="">original start node</var> and <var title="">new offset</var> to
 <var title="">original start offset</var>.

Otherwise:

Let <var title="">reference node</var> equal <var title="">original start node</var>.

While <var title="">reference node</var>'s
   parent is not null and is not an
   inclusive ancestor of
   <var title="">original end node</var>, set <var title="">reference node</var> to its
   parent.

Set <var title="">new node</var> to the
    parent of <var title="">reference node</var>, and
    <var title="">new offset</var> to one plus <var title="">reference node</var>'s
    index.

If <var title="">reference node</var>'s
    parent is null, it would be the
    root of <var title="">range</var>, so would be an
    inclusive ancestor of
    <var title="">original end node</var>, and we could not reach this point.

If <var title="">first partially contained child</var> is a
  Text, ProcessingInstruction, or
  Comment node:

In this case, <var title="">first partially contained child</var> is
  <var title="">original start node</var>.

Let <var title="">clone</var> be a
   clone of
   <var title="">original start node</var>.

Set the data of
   <var title="">clone</var> to the result of
   substringing data with node
   <var title="">original start node</var>, offset
   <var title="">original start offset</var>, and count
   <var title="">original start node</var>'s
   length minus
   <var title="">original start offset</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Replace data with node
   <var title="">original start node</var>, offset
   <var title="">original start offset</var>, count
   <var title="">original start node</var>'s
   length minus
   <var title="">original start offset</var>, and data the empty string.

Otherwise, if <var title="">first partially contained child</var> is not
  null:

Let <var title="">clone</var> be a
   clone of
   <var title="">first partially contained child</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Let <var title="">subrange</var> be a new range
   whose start is
   (<var title="">original start node</var>, <var title="">original start offset</var>) and
   whose end is
   (<var title="">first partially contained child</var>, <var title="">first partially contained child</var>'s length).

Let <var title="">subfragment</var> be the result of
   extracting <var title="">subrange</var>.

Append <var title="">subfragment</var> to
   <var title="">fragment</var>.

For each <var title="">contained child</var> in <var title="">contained children</var>,
 append <var title="">contained child</var> to
 <var title="">fragment</var>.

If <var title="">last partially contained child</var> is a
  Text, ProcessingInstruction, or
  Comment node:

In this case, <var title="">last partially contained child</var> is
  <var title="">original end node</var>.

Let <var title="">clone</var> be a clone of
   <var title="">original end node</var>.

Set the data of
   <var title="">clone</var> to the result of
   substringing data with node
   <var title="">original end node</var>, offset 0, and count
   <var title="">original end offset</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Replace data with node
   <var title="">original end node</var>, offset 0, count
   <var title="">original end offset</var>, and data the empty string.

Otherwise, if <var title="">last partially contained child</var> is not
  null:

Let <var title="">clone</var> be a
   clone of
   <var title="">last partially contained child</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Let <var title="">subrange</var> be a new range
   whose start is
   (<var title="">last partially contained child</var>, 0) and whose
   end is
   (<var title="">original end node</var>, <var title="">original end offset</var>).

Let <var title="">subfragment</var> be the result of
   extracting <var title="">subrange</var>.

Append <var title="">subfragment</var> to
   <var title="">fragment</var>.

Set <var title="">range</var>'s start and
 end to
 (<var title="">new node</var>, <var title="">new offset</var>).

Return <var title="">fragment</var>.

The <dfn id="dom-range-extractcontents" title="dom-Range-extractContents">extractContents()</dfn> method
must return the result of extracting
context object.

To <dfn id="concept-range-clone" title="concept-range-clone">clone</dfn> a range
<var title="">range</var>, run these steps:

Let <var title="">fragment</var> be a new DocumentFragment
 node whose
 node document is <var title="">range</var>'s
 start node's
 node document.

If <var title="">range</var>'s start equals
 its end, return <var title="">fragment</var>.

Let <var title="">original start node</var>, <var title="">original start offset</var>,
 <var title="">original end node</var>, and <var title="">original end offset</var> be
 <var title="">range</var>'s start node,
 start offset,
 end node, and
 end offset, respectively.

If <var title="">original start node</var> equals
  <var title="">original end node</var>, and they are a Text,
  ProcessingInstruction, or Comment
  node:

Let <var title="">clone</var> be a clone of
   <var title="">original start node</var>.

Set the data of
   <var title="">clone</var> to the result of
   substringing data with node
   <var title="">original start node</var>, offset
   <var title="">original start offset</var>, and count
   <var title="">original end offset</var> minus
   <var title="">original start offset</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Return <var title="">fragment</var>.

Let <var title="">common ancestor</var> be
 <var title="">original start node</var>.

While <var title="">common ancestor</var> is not an
 inclusive ancestor of
 <var title="">original end node</var>, set
 <var title="">common ancestor</var> to its own
 parent.

Let <var title="">first partially contained child</var> be null.

If <var title="">original start node</var> is not an
 inclusive ancestor of
 <var title="">original end node</var>, set <var title="">first partially contained child</var>
 to the first child of
 <var title="">common ancestor</var> that is partially contained in
 <var title="">range</var>.

Let <var title="">last partially contained child</var> be null.

If <var title="">original end node</var> is not an
  inclusive ancestor of
  <var title="">original start node</var>, set
  <var title="">last partially contained child</var> to the last
  child of <var title="">common ancestor</var> that is
  partially contained in <var title="">range</var>.

These variable assignments do actually always make sense.
  For instance, if <var title="">original start node</var> is not an
  inclusive ancestor of
  <var title="">original end node</var>, <var title="">original start node</var> is itself
  partially contained in <var title="">range</var>, and so are all its
  ancestors up until a
  child of <var title="">common ancestor</var>.
  <var title="">common ancestor</var> cannot be <var title="">original start node</var>, because
  it has to be an inclusive ancestor of
  <var title="">original end node</var>. The other case is similar. Also, notice that the two
  children will never be equal if both are defined.

Let <var title="">contained children</var> be a list of all
 children of
 <var title="">common ancestor</var> that are contained in
 <var title="">range</var>, in tree order.

If any member of <var title="">contained children</var> is a
  doctype, throw a
  "HierarchyRequestError" exception.

We do not have to worry about the first or last partially
  contained node, because a doctype can never be
  partially contained. It cannot be a boundary point of a range, and it
  cannot be the ancestor of anything.

If <var title="">first partially contained child</var> is a
  Text, ProcessingInstruction, or
  Comment node:

In this case, <var title="">first partially contained child</var> is
  <var title="">original start node</var>.

Let <var title="">clone</var> be a
   clone of
   <var title="">original start node</var>.

Set the data of
   <var title="">clone</var> to the result of
   substringing data with node
   <var title="">original start node</var>, offset
   <var title="">original start offset</var>, and count
   <var title="">original start node</var>'s
   length minus
   <var title="">original start offset</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Otherwise, if <var title="">first partially contained child</var> is not
  null:

Let <var title="">clone</var> be a
   clone of
   <var title="">first partially contained child</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Let <var title="">subrange</var> be a new range
   whose start is
   (<var title="">original start node</var>, <var title="">original start offset</var>) and
   whose end is
   (<var title="">first partially contained child</var>, <var title="">first partially contained child</var>'s length).

Let <var title="">subfragment</var> be the result of
   cloning <var title="">subrange</var>.

Append <var title="">subfragment</var> to
   <var title="">fragment</var>.

For each <var title="">contained child</var> in
  <var title="">contained children</var>:

Let <var title="">clone</var> be a clone of
   <var title="">contained child</var>.

Append <var title="">clone</var> to
   <var title="">fragment</var>.

If <var title="">last partially contained child</var> is a
  Text, ProcessingInstruction, or
  Comment node:

In this case, <var title="">last partially contained child</var> is
  <var title="">original end node</var>.

Let <var title="">clone</var> be a clone of
   <var title="">original end node</var>.

Set the data of
   <var title="">clone</var> to the result of
   substringing data with node
   <var title="">original end node</var>, offset 0, and count
   <var title="">original end offset</var>.

Append <var title="">clone</var> to
   <var title="">fragment</var>.

Otherwise, if <var title="">last partially contained child</var> is not
  null:

Let <var title="">clone</var> be a
   clone of
   <var title="">last partially contained child</var>.

Append <var title="">clone</var>
   to <var title="">fragment</var>.

Let <var title="">subrange</var> be a new range
   whose start is
   (<var title="">last partially contained child</var>, 0) and whose
   end is
   (<var title="">original end node</var>, <var title="">original end offset</var>).

Let <var title="">subfragment</var> be the result of
   cloning <var title="">subrange</var>.

Append <var title="">subfragment</var> to
   <var title="">fragment</var>.

Return <var title="">fragment</var>.

The <dfn id="dom-range-clonecontents" title="dom-Range-cloneContents">cloneContents()</dfn>
method must return the result of cloning
context object.

To <dfn id="concept-range-insert" title="concept-range-insert">insert</dfn> a node
<var title="">node</var> into a range
<var title="">range</var>, run these steps:

If <var title="">range</var>'s start node
 is either a ProcessingInstruction or Comment
 node, or a Text
 node whose parent
 is null, throw an "HierarchyRequestError"
 exception.

If <var title="">node</var>'s parent is not
 null, remove <var title="">node</var> from its
 parent.

Let <var title="">referenceNode</var> be null.

If <var title="">range</var>'s start node
 is a Text node,
 split it with offset
 <var title="">range</var>'s start offset, and
 set <var title="">referenceNode</var> to the result.

Otherwise, set <var title="">referenceNode</var> to the
 child of
 start node whose
 index is
 start offset, and null if
 there is no such child otherwise.

Let <var title="">parent</var> be <var title="">range</var>'s
 start node if <var title="">referenceNode</var>
 is null, and <var title="">referenceNode</var>'s
 parent otherwise.

Let <var title="">newOffset</var> be <var title="">parent</var>'s
 length if <var title="">referenceNode</var> is null,
 and <var title="">referenceNode</var>'s index
 otherwise.

Increase <var title="">newOffset</var> by <var title="">node</var>'s
 length if <var title="">node</var> is a
 DocumentFragment node, and one otherwise.

Pre-insert
 <var title="">node</var> into <var title="">parent</var> before <var title="">referenceNode</var>.

If <var title="">range</var>'s start and
 end are the same, set <var title="">range</var>'s
 end to
 (<var title="">parent</var>, <var title="">newOffset</var>).

The <dfn id="dom-range-insertnode" title="dom-Range-insertNode">insertNode(<var>node</var>)</dfn>
method must insert <var title="">node</var> into
context object.

The
<dfn id="dom-range-surroundcontents" title="dom-Range-surroundContents">surroundContents(<var>newParent</var>)</dfn>
method must run these steps:

If a non-Text node is
 partially contained in the context object,
 throw an
 "InvalidStateError" exception.

If <var title="">newParent</var> is a Document,
 DocumentType, or DocumentFragment
 node,
 throw an
 "InvalidNodeTypeError" exception.

Let <var title="">fragment</var> be the result of
 extracting context object.

If <var title="">newParent</var> has
 children,
 replace all with null within
 <var title="">newParent</var>.

Insert <var title="">newParent</var> into
 context object.

Append <var title="">fragment</var> to
 <var title="">newParent</var>.

Select <var title="">newParent</var> within
 context object.

The <dfn id="dom-range-clonerange" title="dom-Range-cloneRange">cloneRange()</dfn>
method must return a new range with the
same start and
end as the context object.

The <dfn id="dom-range-detach" title="dom-Range-detach">detach()</dfn> method must
do nothing. Its functionality (disabling a
Range object) was removed, but the method itself is preserved
for compatibility.

<var title="">position</var> = <var title="">range</var> . comparePoint( <var title="">parent</var>, <var title="">offset</var> )

Returns −1 if the point is before the range, 0 if the point is
 in the range, and 1 if the point is after the range.

<var title="">intersects</var> = <var title="">range</var> . intersectsNode( <var title="">node</var> )

Returns whether <var title="">range</var> intersects
 <var title="">node</var>.

The
<dfn id="dom-range-ispointinrange" title="dom-Range-isPointInRange">isPointInRange(<var>node</var>, <var>offset</var>)</dfn>
must run these steps:

If <var title="">node</var>'s root is
 different from the context object's root, return false.

If <var title="">node</var> is a
 doctype,
 throw an
 "InvalidNodeTypeError" exception.

If <var title="">offset</var> is greater than
 <var title="">node</var>'s length,
 throw an
 "IndexSizeError" exception.

If (<var title="">node</var>, <var title="">offset</var>) is
 before
 start or
 after
 end, return false.

Return true.

The
<dfn id="dom-range-comparepoint" title="dom-Range-comparePoint">comparePoint(<var>node</var>, <var>offset</var>)</dfn>
method must run these steps:

If <var title="">node</var>'s root is
 different from the context object's
 root,
 throw a "WrongDocumentError"
 exception.

If <var title="">node</var> is a
 doctype,
 throw an
 "InvalidNodeTypeError" exception.

If <var title="">offset</var> is greater than
 <var title="">node</var>'s length,
 throw an
 "IndexSizeError" exception.

If (<var title="">node</var>, <var title="">offset</var>) is
 before
 start, return −1.

If (<var title="">node</var>, <var title="">offset</var>) is
 after
 end, return 1.

Return 0.

The
<dfn id="dom-range-intersectsnode" title="dom-Range-intersectsNode">intersectsNode(<var>node</var>)</dfn>
method must run these steps:

If <var title="">node</var>'s root
 is different from the context object's
 root, return false.

Let <var title="">parent</var> be <var title="">node</var>'s
 parent.

If <var title="">parent</var> is null, return true.

Let <var title="">offset</var> be <var title="">node</var>'s
 index.

If (<var title="">parent</var>, <var title="">offset</var>) is
 before
 end and (<var title="">parent</var>,
 <var title="">offset</var> + 1) is
 after
 start, return true.

Return false.

The <dfn id="dom-range-stringifier" title="dom-Range-stringifier">stringifier</dfn> must run these
steps:

Let <var title="">s</var> be the empty string.

If start node equals
 end node, and it is a
 Text node, return the
 substring of that Text node's data beginning at
 start offset and ending at
 end offset.

If start node is a
 Text node, append to
 <var title="">s</var> the substring of that
 node's
 data from the
 start offset until the end.

Append to <var title="">s</var> the concatenation, in
 tree order, of the
 data of all Text
 nodes that are contained in
 the context object.

If end node is a
 Text node, append to
 <var title="">s</var> the substring of that
 node's
 data from its start until the
 end offset.

Return <var title="">s</var>.

The
createContextualFragment(),
getClientRects(),
and
getBoundingClientRect()
methods are defined in other specifications.
[DOMPS]
[CSSOMVIEW]

7 Traversal

NodeIterator and TreeWalker objects can be used
to filter and traverse node
trees.

Each NodeIterator and TreeWalker object has an
associated <dfn id="concept-traversal-active" title="concept-traversal-active">active flag</dfn> to avoid
recursive invocations. It is initially unset.

Each NodeIterator and TreeWalker object also
has an associated <dfn id="concept-traversal-root" title="concept-traversal-root">root</dfn>
node,
<dfn id="concept-traversal-whattoshow" title="concept-traversal-whatToShow">whatToShow</dfn> bitmask, and
<dfn id="concept-traversal-filter" title="concept-traversal-filter">filter</dfn> callback.

To <dfn id="concept-node-filter" title="concept-node-filter">filter</dfn> <var title="">node</var> run
these steps:

If active flag is set
 throw an
 "InvalidStateError".

Let <var title="">n</var> be <var title="">node</var>'s
 nodeType attribute value minus 1.

If the <var title="">n</var>th bit (where 0 is the least
 significant bit) of
 whatToShow is not set,
 return FILTER_SKIP.

If filter is null,
 return FILTER_ACCEPT.

Set the active flag.

Let <var title="">result</var> be the return value of invoking
 filter.

Unset the active flag.

If an exception was thrown, re-throw the exception.

Return <var title="">result</var>.

7.1 Interface NodeIterator

interface <dfn id="nodeiterator">NodeIterator</dfn> {
  [SameObject] readonly attribute Node root;
  readonly attribute Node referenceNode;
  readonly attribute boolean pointerBeforeReferenceNode;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;

  Node? nextNode();
  Node? previousNode();

  void detach();
};

NodeIterator objects can be created using the
createNodeIterator()
method.

Each NodeIterator object has an associated
<dfn id="iterator-collection">iterator collection</dfn>, which is a
collection rooted at
root, whose filter matches any
node.

Before a node is removed from the
iterator collection, these steps must be run:

If the node is not a
 descendant of
 root and is not an
 ancestor of the
 referenceNode attribute
 value or the
 referenceNode attribute
 value itself, terminate these steps.

If the
 pointerBeforeReferenceNode
 attribute value is false, set the
 referenceNode attribute
 to the first node
 preceding the
 node that is being removed, and terminate
 these steps.

If the
 pointerBeforeReferenceNode
 attribute value is true and there is a node
 following the
 node that is being removed, set the
 referenceNode attribute
 to the first such node, and terminate these
 steps.

Set the
 referenceNode attribute
 to the first node
 preceding the
 node that is being removed and set the
 pointerBeforeReferenceNode
 attribute to false.

As mentioned earlier NodeIterator objects have an
associated active flag,
root
node,
whatToShow bitmask, and
filter callback as well.

The <dfn id="dom-nodeiterator-root" title="dom-NodeIterator-root">root</dfn> attribute
must return root.

The
<dfn id="dom-nodeiterator-referencenode" title="dom-NodeIterator-referenceNode">referenceNode</dfn>
and
<dfn id="dom-nodeiterator-pointerbeforereferencenode" title="dom-NodeIterator-pointerBeforeReferenceNode">pointerBeforeReferenceNode</dfn>
attributes must return what they were initialized to.

The <dfn id="dom-nodeiterator-whattoshow" title="dom-NodeIterator-whatToShow">whatToShow</dfn>
attribute must return
whatToShow.

The <dfn id="dom-nodeiterator-filter" title="dom-NodeIterator-filter">filter</dfn>
attribute must return filter.

To <dfn id="concept-nodeiterator-traverse" title="concept-NodeIterator-traverse">traverse</dfn> in direction
<var title="">direction</var> run these steps:

Let <var title="">node</var> be the value of the
 referenceNode attribute.

Let <var title="">before node</var> be the value of the
 pointerBeforeReferenceNode
 attribute.

Run these substeps:

If direction is next

If <var title="">before node</var> is false, let <var title="">node</var>
      be the first node
      following
      <var title="">node</var> in the iterator collection. If
      there is no such node return null.

If <var title="">before node</var> is true, set it to false.

If direction is previous

If <var title="">before node</var> is true, let <var title="">node</var>
      be the first node
      preceding
      <var title="">node</var> in the iterator collection. If
      there is no such node return null.

If <var title="">before node</var> is false, set it to true.

Filter
   <var title="">node</var> and let <var title="">result</var> be the return
   value.

If <var title="">result</var> is
    FILTER_ACCEPT, go to the
    next step in the overall set of steps.

Otherwise, run these substeps again.

Set the
 referenceNode attribute
 to <var title="">node</var>, set the
 pointerBeforeReferenceNode
 attribute to <var title="">before node</var>, and return
 <var title="">node</var>.

The <dfn id="dom-nodeiterator-nextnode" title="dom-NodeIterator-nextNode">nextNode()</dfn>
method must traverse in
direction next.

The
<dfn id="dom-nodeiterator-previousnode" title="dom-NodeIterator-previousNode">previousNode()</dfn>
method must traverse in
direction previous.

The <dfn id="dom-nodeiterator-detach" title="dom-NodeIterator-detach">detach()</dfn>
method must do nothing. Its functionality (disabling a
NodeIterator object) was removed, but the method itself is preserved
for compatibility.

7.2 Interface TreeWalker

interface <dfn id="treewalker">TreeWalker</dfn> {
  [SameObject] readonly attribute Node root;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;
           attribute Node currentNode;

  Node? parentNode();
  Node? firstChild();
  Node? lastChild();
  Node? previousSibling();
  Node? nextSibling();
  Node? previousNode();
  Node? nextNode();
};

TreeWalker objects can be created using the
createTreeWalker() method.

As mentioned earlier TreeWalker objects have an
associated active flag,
root
node,
whatToShow bitmask, and
filter callback.

The <dfn id="dom-treewalker-root" title="dom-TreeWalker-root">root</dfn> attribute must
return root.

The <dfn id="dom-treewalker-whattoshow" title="dom-TreeWalker-whatToShow">whatToShow</dfn>
attribute must return
whatToShow.

The <dfn id="dom-treewalker-filter" title="dom-TreeWalker-filter">filter</dfn> attribute
must return filter.

The <dfn id="dom-treewalker-currentnode" title="dom-TreeWalker-currentNode">currentNode</dfn>
attribute must return what it was initialized to.

Setting the currentNode
attribute must set it to the new value.

The <dfn id="dom-treewalker-parentnode" title="dom-TreeWalker-parentNode">parentNode()</dfn>
method must run these steps:

Let <var title="">node</var> be the value of the
 currentNode attribute.

While <var title="">node</var> is not null and is not
  root, run these substeps:

Let <var title="">node</var> be <var title="">node</var>'s
   parent.

If <var title="">node</var> is not null and
   filtering <var title="">node</var>
   returns FILTER_ACCEPT,
   then set the currentNode
   attribute to <var title="">node</var>, return <var title="">node</var>.

Return null.

To <dfn id="concept-traverse-children" title="concept-traverse-children">traverse children</dfn> of type
<var title="">type</var>, run these steps:

Let <var title="">node</var> be the value
 of the currentNode attribute.

Set <var title="">node</var> to <var title="">node</var>'s
 first child if
 <var title="">type</var> is first, and <var title="">node</var>'s
 last child if
 <var title="">type</var> is last.

<dfn id="concept-traverse-children-main" title="concept-traverse-children-main">Main</dfn>:
  While <var title="">node</var> is not null, run these substeps:

Filter
   <var title="">node</var> and let <var title="">result</var> be the return
   value.

If <var title="">result</var> is
   FILTER_ACCEPT, then set
   the currentNode
   attribute to <var title="">node</var> and return <var title="">node</var>.

If <var title="">result</var> is
    FILTER_SKIP, run these
    subsubsteps:

Let <var title="">child</var> be <var title="">node</var>'s
     first child if
     <var title="">type</var> is first, and <var title="">node</var>'s
     last child if
     <var title="">type</var> is last.

If <var title="">child</var> is not null, set <var title="">node</var>
     to <var title="">child</var> and goto
     Main.

While <var title="">node</var> is not null, run these subsubsteps:

Let <var title="">sibling</var> be <var title="">node</var>'s
     next sibling if
     <var title="">type</var> is first, and <var title="">node</var>'s
     previous sibling if
     <var title="">type</var> is last.

If <var title="">sibling</var> is not null, set
     <var title="">node</var> to <var title="">sibling</var> and goto
     Main.

Let <var title="">parent</var> be <var title="">node</var>'s
     parent.

If <var title="">parent</var> is null, <var title="">parent</var> is
     root, or
     <var title="">parent</var> is
     currentNode attribute's
     value, return null.

Otherwise, set <var title="">node</var> to <var title="">parent</var>.

Return null.

The <dfn id="dom-treewalker-firstchild" title="dom-TreeWalker-firstChild">firstChild()</dfn>
method must traverse children
of type first.

The <dfn id="dom-treewalker-lastchild" title="dom-TreeWalker-lastChild">lastChild()</dfn>
method must traverse children
of type last.

To <dfn id="concept-traverse-siblings" title="concept-traverse-siblings">traverse siblings</dfn> of type
<var title="">type</var> run these steps:

Let <var title="">node</var> be the value of the
 currentNode attribute.

If <var title="">node</var> is
 root, return null.

Run these substeps:

Let <var title="">sibling</var> be <var title="">node</var>'s
   next sibling if
   <var title="">type</var> is next, and <var title="">node</var>'s
   previous sibling if
   <var title="">type</var> is previous.

While <var title="">sibling</var> is not null, run these subsubsteps:

Set <var title="">node</var> to <var title="">sibling</var>.

Filter
     <var title="">node</var> and let <var title="">result</var> be the return
     value.

If <var title="">result</var> is
     FILTER_ACCEPT, then set
     the currentNode
     attribute to <var title="">node</var> and return <var title="">node</var>.

Set <var title="">sibling</var> to <var title="">node</var>'s
     first child if
     <var title="">type</var> is next, and <var title="">node</var>'s
     last child if
     <var title="">type</var> is previous.

If <var title="">result</var> is
     FILTER_REJECT or
     <var title="">sibling</var> is null, then set <var title="">sibling</var> to
     <var title="">node</var>'s
     next sibling if
     <var title="">type</var> is next, and <var title="">node</var>'s
     previous sibling if
     <var title="">type</var> is previous.

Set <var title="">node</var> to its
   parent.

If <var title="">node</var> is null or is
   root, return null.

Filter
   <var title="">node</var> and if the return value is
   FILTER_ACCEPT, then
   return null.

Run these substeps again.

The
<dfn id="dom-treewalker-nextsibling" title="dom-TreeWalker-nextSibling">nextSibling()</dfn>
method must traverse siblings
of type next.

The
<dfn id="dom-treewalker-previoussibling" title="dom-TreeWalker-previousSibling">previousSibling()</dfn>
method must traverse siblings
of type previous.

The
<dfn id="dom-treewalker-previousnode" title="dom-TreeWalker-previousNode">previousNode()</dfn>
method must run these steps:

Let <var title="">node</var> be the value of the
 currentNode attribute.

While <var title="">node</var> is not
  root, run these substeps:

Let <var title="">sibling</var> be the
   previous sibling of
   <var title="">node</var>.

While <var title="">sibling</var> is not null, run these subsubsteps:

Set <var title="">node</var> to <var title="">sibling</var>.

Filter
     <var title="">node</var> and let <var title="">result</var> be the return
     value.

While <var title="">result</var> is not
     FILTER_REJECT and
     <var title="">node</var> has a
     child, set <var title="">node</var>
     to its last child and then
     filter <var title="">node</var> and
     set <var title="">result</var> to the return value.

If <var title="">result</var> is
     FILTER_ACCEPT, then set
     the currentNode
     attribute to <var title="">node</var> and return <var title="">node</var>.

Set <var title="">sibling</var> to the
     previous sibling of
     <var title="">node</var>.

If <var title="">node</var> is
   root or <var title="">node</var>'s
   parent is null, return null.

Set <var title="">node</var> to its
   parent.

Filter
   <var title="">node</var> and if the return value is
   FILTER_ACCEPT, then set
   the currentNode attribute
   to <var title="">node</var> and return <var title="">node</var>.

Return null.

The <dfn id="dom-treewalker-nextnode" title="dom-TreeWalker-nextNode">nextNode()</dfn>
method must run these steps:

Let <var title="">node</var> be the value of the
 currentNode attribute.

Let <var title="">result</var> be
 FILTER_ACCEPT.

Run these substeps:

While <var title="">result</var> is not
    FILTER_REJECT and
    <var title="">node</var> has a child,
    run these subsubsteps:

Set <var title="">node</var> to its
     first child.

Filter
     <var title="">node</var> and set <var title="">result</var> to the return
     value.

If <var title="">result</var> is
     FILTER_ACCEPT, then set
     the currentNode attribute
     to <var title="">node</var> and return <var title="">node</var>.

If a node is
    following
    <var title="">node</var> and is not
    following
    root, set
    <var title="">node</var> to the first such
    node.

Otherwise, return null.

Filter
   <var title="">node</var> and set <var title="">result</var> to the return
   value.

If <var title="">result</var> is
   FILTER_ACCEPT, then set
   the currentNode attribute
   to <var title="">node</var> and return <var title="">node</var>.

Run these substeps again.

7.3 Interface NodeFilter

callback interface <dfn id="nodefilter">NodeFilter</dfn> {
  // Constants for acceptNode()
  const unsigned short FILTER_ACCEPT = 1;
  const unsigned short FILTER_REJECT = 2;
  const unsigned short FILTER_SKIP = 3;

  // Constants for whatToShow
  const unsigned long SHOW_ALL = 0xFFFFFFFF;
  const unsigned long SHOW_ELEMENT = 0x1;
  const unsigned long SHOW_ATTRIBUTE = 0x2; // historical
  const unsigned long SHOW_TEXT = 0x4;
  const unsigned long SHOW_CDATA_SECTION = 0x8; // historical
  const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // historical
  const unsigned long SHOW_ENTITY = 0x20; // historical
  const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40;
  const unsigned long SHOW_COMMENT = 0x80;
  const unsigned long SHOW_DOCUMENT = 0x100;
  const unsigned long SHOW_DOCUMENT_TYPE = 0x200;
  const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400;
  const unsigned long SHOW_NOTATION = 0x800; // historical

  unsigned short acceptNode(Node <var title="">node</var>);
};

NodeFilter objects can be used as
filter callback and provide
constants for the whatToShow
bitmask.

It is typically implemented as an JavaScript function.

These constants can be used as callback return value:

<dfn id="dom-nodefilter-filter_accept" title="dom-NodeFilter-FILTER_ACCEPT">FILTER_ACCEPT</dfn> (1);

<dfn id="dom-nodefilter-filter_reject" title="dom-NodeFilter-FILTER_REJECT">FILTER_REJECT</dfn> (2);

<dfn id="dom-nodefilter-filter_skip" title="dom-NodeFilter-FILTER_SKIP">FILTER_SKIP</dfn> (3).

These constants can be used for the
whatToShow bitmask:

<dfn id="dom-nodefilter-show_all" title="dom-NodeFilter-SHOW_ALL">SHOW_ALL</dfn> (4294967295, FFFFFFFF in hexadecimal);

<dfn id="dom-nodefilter-show_element" title="dom-NodeFilter-SHOW_ELEMENT">SHOW_ELEMENT</dfn> (1);

<dfn id="dom-nodefilter-show_text" title="dom-NodeFilter-SHOW_TEXT">SHOW_TEXT</dfn> (4);

<dfn id="dom-nodefilter-show_processing_instruction" title="dom-NodeFilter-SHOW_PROCESSING_INSTRUCTION">SHOW_PROCESSING_INSTRUCTION</dfn> (64, 40 in hexadecimal);

<dfn id="dom-nodefilter-show_comment" title="dom-NodeFilter-SHOW_COMMENT">SHOW_COMMENT</dfn> (128, 80 in hexadecimal);

<dfn id="dom-nodefilter-show_document" title="dom-NodeFilter-SHOW_DOCUMENT">SHOW_DOCUMENT</dfn> (256, 100 in hexadecimal);

<dfn id="dom-nodefilter-show_document_type" title="dom-NodeFilter-SHOW_DOCUMENT_TYPE">SHOW_DOCUMENT_TYPE</dfn> (512, 200 in hexadecimal);

<dfn id="dom-nodefilter-show_document_fragment" title="dom-NodeFilter-SHOW_DOCUMENT_FRAGMENT">SHOW_DOCUMENT_FRAGMENT</dfn> (1024, 400 in hexadecimal).

8 Sets

Yes, the names DOMTokenList and
DOMSettableTokenList are unfortunate legacy mishaps.

8.1 Interface DOMTokenList

interface <dfn id="domtokenlist">DOMTokenList</dfn> {
  readonly attribute unsigned long length;
  getter DOMString? item(unsigned long <var title="">index</var>);
  boolean contains(DOMString <var title="">token</var>);
  void add(DOMString... <var title="">tokens</var>);
  void remove(DOMString... <var title="">tokens</var>);
  boolean toggle(DOMString <var title="">token</var>, optional boolean <var title="">force</var>);
  stringifier;
};

A DOMTokenList object has an associated ordered set of
<dfn id="concept-dtl-tokens" title="concept-DTL-tokens">tokens</dfn>, which is initially empty.

A DOMTokenList object also has an associated
element and an
attribute's
local name.

A DOMTokenList object's
<dfn id="concept-dtl-update" title="concept-DTL-update">update steps</dfn> are:

If there is no associated
 attribute (when the object is a
 DOMSettableTokenList), terminate these steps.

Set an attribute
 for the associated element using
 associated attribute's
 local name and the result
 of running the ordered set serializer
 for tokens.

<var title="">tokenlist</var> . length

Returns the number of tokens.

<var title="">tokenlist</var> . item(<var title="">index</var>)

<var title="">tokenlist</var>[<var title="">index</var>]

Returns the token with index <var title="">index</var>.

<var title="">tokenlist</var> . contains(<var title="">token</var>)

Returns true if <var title="">token</var> is present, and false otherwise.

Throws a "SyntaxError" exception if <var title="">token</var>
  is the empty string.

Throws an "InvalidCharacterError" exception if
  <var title="">token</var> contains any
  ASCII whitespace.

<var title="">tokenlist</var> . add(<var title="">tokens</var>…)

Adds all arguments passed, except those already present.

Throws a "SyntaxError" exception if one if the arguments
  is the empty string.

Throws an "InvalidCharacterError" exception if one of the
  arguments contains any
  ASCII whitespace.

<var title="">tokenlist</var> . remove(<var title="">tokens</var>…)

Removes arguments passed, if they are present.

Throws a "SyntaxError" exception if one if the arguments
  is the empty string.

Throws an "InvalidCharacterError" exception if one of the
  arguments contains any
  ASCII whitespace.

<var title="">tokenlist</var> . toggle(<var title="">token</var> [, <var title="">force</var>])

If <var title="">force</var> is not given, "toggles"
  <var title="">token</var>, removing it if it's present and adding it if it's
  not. If <var title="">force</var> is true, adds <var title="">token</var> (same
  as add()).  If
  <var title="">force</var> is false, removes <var title="">token</var> (same as
  remove()).

Returns true if <var title="">token</var> is now present, and false
  otherwise.

Throws a "SyntaxError" exception if <var title="">token</var> is empty.

Throws an "InvalidCharacterError" exception if <var title="">token</var> contains any spaces.

The <dfn id="dom-domtokenlist-length" title="dom-DOMTokenList-length">length</dfn>
attribute must return the number of tokens in the
tokens.

The object's
supported property indices are the
numbers in the range zero to the number of tokens in
tokens minus one, unless
tokens is  empty, in which case there are no
supported property indices.

The
<dfn id="dom-domtokenlist-item" title="dom-DOMTokenList-item">item(<var title="">index</var>)</dfn>
method must run these steps:

If <var title="">index</var> is equal to or greater than the number of
 tokens in tokens, return null.

Return the <var title="">index</var>th token in
 tokens.

The
<dfn id="dom-domtokenlist-contains" title="dom-DOMTokenList-contains">contains(<var title="">token</var>)</dfn>
method must run these steps:

If <var title="">token</var> is the empty string, then
 throw a "SyntaxError"
 exception.

If <var title="">token</var> contains any
 ASCII whitespace, then
 throw
 an "InvalidCharacterError" exception.

Return true if <var title="">token</var> is in
 tokens, and false otherwise.

The
<dfn id="dom-domtokenlist-add" title="dom-DOMTokenList-add">add(<var title="">tokens</var>…)</dfn>
method must run these steps:

If one of <var title="">tokens</var> is the empty string,
 throw a "SyntaxError"
 exception.

If one of <var title="">tokens</var> contains any
 ASCII whitespace, then
 throw an
 "InvalidCharacterError" exception.

For each <var title="">token</var> in <var title="">tokens</var>, in given
 order, that is not in tokens, append
 <var title="">token</var> to tokens.

Run the update steps.

The
<dfn id="dom-domtokenlist-remove" title="dom-DOMTokenList-remove">remove(<var title="">tokens</var>…)</dfn>
method must run these steps:

If one of <var title="">tokens</var> is the empty string,
 throw a "SyntaxError"
 exception.

If one of <var title="">tokens</var> contains any
 ASCII whitespace, then
 throw an
 "InvalidCharacterError" exception.

For each <var title="">token</var> in <var title="">tokens</var>, remove
 <var title="">token</var> from tokens.

Run the update steps.

The
<dfn id="dom-domtokenlist-toggle" title="dom-DOMTokenList-toggle">toggle(<var title="">token</var>, <var title="">force</var>)</dfn>
method must run these steps:

If <var title="">token</var> is the empty string,
 throw a "SyntaxError"
 exception.

If <var title="">token</var> contains any
 ASCII whitespace,
 throw an
 "InvalidCharacterError" exception.

If <var title="">token</var> is in tokens, run
  these substeps:

If <var title="">force</var> is either not passed or is false, then remove
   <var title="">token</var> from tokens, run the
   update steps, and return false.

Otherwise, return true.

Otherwise, run these substeps:

If <var title="">force</var> is passed and is false, return false.

Otherwise, append <var title="">token</var> to
   tokens, run the
   update steps, and return true.

The <dfn id="dom-domtokenlist-stringifier" title="dom-DOMTokenList-stringifier">stringifier</dfn> must
return the result of the
ordered set serializer for
tokens.

8.2 Interface DOMSettableTokenList

interface <dfn id="domsettabletokenlist">DOMSettableTokenList</dfn> : DOMTokenList {
            attribute DOMString value;
};

A DOMSettableTokenList object is equivalent to a
DOMTokenList object without an associated
attribute.

<var title="">tokenlist</var> . value

Returns the associated set as string.

Can be set, to change the associated set via a string.

The <dfn id="dom-domsettabletokenlist-value" title="dom-DOMSettableTokenList-value">value</dfn>
attribute must return the result of the
ordered set serializer for
tokens.

Setting the value
attribute must run the ordered set parser
for the given value and set tokens to the result.

9 Historical

As explained in goals this specification is a
significant revision of various DOM specifications. This section attempts to
enumerate the changes.

9.1 DOM Events

These are the changes made to the features described in the
"DOM Event Architecture", "Basic Event Interfaces", "Mutation Events", and
"Mutation Name Event Types" chapters of DOM Level 3 Events. The
other chapters are defined by the UI Events specification.
[DOM3EVENTS]
[UIEVENTS]

Events have constructors now.

Removes <dfn id="mutationevent">MutationEvent</dfn>, and
 <dfn id="mutationnameevent">MutationNameEvent</dfn>.

Fire is no longer synonymous with dispatch, but includes initializing
 an event.

The propagation and canceled flags are unset when invoking
 initEvent() rather than after
 dispatch.

9.2 DOM Core

These are the changes made to the features described in
DOM Level 3 Core.

<dfn id="domstring">DOMString</dfn> and
<dfn id="domtimestamp">DOMTimeStamp</dfn> are now defined in Web IDL.

Node now inherits from EventTarget.

Nodes are implicitly
adopted across
document boundaries.

Doctypes now always have a
node document and can be moved
across document boundaries.

ProcessingInstruction now inherits from
CharacterData.

DOMError is completely redesigned.

The remainder of interfaces and interface members listed in this section
were removed to simplify the DOM platform. Implementations conforming to
this specification will not support them.

It is not yet clear if it would be web-compatible to
remove all the following features. The editors welcome any data showing that
some of these features should be reintroduced.

Interfaces:

<dfn id="cdatasection">CDATASection</dfn>

<dfn id="domconfiguration">DOMConfiguration</dfn>

<dfn id="domerrorhandler">DOMErrorHandler</dfn>

<dfn id="domimplementationlist">DOMImplementationList</dfn>

<dfn id="domimplementationsource">DOMImplementationSource</dfn>

<dfn id="domlocator">DOMLocator</dfn>

<dfn id="domobject">DOMObject</dfn>

<dfn id="domstringlist">DOMStringList</dfn>

<dfn id="domuserdata">DOMUserData</dfn>

<dfn id="entity">Entity</dfn>

<dfn id="entityreference">EntityReference</dfn>

<dfn id="namednodemap">NamedNodeMap</dfn>

<dfn id="namelist">NameList</dfn>

<dfn id="notation">Notation</dfn>

<dfn id="typeinfo">TypeInfo</dfn>

<dfn id="userdatahandler">UserDataHandler</dfn>

Interface members:

Node

<dfn id="dom-node-hasattributes" title="dom-Node-hasAttributes">hasAttributes()</dfn>

<dfn id="dom-node-attributes" title="dom-Node-attributes">attributes</dfn>

<dfn id="dom-node-namespaceuri" title="dom-Node-namespaceURI">namespaceURI</dfn>

<dfn id="dom-node-prefix" title="dom-Node-prefix">prefix</dfn>

<dfn id="dom-node-localname" title="dom-Node-localName">localName</dfn>

<dfn id="dom-node-issupported" title="dom-Node-isSupported">isSupported</dfn>

<dfn id="dom-node-getfeature" title="dom-Node-getFeature">getFeature()</dfn>

<dfn id="dom-node-getuserdata" title="dom-Node-getUserData">getUserData()</dfn>

<dfn id="dom-node-setuserdata" title="dom-Node-setUserData">setUserData()</dfn>

<dfn id="dom-node-issamenode" title="dom-Node-isSameNode">isSameNode()</dfn>

Document

<dfn id="dom-document-createcdatasection" title="dom-Document-createCDATASection">createCDATASection()</dfn>

<dfn id="dom-document-createattribute" title="dom-Document-createAttribute">createAttribute()</dfn>

<dfn id="dom-document-createattributens" title="dom-Document-createAttributeNS">createAttributeNS()</dfn>

<dfn id="dom-document-createentityreference" title="dom-Document-createEntityReference">createEntityReference()</dfn>

<dfn id="dom-document-inputencoding" title="dom-Document-inputEncoding">inputEncoding</dfn>

<dfn id="dom-document-xmlencoding" title="dom-Document-xmlEncoding">xmlEncoding</dfn>

<dfn id="dom-document-xmlstandalone" title="dom-Document-xmlStandalone">xmlStandalone</dfn>

<dfn id="dom-document-xmlversion" title="dom-Document-xmlVersion">xmlVersion</dfn>

<dfn id="dom-document-stricterrorchecking" title="dom-Document-strictErrorChecking">strictErrorChecking</dfn>

<dfn id="dom-document-domconfig" title="dom-Document-domConfig">domConfig</dfn>

<dfn id="dom-document-normalizedocument" title="dom-Document-normalizeDocument">normalizeDocument()</dfn>

<dfn id="dom-document-renamenode" title="dom-Document-renameNode">renameNode()</dfn>

DOMImplementation

<dfn id="dom-domimplementation-getfeature" title="dom-DOMImplementation-getFeature">getFeature()</dfn>

Attr

No longer inherits from Node and therefore completely
  changed.

Element

<dfn id="dom-element-getattributenode" title="dom-Element-getAttributeNode">getAttributeNode()</dfn>

<dfn id="dom-element-getattributenodens" title="dom-Element-getAttributeNodeNS">getAttributeNodeNS()</dfn>

<dfn id="dom-element-setattributenode" title="dom-Element-setAttributeNode">setAttributeNode()</dfn>

<dfn id="dom-element-removeattributenode" title="dom-Element-removeAttributeNode">removeAttributeNode()</dfn>

<dfn id="dom-element-schematypeinfo" title="dom-Element-schemaTypeInfo">schemaTypeInfo</dfn>

<dfn id="dom-element-setidattribute" title="dom-Element-setIdAttribute">setIdAttribute()</dfn>

<dfn id="dom-element-setidattributens" title="dom-Element-setIdAttributeNS">setIdAttributeNS()</dfn>

<dfn id="dom-element-setidattributenode" title="dom-Element-setIdAttributeNode">setIdAttributeNode()</dfn>

DocumentType

<dfn id="dom-documenttype-entities" title="dom-DocumentType-entities">entities</dfn>

<dfn id="dom-documenttype-notations" title="dom-DocumentType-notations">notations</dfn>

<dfn id="dom-documenttype-internalsubset" title="dom-DocumentType-internalSubset">internalSubset</dfn>

Text

<dfn id="dom-text-iselementcontentwhitespace" title="dom-Text-isElementContentWhitespace">isElementContentWhitespace</dfn>

<dfn id="dom-text-replacewholetext" title="dom-Text-replaceWholeText">replaceWholeText()</dfn>

9.3 DOM Ranges

These are the changes made to the features described in the
"Document Object Model Range" chapter of
DOM Level 2 Traversal and Range.

<dfn id="rangeexception">RangeException</dfn> has been removed.

Range objects can now be moved between
 documents and used on
 nodes that are not in a document.

A wild Range() constructor appeared.

New methods comparePoint(),
 intersectsNode(), and
 isPointInRange() have been added.

detach() is now a no-op.

<dfn id="dom-range-tostring" title="dom-Range-toString">toString()</dfn> is now defined through
 IDL.

9.4 DOM Traversal

These are the changes made to the features described in the
"Document Object Model Traversal" chapter of
DOM Level 2 Traversal and Range.

createNodeIterator() and
 createTreeWalker() now have optional
 arguments and lack a fourth argument which is no longer relevant given entity references
 never made it into the DOM.

The expandEntityReferences attribute has been removed from the
 NodeIterator and TreeWalker interfaces for the aforementioned
 reason.

The referenceNode and
 pointerBeforeReferenceNode
 attributes have been added to NodeIterator objects to align with proprietary
 extensions of implementations.

nextNode() and
 previousNode() now throw
 when invoked from a NodeFilter to align with user agents.

detach() is now a no-op.

References

[CSSOMVIEW]

(Non-normative)

Document Object Model (DOM) Level 2 Style, C. Wilson, P. Le Hégaret, V. Apparao. W3C.

CSSOM View Module, S. Pieters, G. Adams. W3C.

[DOM2TR]

(Non-normative) Document Object Model (DOM) Level 2 Traversal and Range Specification, Joe Kesselman, Jonathan Robie, Mike Champion et al.. W3C.

[DOM3CORE]

(Non-normative) Document Object Model (DOM) Level 3 Core Specification, Arnaud Le Hors, Philippe Le Hégaret, Lauren Wood et al.. W3C.

[DOM3EVENTS]

(Non-normative) Document Object Model (DOM) Level 3 Events Specification, Travis Leithead. W3C.

[DOMPS]

(Non-normative) DOM Parsing and Serialization, T. Leithead. Work in Progress. W3C.

[ELEMENTTRAVERSAL]

(Non-normative) Element Traversal Specification, Doug Schepers. W3C.

[ENCODING]

Encoding, A. van Kesteren, J. Bell, A. Phillips. W3C.

[HTML]

   HTML5,
   R. Berjon, T. Leithead, E. Doyle Navara, E. O'Connor, S. Pfeiffer. W3C.

[ORIGIN]

The Web Origin Concept, Adam Barth. IETF.

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.

[SELECTORS]

Selectors, E. Etemad, T. Atkins. W3C.

[SELECTORSAPI]

(Non-normative) Selectors API Level 2, Lachlan Hunt. W3C.

[UIEVENTS]

UI Events, Gary Kacmarcik and Travis Leithead. W3C.

[URL]

URL, Anne van Kesteren. WHATWG.

RFC3986, T. Berners-Lee; R. Fielding; L. Masinter. IETF.

[WEBIDL]

Web IDL, Cameron McCormack. W3C.

[XML]

Extensible Markup Language, Tim Bray, Jean Paoli, C. M. Sperberg-McQueen et al.. W3C.

[XMLNS]

Namespaces in XML, Tim Bray, Dave Hollander, Andrew Layman et al.. W3C.

Acknowledgments

Thanks to

Adam Klein,
Adrian Bateman,
Alex Russell,
Arkadiusz Michalski,
Arun Ranganathan,
Jake Archibald,
Boris Zbarsky,
Brandon Slade,
Brandon Wallace,
Brian Kardell,
Cameron McCormack,
Christophe Dumez,
Daniel Glazman,
David Bruant,
David Flanagan,
David Håsäther,
Dethe Elza,
Dimitri Glazkov,
Domenic Denicola,
Dominic Cooney,
Dominique Hazaël-Massieux,
Erik Arvidsson,
Glenn Maynard,
Harald Alvestrand,
Henri Sivonen,
Igor Bukanov,
Jacob Rossi,
Jake Verbaten,
James Graham,
James Robinson,
Jens Lindström,
João Eiras,
Jonas Sicking,
Joshua Bell,
Justin Summerlin,
呂康豪 (Kang-Hao Lu),
Kevin Sweeney,
Manish Goregaokar,
Manish Tripathi,
Marcos Caceres,
Mark Miller,
Mats Palmgren,
Mounir Lamouri,
Michael™ Smith,
Ojan Vafai,
Olli Pettay,
Ondřej Žára,
Philip Jägenstedt,
Rafael Weinstein,
Rick Waldron,
Robbert Broersma,
Robin Berjon,
Rune F. Halvorsen,
Ryosuke Niwa,
Seo Sanghyeon,
Shiki Okasaka,
Stig Halvorsen,
Tab Atkins,
Timo Tijhof,
Travis Leithead,
Yehuda Katz, and
Zack Weinberg

for their useful comments.

Special thanks to Geoffrey Sneddon and Simon Pieters for first specifying the Nodes section 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: Arnaud Le Hors,
Björn Höhrmann, Doug Schepers, Gavin Nicol, Joe Kesselman, Jonathan Robie,
Lachlan Hunt, Lauren Wood, Mike Champion, Peter Sharpe, Philippe Le Hégaret, Robin Berjon,
Steve Byrne, Tom Pixley, and Vidur Apparao.