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.
DOM defines a platform-neutral model for events and node trees.
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.
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:
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.
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.
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]
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 applicable specification for the purposes of conformance requirements in this specification.
The term context object 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.
A tree is a finite hierarchical tree structure. In tree order is preorder, depth-first traversal of a tree.
An object that participates in a tree has a parent, which is either another object or null, and an ordered list of zero or more child objects. An object A whose parent is object B is a child of B.
The root of an object is itself, if its parent is null, or else it is the root of its parent.
An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.
An inclusive descendant is an object or one of its descendants.
An object A is called an ancestor of an object B if and only if B is a descendant of A.
An inclusive ancestor is an object or one of its ancestors.
An object A is called a sibling of an object B, if and only if B and A share the same non-null parent.
An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order.
An object A is following an object B if A and B are in the same tree and A comes after B in tree order.
The first child of an object is its first child or null if it has no child.
The last child of an object is its last child or null if it has no child.
The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling.
The next sibling of an object is its first following sibling or null if it has no following sibling.
The index of an object is its number of preceding siblings.
Comparing two strings in a case-sensitive manner means comparing them exactly, code point for code point.
Comparing two strings in a ASCII case-insensitive 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.
Converting a string to ASCII uppercase 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).
Converting a string to ASCII lowercase 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 pattern is a prefix match for a string s when pattern is not longer than s and truncating s to pattern's length leaves the two strings as matches of each other.
The ordered set parser takes a string input and then runs these steps:
Let position be a pointer into input, initially pointing at the start of the string.
Let tokens be an ordered set of tokens, initially empty.
While position is not past the end of input:
Collect a code point sequence of code points that are not ASCII whitespace.
If the collected string is not in tokens, append the collected string to tokens.
Return tokens.
To collect a code point sequence of code points, run these steps:
Let input and position be the same variables as those of the same name in the algorithm that invoked these steps.
Let result be the empty string.
While position does not point past the end of input and the code point at position is one of code points, append that code point to the end of result and advance position to the next code point in input.
Return result.
To skip ASCII whitespace means to collect a code point sequence of ASCII whitespace and discard the return value.
The ordered set serializer takes a set and returns the concatenation of the strings in set, separated from each other by U+0020.
The HTML namespace is
http://www.w3.org/1999/xhtml.
The XML namespace is
http://www.w3.org/XML/1998/namespace.
The XMLNS namespace is
http://www.w3.org/2000/xmlns/.
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.
DOMExceptionexception DOMException {
const unsigned short INDEX_SIZE_ERR = 1;
const unsigned short DOMSTRING_SIZE_ERR = 2; // historical
const unsigned short HIERARCHY_REQUEST_ERR = 3;
const unsigned short WRONG_DOCUMENT_ERR = 4;
const unsigned short INVALID_CHARACTER_ERR = 5;
const unsigned short NO_DATA_ALLOWED_ERR = 6; // historical
const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short NOT_FOUND_ERR = 8;
const unsigned short NOT_SUPPORTED_ERR = 9;
const unsigned short INUSE_ATTRIBUTE_ERR = 10; // historical
const unsigned short INVALID_STATE_ERR = 11;
const unsigned short SYNTAX_ERR = 12;
const unsigned short INVALID_MODIFICATION_ERR = 13;
const unsigned short NAMESPACE_ERR = 14;
const unsigned short INVALID_ACCESS_ERR = 15;
const unsigned short VALIDATION_ERR = 16; // historical
const unsigned short TYPE_MISMATCH_ERR = 17; // 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 code exception
field must return the value it was initialized to.
To throw a name exception run these steps:
Let code be zero.
If name is in the first column of the
error names table and has a corresponding legacy
code exception field value in the
third column, set code to that value.
Throw a new
DOMException exception, whose
message is a user agent-defined value,
name is name, and
whose code exception field is
code.
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".
DOMError[Constructor(DOMString name, optional DOMString message = "")]
interface DOMError {
readonly attribute DOMString name;
readonly attribute DOMString message;
};
DOMError will be nuked. Replace your usage with
DOMException now.
The DOMError(name, message)
constructor must return a new DOMError object whose
name attribute is initialized to
name and whose message attribute
is initialized to message.
The name attribute must
return the value it was initialized to.
The message 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
name DOMError
means a DOMError object whose
name attribute is initialized to
name 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.
The error names table 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!
| Name | Description | Legacy code exception field value (if any)
|
|---|---|---|
"IndexSizeError"
| The index is not in the allowed range. | INDEX_SIZE_ERR (1)
|
"HierarchyRequestError"
| The operation would yield an incorrect node tree. | HIERARCHY_REQUEST_ERR (3)
|
"WrongDocumentError"
| The object is in the wrong document. | WRONG_DOCUMENT_ERR (4)
|
"InvalidCharacterError"
| The string contains invalid characters. | INVALID_CHARACTER_ERR (5)
|
"NoModificationAllowedError"
| The object can not be modified. | NO_MODIFICATION_ALLOWED_ERR (7)
|
"NotFoundError"
| The object can not be found here. | NOT_FOUND_ERR (8)
|
"NotSupportedError"
| The operation is not supported. | NOT_SUPPORTED_ERR (9)
|
"InvalidStateError"
| The object is in an invalid state. | INVALID_STATE_ERR (11)
|
"SyntaxError"
| The string did not match the expected pattern. | SYNTAX_ERR (12)
|
"InvalidModificationError"
| The object can not be modified in this way. | INVALID_MODIFICATION_ERR (13)
|
"NamespaceError"
| The operation is not allowed by Namespaces in XML. [XMLNS] | NAMESPACE_ERR (14)
|
"InvalidAccessError"
| The object does not support the operation or argument. | INVALID_ACCESS_ERR (15)
|
"SecurityError"
| The operation is insecure. | SECURITY_ERR (18)
|
"NetworkError"
| A network error occurred. | NETWORK_ERR (19)
|
"AbortError"
| The operation was aborted. | ABORT_ERR (20)
|
"URLMismatchError"
| The given URL does not match another URL. | URL_MISMATCH_ERR (21)
|
"QuotaExceededError"
| The quota has been exceeded. | QUOTA_EXCEEDED_ERR (22)
|
"TimeoutError"
| The operation timed out. | TIMEOUT_ERR (23)
|
"InvalidNodeTypeError"
| The supplied node is incorrect or has an incorrect ancestor for this operation. | INVALID_NODE_TYPE_ERR (24)
|
"DataCloneError"
| The object can not be cloned. | DATA_CLONE_ERR (25)
|
"EncodingError"
| The encoding operation (either encoded or decoding) failed. | — |
"NotReadableError"
| The I/O read operation failed. | — |
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
ev 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 (obj
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.
Event[Constructor(DOMString type, optional EventInit eventInitDict),
Exposed=Window,Worker]
interface Event {
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 type, boolean bubbles, boolean cancelable);
};
dictionary EventInit {
boolean bubbles = false;
boolean cancelable = false;
};
An event 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.
event = new Event(type [, eventInitDict])
Returns a new event whose
type attribute value is set to
type. The optional eventInitDict argument
allows for setting the bubbles and
cancelable attributes via object
members of the same name.
event . type
Returns the type of event, e.g.
"click", "hashchange", or
"submit".
event . target
Returns the object event is dispatched to.
event . currentTarget
Returns the object whose event listener's callback is invoked.
event . eventPhase
Returns the event's phase, which is
one of NONE,
CAPTURING_PHASE,
AT_TARGET, and
BUBBLING_PHASE.
event . stopPropagation()
When dispatched in a tree, invoking this method prevents event from reaching any other objects than the current.
event . stopImmediatePropagation()
Invoking this method prevents event from reaching any event listeners registered after the current one and when dispatched in a tree also prevents event from reaching any other objects.
event . bubbles
Returns true if event's goes through its target attribute value's ancestors in reverse tree order, and false otherwise.
event . cancelable
Returns true or false depending on how event was
initialized. Its return value does not always carry meaning, but true can
indicate that part of the operation during which event was
dispatched, can be canceled by
invoking the preventDefault()
method.
event . preventDefault()
If invoked when the
cancelable attribute value is true,
signals to the operation that caused event to be
dispatched that it needs to be
canceled.
event . defaultPrevented
Returns true if
preventDefault() was invoked
while the cancelable attribute
value is true, and false otherwise.
event . isTrusted
Returns true if event was dispatched by the user agent, and false otherwise.
event . timeStamp
Returns the creation time of event in the number of milliseconds that passed since 00:00:00 UTC on 1 January 1970.
The type attribute must
return the value it was initialized to. When an
event is created the attribute must be
initialized to the empty string.
The target and
currentTarget
attributes must return the values they were initialized to. When an
event is created the attributes must be
initialized to null.
The eventPhase
attribute must return the value it was initialized to, which must be one of
the following:
NONE (numeric value 0)
Events not currently dispatched are in this phase.
CAPTURING_PHASE (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.
AT_TARGET (numeric value 2)
When an event is
dispatched it will be in this
phase on its target attribute value.
BUBBLING_PHASE (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:
The
stopPropagation()
method must set the stop propagation flag.
The
stopImmediatePropagation()
method must set both the stop propagation flag and
stop immediate propagation flag.
The bubbles and
cancelable 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
preventDefault()
method must set the canceled flag if the
cancelable attribute value is true.
The
defaultPrevented
attribute must return true if the canceled flag is set and
false otherwise.
The isTrusted attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to false.
The timeStamp 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 initialize an event, with type, bubbles, and cancelable, 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
type.
Set the bubbles attribute to
bubbles.
Set the cancelable attribute
to cancelable.
The
initEvent(type, bubbles, cancelable)
method must initialize the
context object with type,
bubbles, and cancelable.
As events have constructors
initEvent() is superfluous. However,
it has to be supported for legacy content.
CustomEvent[Constructor(DOMString type, optional CustomEventInit eventInitDict),
Exposed=Window,Worker]
interface CustomEvent : Event {
readonly attribute any detail;
void initCustomEvent(DOMString type, boolean bubbles, boolean cancelable, any detail);
};
dictionary CustomEventInit : EventInit {
any detail = null;
};
Events using the
CustomEvent interface can be used to carry custom data.
event = new CustomEvent(type [, eventInitDict])
Works analogously to the constructor for Event except
that the optional eventInitDict argument now
allows for setting the detail attribute
too.
event . detail
Returns any custom data event was created with. Typically used for synthetic events.
The detail 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
initCustomEvent(type, bubbles, cancelable, detail)
method must initialize the
context object with type,
bubbles, and cancelable, and then set its
detail attribute to
detail.
When a constructor 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 type argument.
If there is an eventInitDict 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.
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*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.
EventTarget[Exposed=Window,Worker]
interface EventTarget {
void addEventListener(DOMString type, EventListener? callback, optional boolean capture = false);
void removeEventListener(DOMString type, EventListener? callback, optional boolean capture = false);
boolean dispatchEvent(Event event);
};
callback interface EventListener {
void handleEvent(Event event);
};
EventTarget is an object to which an
event is
dispatched when something has
occurred. Each EventTarget has an associated list of
event listeners.
An event listener 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.
target . addEventListener(type, callback [, capture = false])
Appends an event listener
for events whose
type attribute value is
type. The callback argument sets the
callback that will be invoked when the
event is
dispatched. When set to true,
the capture 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 target's list of event listeners and is not appended if it is a duplicate (the event listeners in the list are unique).
target . removeEventListener(type, callback [, capture = false])
Remove the event listener in target's list of event listeners with the same type, callback, and capture.
target . dispatchEvent(event)
Dispatches a synthetic
event event to target and returns true
if either event's
cancelable attribute value is false
or it's preventDefault() method
was not invoked, and false otherwise.
The
addEventListener(type, callback, capture)
method must run these steps:
If callback is null, terminate these steps.
Append an event listener to the associated list of event listeners with type set to type, callback set to callback, and capture set to capture, unless there already is an event listener in that list with the same type, callback, and capture.
The
removeEventListener(type, callback, capture)
method must run these steps:
Remove an event listener from the associated list of event listeners, whose type is name, callback is callback, and capture is capture.
The
dispatchEvent(event)
method must run these steps:
If event's dispatch flag is set, or if
its initialized flag is not set,
throw an
"InvalidStateError" exception.
Initialize event's
isTrusted attribute to false.
Dispatch the event and return the value that returns.
To dispatch an event to a given object, optionally with a target override, run these steps:
Let event be the event that is dispatched.
Set event's dispatch flag.
Initialize event's
target attribute to
target override, if it is given, or the object to which
event is dispatched otherwise.
If event's
target attribute value is
participating in a
tree, let event path be a
static ordered list of all its
ancestors in
tree order, and let
event path be the empty list otherwise.
Initialize event's
eventPhase attribute to
CAPTURING_PHASE.
For each object in event path, invoke its event listeners with event event, as long as event's stop propagation flag is unset.
Initialize event's
eventPhase attribute to
AT_TARGET.
Invoke the
event listeners of
event's target
attribute value with event, if event's
stop propagation flag is unset.
If event's
bubbles attribute value is true, run
these substeps:
Reverse the order of event path.
Initialize event's
eventPhase attribute to
BUBBLING_PHASE.
For each object in event path, invoke its event listeners, with event event as long as event's stop propagation flag is unset.
Unset event's dispatch flag.
Initialize event's
eventPhase attribute to
NONE.
Initialize event's
currentTarget attribute to null.
Return false if event's canceled flag is set, and true otherwise.
To invoke the event listeners for an object with an event run these steps:
Let event be the event for which the event listeners are invoked.
Let listeners be a copy of the event listeners associated with the object for which these steps are run.
Initialize event's
currentTarget attribute to the
object for which these steps are run.
Then run these substeps for each event listener in listeners:
If event's stop immediate propagation flag is set, terminate the invoke algorithm.
Let listener be the event listener.
If event's type
attribute value is not listener's type, terminate
these substeps (and run them for the next
event listener).
If event's
eventPhase attribute value is
CAPTURING_PHASE and
listener's capture is false, terminate these
substeps (and run them for the next
event listener).
If event's
eventPhase attribute value is
BUBBLING_PHASE and
listener's capture is true, terminate these
substeps (and run them for the next
event listener).
Call listener's callback's
handleEvent, with the event passed to
this algorithm as the first argument and event's
currentTarget attribute value as
callback this value.
To
fire an event named e
means that a new event using the
Event interface, with its
type attribute initialized to
e, 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".
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:
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.
Objects implementing the Document,
DocumentFragment, DocumentType,
Element, Text, ProcessingInstruction,
or Comment interface (simply called
nodes)
participate in a
tree, simply named the
node tree.
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 length of a node node depends on node:
DocumentType
Zero.
Text
ProcessingInstruction
Comment
Its length attribute
value.
Its number of children.
A node is considered empty if its length is zero.
At certain points in the algorithms below it is said that a node is inserted or a node is removed. 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 pre-insert a node into a parent before a child, run these steps:
If parent is not a Document,
DocumentFragment, or Element
node,
throw a
"HierarchyRequestError".
If node is a
host-including inclusive ancestor
of parent, throw a
"HierarchyRequestError".
If child is not null and its
parent is not
parent, throw a
"NotFoundError" exception.
If node is not a
DocumentFragment, DocumentType,
Element, Text,
ProcessingInstruction, or Comment
node,
throw a
"HierarchyRequestError".
If either node is a Text
node and parent is a
document, or node is a
doctype and parent is
not a document,
throw a
"HierarchyRequestError".
If parent is a
document, and any of the statements below, switched
on node, are true, throw a
"HierarchyRequestError".
DocumentFragment node
If node has more than one
element child
or has a Text node
child.
Otherwise, if node has one element child, and parent has an element child, child is a doctype, or child is not null and a doctype is following child.
parent has an element child, child is a doctype, or child is not null and a doctype is following child.
parent has a doctype child, an element is preceding child, or child is null and parent has an element child.
Let reference child be child.
If reference child is node, set it to node's next sibling.
Adopt node into parent's node document.
Insert node into parent before reference child.
Return node.
To insert a node into a parent before a child, optionally with a suppress observers flag, run these steps:
Let count be the number of
children of node if
it is a DocumentFragment node,
and one otherwise.
For each range whose start node is parent and start offset is greater than child's index, increase its start offset by count.
For each range whose end node is parent and end offset is greater than child's index, increase its end offset by count.
Let nodes be node's
children if node is
a DocumentFragment node, and a
list containing solely node otherwise.
If node is a DocumentFragment
node, queue a mutation record
of "childList" for node with removedNodes
nodes.
This step does intentionally not pay attention to the suppress observers flag.
If node 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
parent with addedNodes nodes,
nextSibling child, and previousSibling
child's
previous sibling
or parent's
last child if
child is null.
Insert all nodes in nodes before child or at the end of parent if child is null.
If suppress observers flag is unset, for each node in nodes, in tree order run node is inserted.
To append a node to a parent, pre-insert node into parent before null.
To replace a child with node within a parent, run these steps:
If parent is not a Document,
DocumentFragment, or Element
node,
throw a
"HierarchyRequestError".
If node is a
host-including inclusive ancestor
of parent, throw a
"HierarchyRequestError".
If child's
parent is not
parent, throw a
"NotFoundError" exception.
If node is not a
DocumentFragment, DocumentType,
Element, Text,
ProcessingInstruction, or Comment
node,
throw a
"HierarchyRequestError".
If either node is a Text
node and parent is a
document, or node is a
doctype and parent is
not a document,
throw a
"HierarchyRequestError".
If parent is a
document, and any of the statements below, switched
on node, are true, throw a
"HierarchyRequestError".
DocumentFragment node
If node has more than one
element child
or has a Text node
child.
Otherwise, if node has one element child and either parent has an element child that is not child or a doctype is following child.
parent has an element child that is not child or a doctype is following child.
The above statements differ from the pre-insert algorithm.
Let reference child be child's next sibling.
If reference child is node, set it to node's next sibling.
Adopt node into parent's node document.
Remove child from its parent with the suppress observers flag set.
Insert node into parent before reference child with the suppress observers flag set.
Let nodes be node's
children if node is
a DocumentFragment node, and a
list containing solely node otherwise.
Queue a mutation record of "childList" for
target parent with addedNodes
nodes, removedNodes a list solely containing
child, nextSibling reference child, and
previousSibling child's
previous sibling.
Run node is removed for child, and then for each node in nodes, in tree order, run node is inserted.
Return child.
To replace all with a node within a parent, run these steps:
If node is not null, adopt node into parent's node document.
Let removedNodes be parent's children.
Let addedNodes be the empty list if node is
null, node's children if
node is a DocumentFragment
node, and a list containing node
otherwise.
Remove all parent's children, with the suppress observers flag set.
If node is not null, insert node into parent before null with the suppress observers flag set.
Queue a mutation record of "childList" for
parent with addedNodes addedNodes and
removedNodes removedNodes.
Run node is removed for each node in removedNodes, in tree order, and then run node is inserted for each node in addedNodes, in tree order.
This algorithm does not make any checks with regards to the node tree constraints. Use it wisely.
To pre-remove a child from a parent, run these steps:
If child's
parent is not
parent, throw a
"NotFoundError" exception.
Remove child from parent.
Return child.
To remove a node from a parent, optionally with suppress observers flag set, run these steps:
Let index be node's index.
For each range whose start node is a descendant of node, set its start to (parent, index).
For each range whose end node is a descendant of node, set its end to (parent, index).
For each range whose start node is parent and start offset is greater than index, decrease its start offset by one.
For each range whose end node is parent and end offset is greater than index, decrease its end offset by one.
If suppress observers flag is unset,
queue a mutation record of "childList" for
parent with removedNodes a list solely containing
node, nextSibling node's
next sibling,
and previousSibling node's
previous sibling.
For each ancestor
ancestor of node, if
ancestor has any
registered observers whose
options's
subtree is true, then
for each such registered observer registered, append a
transient registered observer whose observer and
options are identical to those of registered and source
which is registered to node's list of
registered observers.
Remove node from its parent.
If suppress observers flag is unset, run node is removed for node.
NonElementParentNodeThe
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 NonElementParentNode {
Element? getElementById(DOMString elementId);
};
Document implements NonElementParentNode;
DocumentFragment implements NonElementParentNode;
node . getElementById(elementId)
Returns the first element within node's descendants whose ID is elementId.
The
getElementById(elementId)
method must return the first element, in
tree order, within context object's
descendants, whose
ID is elementId, and null if there is no
such element otherwise.
ParentNodeThe mutation method macro:
Let node be null.
Replace each string in nodes with a
Text node whose
data is the string value.
If nodes contains more than one
node, set node to a new
DocumentFragment and
append each
node in nodes to it. If
this throws an exception, re-throw the exception.
Otherwise, set node to the single node nodes contains.
[NoInterfaceObject]
interface ParentNode {
readonly attribute HTMLCollection children;
readonly attribute Element? firstElementChild;
readonly attribute Element? lastElementChild;
readonly attribute unsigned long childElementCount;
Element? querySelector(DOMString selectors);
[NewObject] NodeList querySelectorAll(DOMString selectors);
};
Document implements ParentNode;
DocumentFragment implements ParentNode;
Element implements ParentNode;
collection = node . children
element = node . firstElementChild
Returns the first child that is an element, and null otherwise.
element = node . lastElementChild
Returns the last child that is an element, and null otherwise.
node . querySelector(selectors)
Returns the first element that is a descendant of node that matches selectors.
node . querySelectorAll(selectors)
Returns all element descendants of node that match selectors.
The children
attribute must return an HTMLCollection
collection rooted at the
context object matching only
element
children.
The
firstElementChild
attribute must return the first child
that is an element, and null otherwise.
The
lastElementChild
attribute must return the last child
that is an element, and null otherwise.
The
childElementCount
attribute must return the number of
children of the
context object that are
elements.
To scope-match a selectors string selectors against a node, run these steps:
Let s be the result of parse a selector selectors. [SELECTORS]
If s is failure, throw a
JavaScript TypeError.
Return the result of evaluate a selector s against node's root using scoping root node and scoping method scope-filtered. [SELECTORS].
The
querySelector(selectors)
method must return the first result of running scope-match a selectors string
selectors against the context object, and null if the result
is an empty list otherwise.
The
querySelectorAll(selectors)
method must return the static result of
running scope-match a selectors string selectors against the
context object.
NonDocumentTypeChildNodeThe
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 NonDocumentTypeChildNode {
readonly attribute Element? previousElementSibling;
readonly attribute Element? nextElementSibling;
};
Element implements NonDocumentTypeChildNode;
CharacterData implements NonDocumentTypeChildNode;
element = node . previousElementSibling
Returns the first preceding sibling that is an element, and null otherwise.
element = node . nextElementSibling
Returns the first following sibling that is an element, and null otherwise.
The
previousElementSibling
attribute must return the first
preceding
sibling that is an
element, and null otherwise.
The
nextElementSibling
attribute must return the first
following
sibling that is an
element, and null otherwise.
ChildNode[NoInterfaceObject]
interface ChildNode {
void remove();
};
DocumentType implements ChildNode;
Element implements ChildNode;
CharacterData implements ChildNode;
node . remove()
Removes node.
The
remove()
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.
NodeList and HTMLCollectionA collection is an object that represents a lists of DOM nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.
If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.
When a collection is created, a filter and a root are associated with it.
The collection then represents a view of the subtree rooted at the collection's root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.
NodeListA NodeList object is a
collection of
nodes.
interface NodeList {
getter Node? item(unsigned long index);
readonly attribute unsigned long length;
};
length
Returns the number of nodes in the collection.
item(index)
Returns the node with index index 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 length attribute must
return the number of nodes represented by the collection.
The
item(index)
method must return the indexth
node in the collection. If there is no
indexth node in the collection, then the method must return null.
HTMLCollectioninterface HTMLCollection {
readonly attribute unsigned long length;
getter Element? item(unsigned long index);
getter Element? namedItem(DOMString name);
};
An HTMLCollection object is a
collection of
elements.
length
Returns the number of elements in the collection.
item(index)
Returns the element with index index from the collection. The elements are sorted in tree order.
namedItem(name)
Returns the first element with ID or name name 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 length attribute
must return the number of nodes represented by the collection.
The
item(index)
method must return the indexth
element in the collection. If there is no
indexth 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 result be an empty list.
For each element represented by the collection, in tree order, run these substeps:
If element has an ID which is neither the empty string nor is in result, append element's ID to result.
If element is in the HTML namespace
and has a
name attribute
whose value is neither the
empty string nor is in result, append
element's
name attribute
value to result.
Return result.
The
namedItem(key)
method must run these steps:
Return the first element in the collection for which at least one of the following is true:
name attribute
whose value is
key;
or null if there is no such element.
Each
unit of related similar-origin browsing contexts has a
mutation observer compound microtask queued flag and an associated list of
MutationObserver objects which is initially empty.
[HTML]
To queue a mutation observer compound microtask, run these steps:
If mutation observer compound microtask queued flag is set, terminate these steps.
To notify mutation observers, run these steps:
Let notify list be a copy of
unit of related similar-origin browsing contexts's
list of MutationObserver objects.
For each MutationObserver object mo
in notify list,
execute a compound microtask subtask to run these
steps:
[HTML]
Let queue be a copy of mo's record queue.
Empty mo's record queue.
Remove all transient registered observers whose observer is mo.
If queue is non-empty, invoke mo's callback with queue as first argument, and mo (itself) as second argument and callback this value.
Each node has an associated list of registered observers.
A registered observer consists of an observer (a
MutationObserver object) and options (a
MutationObserverInit dictionary). A
transient registered observer is a specific type of
registered observer that has a source which is a
registered observer.
MutationObserver[Constructor(MutationCallback callback)]
interface MutationObserver {
void observe(Node target, MutationObserverInit options);
void disconnect();
sequence<MutationRecord> takeRecords();
};
callback MutationCallback = void (sequence<MutationRecord> mutations, MutationObserver observer);
dictionary MutationObserverInit {
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 callback 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
record queue that is initially empty.
observer = new MutationObserver(callback)
Constructs a MutationObserver object and sets its
callback to
callback. The callback 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.
observer . observe(target, options)
Instructs the user agent to observe a given target (a node) and report any mutations based on the criteria given by options (an object).
The options 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 target's children are to be observed.
attributes
Set to true if mutations to target's
attributes are to be observed. Can be omitted if
attributeOldValue and/or
attributeFilter is
specified.
characterData
Set to true if mutations to target's
data are to be observed. Can be omitted if
characterDataOldValue
is specified.
subtree
Set to true if mutations to not just target, but also target's descendants are to be observed.
attributeOldValue
Set to true if
attributes is true or omitted
and target's
attribute
value before the mutation
needs to be recorded.
characterDataOldValue
Set to true if
characterData
is set to true or omitted and target'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.
observer . disconnect()
Stops observer from observing any mutations.
Until the observe() method
is used again, observer's
callback will not be invoked.
observer . takeRecords()
Empties the record queue and returns what was in there.
The
MutationObserver(callback)
constructor must create a new MutationObserver object with
callback set to callback,
append it to the
unit of related similar-origin browsing contexts's list
of MutationObserver objects, and then return it.
The
observe(target, options)
method must run these steps:
If either options'
attributeOldValue or
attributeFilter is present
and options'
attributes is omitted, set
options'
attributes to true.
If options'
characterDataOldValue
is present and options'
characterData is omitted, set
options'
characterData to true.
If options'
attributeOldValue is true
and options'
attributes is false,
throw a JavaScript TypeError.
If options'
attributeFilter is present
and options'
attributes is false,
throw a JavaScript TypeError.
If options'
characterDataOldValue
is true and options'
characterData is false,
throw a JavaScript TypeError.
For each registered observer registered in target's list of registered observers whose observer is the context object:
Remove all transient registered observers whose source is registered.
Replace registered's options with options.
Otherwise, add a new registered observer to target's list of registered observers with the context object as the observer and options as the options, and add target to context object's list of nodes on which it is registered.
The
disconnect()
method must, for each node
node in the context object's list of
nodes, remove any
registered observer on node
for which the context object is the observer, and also
empty context object's
record queue.
The
takeRecords()
method must return a copy of the
record queue and then empty the
record queue.
To queue a mutation record of type for target with one or more of (depends on type) name name, namespace namespace, oldValue oldValue, addedNodes addedNodes, removedNodes removedNodes, previousSibling previousSibling, and nextSibling nextSibling, run these steps:
Let interested observers be an initially empty set
of MutationObserver objects optionally paired with a string.
Let nodes be the inclusive ancestors of target.
Then, for each node in nodes, and then for each registered observer (with registered observer's options as options) in node's list of registered observers:
If node is not target and
options's subtree is false, continue.
If type is "attributes" and
options's attributes is not true, continue.
If type is "attributes",
options's attributeFilter is present, and either
options's attributeFilter does not contain
name or namespace is non-null, continue.
If type is "characterData" and
options's characterData is not true, continue.
If type is "childList" and
options's childList is false, continue.
If registered observer's observer is not in interested observers, append registered observer's observer to interested observers.
If either type is "attributes"
and options's attributeOldValue is true, or
type is "characterData" and
options's characterDataOldValue is true,
set the paired string of
registered observer's observer in
interested observers to oldValue.
Then, for each observer in interested observers:
Let record be a new MutationRecord
object with its type set to
type and
target set to
target.
If name and namespace are given,
set record's
attributeName to
name, and record's
attributeNamespace
to namespace.
If addedNodes is given, set record's
addedNodes to
addedNodes.
If removedNodes is given, set record's
removedNodes to
removedNodes,
If previousSibling is given, set record's
previousSibling to
previousSibling.
If nextSibling is given, set record's
nextSibling to
nextSibling.
If observer has a paired string,
set record's oldValue to
observer's paired string.
Append record to observer's record queue.
MutationRecordinterface MutationRecord {
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;
};
record . 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.
record . 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.
record . addedNodes
record . removedNodes
Return the nodes added and removed respectively.
record . previousSibling
record . nextSibling
Return the previous and next sibling respectively of the added or removed nodes, and null otherwise.
record . attributeName
Returns the local name of the changed attribute, and null otherwise.
record . attributeNamespace
Returns the namespace of the changed attribute, and null otherwise.
record . 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 type and
target
attributes must return the values they were initialized to.
The
addedNodes and
removedNodes
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
previousSibling,
nextSibling,
attributeName,
attributeNamespace, and
oldValue
attributes must return the values they were initialized to. Unless stated
otherwise, when a MutationRecord object is created, they must
be initialized to null.
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.
Nodeinterface Node : EventTarget {
const unsigned short ELEMENT_NODE = 1;
const unsigned short ATTRIBUTE_NODE = 2; // historical
const unsigned short TEXT_NODE = 3;
const unsigned short CDATA_SECTION_NODE = 4; // historical
const unsigned short ENTITY_REFERENCE_NODE = 5; // historical
const unsigned short ENTITY_NODE = 6; // historical
const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
const unsigned short COMMENT_NODE = 8;
const unsigned short DOCUMENT_NODE = 9;
const unsigned short DOCUMENT_TYPE_NODE = 10;
const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
const unsigned short NOTATION_NODE = 12; // historical
readonly attribute unsigned short nodeType;
readonly attribute DOMString nodeName;
readonly attribute DOMString? baseURI;
readonly attribute Document? ownerDocument;
readonly attribute Node? parentNode;
readonly attribute Element? parentElement;
boolean hasChildNodes();
[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 deep = false);
boolean isEqualNode(Node? node);
const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
unsigned short compareDocumentPosition(Node other);
boolean contains(Node? other);
DOMString? lookupPrefix(DOMString? namespace);
DOMString? lookupNamespaceURI(DOMString? prefix);
boolean isDefaultNamespace(DOMString? namespace);
Node insertBefore(Node node, Node? child);
Node appendChild(Node node);
Node replaceChild(Node node, Node child);
Node removeChild(Node child);
};
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 node document, 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 base URL.
Other specifications define the value of the
base URL and its observable
behavior. This specification solely defines the concept and the
baseURI attribute.
node . nodeType
Returns the type of node, represented by a number from the following list:
Node . ELEMENT_NODE (1)
Node . TEXT_NODE (3)
Text
node.
Node . PROCESSING_INSTRUCTION_NODE (7)
ProcessingInstruction
node.
Node . COMMENT_NODE (8)
Comment
node.
Node . DOCUMENT_NODE (9)
Node . DOCUMENT_TYPE_NODE (10)
Node . DOCUMENT_FRAGMENT_NODE (11)
DocumentFragment
node.
node . nodeName
Returns a string appropriate for the type of node, as follows:
Element
tagName attribute value.
Text
#text".
ProcessingInstruction
Comment
#comment".
Document
#document".
DocumentType
DocumentFragment
#document-fragment".
The nodeType attribute
must return the type of the node, which must be one of the following:
ELEMENT_NODE (1);
TEXT_NODE (3);
PROCESSING_INSTRUCTION_NODE (7);
COMMENT_NODE (8);
DOCUMENT_NODE (9);
DOCUMENT_TYPE_NODE (10);
DOCUMENT_FRAGMENT_NODE (11).
The nodeName 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".
node . baseURI
Returns the base URL.
The baseURI attribute must return the associated base URL.
node . ownerDocument
Returns the node document.
Returns null for documents.
node . parentNode
Returns the parent.
node . parentElement
Returns the parent element.
node . hasChildNodes()
Returns whether node has children.
node . childNodes
Returns the children.
node . firstChild
Returns the first child.
node . lastChild
Returns the last child.
node . previousSibling
Returns the previous sibling.
node . nextSibling
Returns the next sibling.
The ownerDocument
attribute must run these steps:
The node document of a document is that document itself.
The parentNode
attribute must return the parent.
The parentElement
attribute must return the parent element.
The hasChildNodes()
method must return true if the context object has
children, and false otherwise.
The childNodes
attribute must return a NodeList rooted at the
context object matching only
children.
The firstChild
attribute must return the
first child.
The lastChild attribute must return the last child.
The
previousSibling
attribute must return the
previous sibling.
The nextSibling
attribute must return the
next sibling.
The nodeValue attribute
must return the following, depending on the context object:
Text
Comment
ProcessingInstruction
The context object's data.
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.
Do nothing.
The textContent
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.
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 node be null.
If new value is not the empty string, set node to
a new Text node whose
data is new value.
Replace all with node within the context object.
Text
ProcessingInstruction
Comment
Replace data with node
context object, offset 0, count
length attribute value, and
data new value.
Do nothing.
node . normalize()
Removes empty
Text nodes and concatenates
the data of remaining
contiguous Text nodes into the first of their
nodes.
The normalize() method
must run these steps:
For each Text node
descendant of the
context object:
Let node be the Text
node
descendant.
Let length be node's
length attribute value.
If length is zero,
remove node and
continue with the next Text
node, if any.
Let data be the concatenation of the
data of node's
contiguous Text nodes (excluding itself), in
tree order.
Replace data with node node, offset length, count 0, and data data.
Let current node be node's next sibling.
While current node is a Text node:
For each range whose start node is current node, add length to its start offset and set its start node to node.
For each range whose end node is current node, add length to its end offset and set its end node to node.
For each range whose start node is current node's parent and start offset is current node's index, set its start node to node and its start offset to length.
For each range whose end node is current node's parent and end offset is current node's index, set its end node to node and its end offset to length.
Add current node's
length attribute value to
length.
Set current node to its next sibling.
Remove
node's
contiguous Text nodes (excluding itself), in
tree order.
node . cloneNode([deep = false])
Returns a copy of node. If deep is true, the copy also includes the node's descendants.
node . isEqualNode(other)
Returns whether node and other have the same properties.
Specifications may define cloning steps for all or some nodes. The algorithm is passed copy, node, document, 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 clone a node, optionally with a document and a clone children flag, run these steps:
If document is not given, let document be node's node document.
Let copy be a node that implements the same interfaces as node.
If copy is a document, set its node document and document to copy.
Otherwise, set copy's node document to document.
Copy the following from node to copy, depending on the type of node:
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
Element
Its namespace, namespace prefix, local name, and its attribute list.
Text
Comment
Its data.
ProcessingInstruction
—
Run any cloning steps defined for node in other applicable specifications and pass copy, node, document and the clone children flag if set, as parameters.
If the clone children flag is set, clone all the children of node and append them to copy, with document as specified and the clone children flag being set.
Return copy.
The
cloneNode(deep)
method must return a clone of the
context object, with the clone children flag set
if deep is true.
A node A equals a node B if all of the following conditions are true:
A and B's
nodeType attribute value is identical.
The following are also equal, depending on A:
DocumentType
Element
Its namespace, namespace prefix, local name, and its number of attributes in its attribute list.
ProcessingInstruction
Text
Comment
Its data.
—
If A is an element, each attribute in its attribute list has an attribute with the same namespace, local name, and value in B's attribute list.
A and B have the same number of children.
Each child of A equals the child of B at the identical index.
The
isEqualNode(node)
method must return true if node is not null and
context object equals
node, and false otherwise.
node . compareDocumentPosition(other)
Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:
Node . DOCUMENT_POSITION_DISCONNECTED (1)
Node . DOCUMENT_POSITION_PRECEDING (2)
Node . DOCUMENT_POSITION_FOLLOWING (4)
Node . DOCUMENT_POSITION_CONTAINS (8)
Node . DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)
node . contains(other)
Returns true if other is an inclusive descendant of node, and false otherwise.
These are the constants
compareDocumentPosition()
returns as mask:
DOCUMENT_POSITION_DISCONNECTED (1);
DOCUMENT_POSITION_PRECEDING (2);
DOCUMENT_POSITION_FOLLOWING (4);
DOCUMENT_POSITION_CONTAINS (8);
DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal);
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (32, 20 in hexadecimal).
The compareDocumentPosition(other)
method must run these steps:
Let reference be the context object.
If other and reference are the same object, return zero.
If other and reference 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 other is an
ancestor of
reference, return the result of adding
DOCUMENT_POSITION_CONTAINS
to
DOCUMENT_POSITION_PRECEDING.
If other is a
descendant of
reference, return the result of adding
DOCUMENT_POSITION_CONTAINED_BY
to
DOCUMENT_POSITION_FOLLOWING.
If other is
preceding
reference return
DOCUMENT_POSITION_PRECEDING.
Return
DOCUMENT_POSITION_FOLLOWING.
The
contains(other)
method must return true if other is an
inclusive descendant of
the context object, and false otherwise (including when
other is null).
To locate a namespace prefix for an element using namespace run these steps:
If element's namespace is namespace and its namespace prefix is not null, return its namespace prefix.
If, element
has an
attribute whose
namespace prefix is
"xmlns" and
value is
namespace, then return element's first
such attribute's
local name.
If element's parent element is not null, return the result of running locate a namespace prefix on that element using namespace. Otherwise, return null.
To locate a namespace for a node using prefix depends on node:
Element
If its namespace is not null and its namespace prefix is prefix, return namespace.
If it has an
attribute whose
namespace is the
XMLNS namespace,
namespace prefix
is "xmlns" and
local name is
prefix, or if prefix is null and it
has an
attribute whose
namespace is the
XMLNS namespace,
namespace prefix
is null and local name
is "xmlns":
Let value be its value if it is not the empty string, and null otherwise.
Return value.
If its parent element is null, return null.
Return the result of running locate a namespace on its parent element using prefix.
Document
If its document element is null, return null.
Return the result of running locate a namespace on its document element using prefix.
DocumentType
DocumentFragment
Return null.
If its parent element is null, return null.
Return the result of running locate a namespace on its parent element using prefix.
The
lookupPrefix(namespace)
method must run these steps:
If namespace 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 namespace.
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.
Return the result of locating a namespace prefix for its parent element, or if that is null, null.
The
lookupNamespaceURI(prefix)
method must run these steps:
If prefix is the empty string, set it to null.
Return the result of running locate a namespace for the context object using prefix.
The
isDefaultNamespace(namespace)
method must run these steps:
If namespace is the empty string, set it to null.
Let defaultNamespace be the result of running locate a namespace for the context object using null.
Return true if defaultNamespace is the same as namespace, and false otherwise.
The
insertBefore(node, child)
method must return the result of
pre-inserting
node into the context object before
child.
The
appendChild(node)
method must return the result of
appending node to
the context object.
The
replaceChild(node, child)
method must return the result of
replacing child
with node within the context object.
The
removeChild(child)
method must return the result of
pre-removing
child from the context object.
The
list of elements with local name localName
for a node root is the
HTMLCollection returned by the following algorithm:
If localName is "*" (U+002A),
return a HTMLCollection rooted at root,
whose filter matches only elements.
Otherwise, if root's
node document is an
HTML document, return a HTMLCollection rooted at
root, whose filter matches only the following
elements:
Otherwise, return a HTMLCollection rooted at
root, whose filter matches only
elements whose
local name is
localName.
When invoked with the same argument, the same HTMLCollection
object may be returned as returned by an earlier call.
The
list of elements with namespace namespace and local name localName
for a node root is the
HTMLCollection returned by the following algorithm:
If namespace is the empty string, set it to null.
If both namespace and localName
are "*" (U+002A) return a HTMLCollection rooted at
root, whose filter matches only
elements.
Otherwise, if just namespace is "*"
(U+002A), return a HTMLCollection rooted at
root, whose filter matches only
elements whose
local name is
localName.
Otherwise, if just localName is "*"
(U+002A), return a HTMLCollection rooted at
root, whose filter matches only
elements whose
namespace is
namespace.
Otherwise, return a HTMLCollection rooted at
root, whose filter matches only
elements whose
namespace is
namespace and
local name is
localName.
When invoked with the same arguments, the same HTMLCollection
object may be returned as returned by an earlier call.
The
list of elements with class names classNames
for a node root is the
HTMLCollection returned by the following algorithm:
Let classes be the result of running the ordered set parser on classNames.
If classes is the empty set, return an empty
HTMLCollection.
Return a HTMLCollection rooted at root,
whose filter matches only
elements that have all the
classes in classes.
If root'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.
Document[Constructor]
interface Document : 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 localName);
HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
HTMLCollection getElementsByClassName(DOMString classNames);
[NewObject] Element createElement(DOMString localName);
[NewObject] Element createElementNS(DOMString? namespace, DOMString qualifiedName);
[NewObject] DocumentFragment createDocumentFragment();
[NewObject] Text createTextNode(DOMString data);
[NewObject] Comment createComment(DOMString data);
[NewObject] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
Node importNode(Node node, optional boolean deep = false);
Node adoptNode(Node node);
[NewObject] Event createEvent(DOMString interface);
[NewObject] Range createRange();
// NodeFilter.SHOW_ALL = 0xFFFFFFFF
[NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
[NewObject] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
};
interface XMLDocument : Document {};
Document nodes are simply
known as documents.
Each document has an associated encoding, content type, and URL. [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 XML document unless it is flagged as being an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.
A document is always set to one of three modes: no-quirks mode, the default; quirks mode, used typically for legacy documents; and limited-quirks mode. 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.)
document = new Document()
Returns a new document.
document . implementation
Returns document's DOMImplementation object.
document . URL
document . documentURI
Returns document's URL.
document . compatMode
Returns the string "CSS1Compat" if
document is in
no-quirks mode or
limited-quirks mode, and
"BackCompat", if document is in
quirks mode.
document . characterSet
Returns document's encoding.
document . contentType
Returns document's content type.
The Document() 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
implementation
attribute must return the DOMImplementation object that is
associated with the document.
The URL and
documentURI
attributes must return the URL.
The compatMode
attribute must return "BackCompat" if the
context object is in
quirks mode, and
"CSS1Compat" otherwise.
The characterSet
attribute must return the name of the
encoding.
The contentType
attribute must return the
content type.
doctype
Returns the doctype or null if there is none.
documentElement
Returns the document element.
getElementsByTagName(localName)
If localName is "*" returns a
HTMLCollection of all
descendant
elements.
Otherwise, returns a HTMLCollection of all
descendant
elements whose
local name is
localName. (Matches case-insensitively against
elements in the
HTML namespace within an HTML document.)
getElementsByTagNameNS(namespace, localName)
If namespace and localName are
"*" returns a HTMLCollection of all
descendant
elements.
If only namespace is "*" returns a
HTMLCollection of all
descendant
elements whose
local name is
localName.
If only localName is "*" returns a
HTMLCollection of all
descendant
elements whose
namespace is
namespace.
Otherwise, returns a HTMLCollection of all
descendant
elements whose
namespace is
namespace and
local name is
localName.
getElementsByClassName(classes)
getElementsByClassName(classes)
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 classes.
The classes argument is interpreted as a space-separated list of classes.
The doctype attribute
must return the child of the
document that is a
doctype, and null otherwise.
The
documentElement
attribute must return the document element.
The
getElementsByTagName(localName)
method must return the
list of elements with local name localName
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
getElementsByTagNameNS(namespace, localName)
method must return the
list of elements with namespace namespace and local name localName
for the context object.
The
getElementsByClassName(classNames)
method must return the
list of elements with class names classNames
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.
createElement(localName)
Returns an element in the HTML namespace with localName as local name. (In an HTML document localName is lowercased.)
If localName does not match the
Name production an
"InvalidCharacterError"
exception will be thrown.
createElementNS(namespace, qualifiedName)
Returns an element with
namespace
namespace. Its
namespace prefix will
be everything before ":" (U+003E) in
qualifiedName or null. Its
local name will be
everything after ":" (U+003E) in
qualifiedName or qualifiedName.
If localName 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:
QName production.
xml" and namespace is not the
XML namespace.
xmlns" and namespace is not the
XMLNS namespace.
xmlns".
createDocumentFragment()
Returns a DocumentFragment
node.
createTextNode(data)
createComment(data)
createProcessingInstruction(target, data)
Returns a ProcessingInstruction
node whose
target is target and
data is data.
If target does not match the
Name production an
"InvalidCharacterError"
exception will be thrown.
If data contains "?>" an
"InvalidCharacterError"
exception will be thrown.
The element interface for any
name and namespace 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 createElement(localName) method must run the these steps:
If localName does not match the
Name production,
throw an
"InvalidCharacterError" exception.
If the context object is an HTML document, let localName be converted to ASCII lowercase.
Let interface be the element interface for localName and the HTML namespace.
Return a new element that implements interface, with no attributes, namespace set to the HTML namespace, local name set to localName, and node document set to the context object.
The
createElementNS(namespace, qualifiedName)
method must run these steps:
If namespace is the empty string, set it to null.
If qualifiedName does not match the
Name production,
throw an
"InvalidCharacterError" exception.
If qualifiedName does not match the
QName production,
throw a
"NamespaceError" exception.
If qualifiedName contains a ":"
(U+003E), then split the string on it and let prefix be
the part before and localName the part after. Otherwise,
let prefix be null and localName be
qualifiedName.
If prefix is not null and
namespace is null, throw
a "NamespaceError" exception.
If prefix is "xml" and
namespace is not the XML namespace,
throw a
"NamespaceError" exception.
If qualifiedName or prefix is
"xmlns" and namespace is not the
XMLNS namespace, throw a
"NamespaceError" exception.
If namespace is the XMLNS namespace
and neither qualifiedName nor prefix is
"xmlns", throw a
"NamespaceError" exception.
Let interface be the element interface for localName and namespace.
Return a new element that implements interface, with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, and node document set to the context object.
The
createDocumentFragment()
method must return a new DocumentFragment
node with its
node document set to the
context object.
The
createTextNode(data)
method must return a new Text
node with its
data set to data and
node document set to the
context object.
No check is performed that data consists of
characters that match the Char production.
The
createComment(data)
method must return a new Comment
node with its
data set to data and
node document set to the
context object.
No check is performed that data consists of
characters that match the Char production
or that it contains two adjacent hyphens or ends with a hyphen.
The createProcessingInstruction(target, data) method must run these steps:
If target does not match the
Name production,
throw an
"InvalidCharacterError" exception.
If data contains the string
"?>", throw an
"InvalidCharacterError" exception.
Return a new ProcessingInstruction
node, with
target set to target,
data set to data, and
node document set to the
context object.
No check is performed that target contains
"xml" or ":", or that
data contains characters that match the
Char production.
importNode(node [, deep = false])
Returns a copy of node. If deep is true, the copy also includes the node's descendants.
If node is a
document throws a
"NotSupportedError"
exception.
adoptNode(node)
Moves node from another document and returns it.
If node is a
document throws a
"NotSupportedError"
exception.
The
importNode(node, deep)
method must run these steps:
If node is a
document,
throw a
"NotSupportedError" exception.
Return a clone of node, with context object and the clone children flag set if deep is true.
Specifications may define adopting steps for all or some nodes. The algorithm is passed node and oldDocument, as indicated in the adopt algorithm.
To adopt a node into a document, run these steps:
Let oldDocument be node's node document.
Set node's inclusive descendants's node document to document.
Run any adopting steps defined for node in other applicable specifications and pass node and oldDocument as parameters.
The
adoptNode(node)
method must run these steps:
If node is a
document,
throw a
"NotSupportedError" exception.
Adopt node into the context object.
Return node.
The
createEvent(interface)
method must run these steps:
Let event be null.
If interface is an ASCII case-insensitive match for any of the strings in the first column in the following table, let event be the interface in the second column on the same row as the matching string:
| String | Interface | Notes |
|---|---|---|
"customevent" | CustomEvent | |
"event" | Event
| |
"events"
| ||
"htmlevents"
| ||
"mouseevent" | MouseEvent | [UIEVENTS] |
"mouseevents"
| ||
"uievent" | UIEvent
| |
"uievents"
|
If event is null, throw a
"NotSupportedError".
Return a new event implementing the event interface.
Event constructors can be used instead.
The createRange()
method must return a new range with
(context object, 0) as its
start and
end.
The Range() constructor can be used instead.
The
createNodeIterator(root, whatToShow, filter)
method must run these steps:
Create a NodeIterator object.
Set root and initialize
the referenceNode
attribute to the root argument.
Initialize the
pointerBeforeReferenceNode
attribute to true.
Set whatToShow to the whatToShow argument.
Set filter to filter.
Return the newly created NodeIterator object.
The
createTreeWalker(root, whatToShow, filter)
method must run these steps:
Create a TreeWalker object.
Set root and initialize
the currentNode attribute to
the root argument.
Set whatToShow to the whatToShow argument.
Set filter to filter.
Return the newly created TreeWalker object.
DOMImplementationUser agents must create a DOMImplementation object whenever
a document is created and associate it
with that document.
interface DOMImplementation {
[NewObject] DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
[NewObject] XMLDocument createDocument(DOMString? namespace, [TreatNullAs=EmptyString] DOMString qualifiedName, optional DocumentType? doctype = null);
[NewObject] Document createHTMLDocument(optional DOMString title);
boolean hasFeature(); // useless; always returns true
};
doctype = document . implementation . createDocumentType(qualifiedName, publicId, systemId)
Returns a doctype, with the given
qualifiedName, publicId, and
systemId. If qualifiedName 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.
doc = document . implementation . createDocument(namespace, qualifiedName [, doctype = null])
Returns an XMLDocument, with a
document element whose
local name is
qualifiedName and whose
namespace is
namespace (unless qualifiedName is the
empty string), and with doctype, if it is given, as its
doctype.
This method throws the same exceptions as the createElementNS method, when
invoked with the same arguments.
doc = document . implementation . createHTMLDocument([title])
Returns a document, with a basic
tree already constructed including a
title element, unless the title
argument is omitted.
The
createDocumentType(qualifiedName, publicId, systemId)
method must run these steps:
If qualifiedName does not match the
Name production,
throw an
"InvalidCharacterError" exception.
If qualifiedName does not match the QName production,
throw a
"NamespaceError" exception.
Return a new doctype, with qualifiedName as its name, publicId as its public ID, and systemId as its system ID, and with its node document set to the associated document of the context object.
No check is performed that publicId
matches the PublicChar production or that
systemId does not contain both a '"' and
"'".
The
createDocument(namespace, qualifiedName, doctype)
method must run these steps:
Let document 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 element be null.
If qualifiedName is not the empty string, set
element to the result of invoking the
createElementNS() method
with the arguments namespace and
qualifiedName on document. If that threw
an exception, re-throw the exception.
If doctype is not null, append doctype to document.
If element is not null, append element to document.
document's origin is an alias to the origin of the context object's associated document, and document's effective script origin is an alias to the effective script origin of the context object's associated document. [HTML]
Return document.
The
createHTMLDocument(title)
method must run these steps:
Let doc be a new document that is an HTML document.
Set doc's
content type to
"text/html".
Create a doctype, with
"html"
as its name and with its
node document set to
doc. Append
the newly created node to doc.
Create an html element in the HTML
namespace, and append
it to doc.
Create a head element in the HTML
namespace, and append
it to the html element created in the previous step.
If the title argument is not omitted:
Create a body element in the
HTML namespace, and
append it to the
html element created in the earlier step.
doc's origin is an alias to the origin of the context object's associated document, and doc's effective script origin is an alias to the effective script origin of the context object's associated document. [HTML]
Return doc.
The hasFeature() 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.
DocumentFragment[Constructor]
interface DocumentFragment : Node {
};
A DocumentFragment node can have an
associated element named
host.
An object A is a host-including inclusive ancestor of an object B, if either A is an inclusive ancestor of B, or if B's root has an associated host and A is a host-including inclusive ancestor of B'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.
tree = new DocumentFragment()
Returns a new DocumentFragment node.
The DocumentFragment() constructor
must return a new DocumentFragment node whose
node document is the global object's associated
document.
DocumentTypeinterface DocumentType : Node {
readonly attribute DOMString name;
readonly attribute DOMString publicId;
readonly attribute DOMString systemId;
};
DocumentType nodes are
simply known as doctypes.
Doctypes have an associated name, public ID, and system ID.
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 name attribute
must return the name.
The publicId
attribute must return the
public ID.
The systemId
attribute must return the
system ID.
Elementinterface Element : 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 name);
DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
void setAttribute(DOMString name, DOMString value);
void setAttributeNS(DOMString? namespace, DOMString name, DOMString value);
void removeAttribute(DOMString name);
void removeAttributeNS(DOMString? namespace, DOMString localName);
boolean hasAttribute(DOMString name);
boolean hasAttributeNS(DOMString? namespace, DOMString localName);
boolean matches(DOMString selectors);
HTMLCollection getElementsByTagName(DOMString localName);
HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
HTMLCollection getElementsByClassName(DOMString classNames);
};
Element nodes are simply
known as elements.
Elements have an associated namespace, namespace prefix, and local name. When an element is created, its local name is always given. Unless explicitly given when an element is created, its namespace and namespace prefix are null.
Elements also have an ordered attribute list. Unless explicitly given when an element is created, its attribute list is empty. An element has an attribute A if A is in its attribute list.
Applicable specifications and this specification (can) use the hooks an attribute is set, an attribute is changed, an attribute is added, and an attribute is removed, for further processing of the attribute's value.
To get an attribute for an element element using a localName and optionally a namespace, run these steps:
If namespace is not given, set it to null.
Return the value of the attribute in element's attribute list whose namespace is namespace and local name is localName, if it has one, and null otherwise.
To set an attribute for an element element using a localName and value, and optionally a name, prefix, and namespace, run these steps:
If name is not given, set it to localName.
If prefix is not given, set it to null.
If namespace is not given, set it to null.
Let attribute be the attribute in element's attribute list whose namespace is namespace and whose local name is localName, or null if there is no such attribute.
If attribute is null, create an attribute whose local name is localName, value is value, name is name, namespace is namespace, and namespace prefix is prefix, and then append this attribute to element and terminate these steps.
Change attribute from element to value.
To change an attribute attribute from an element element to value, run these steps:
Queue a mutation record of "attributes"
for element with name attribute's
local name, namespace
attribute's
namespace, and oldValue
attribute's
value.
Set attribute's value to value.
An attribute is set and an attribute is changed.
To append an attribute attribute to an element element, run these steps:
Queue a mutation record of "attributes"
for element with name attribute's
local name, namespace
attribute's
namespace, and oldValue
null.
Append the attribute to the element's attribute list.
An attribute is set and an attribute is added.
To remove an attribute attribute from an element element, run these steps:
Queue a mutation record of "attributes"
for element with name attribute's
local name, namespace
attribute's
namespace, and oldValue
attribute's
value.
Remove attribute from the element's attribute list.
Elements can have an associated
unique identifier (ID) 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
classes.
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 parent element. If the
node has a
parent of a different type, its
parent element is null.
The document element 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 in a document.
namespaceURI
Returns the namespace.
prefix
Returns the namespace prefix.
localName
Returns the local name.
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 namespaceURI
attribute must return the context object's
namespace.
The prefix attribute must return the context object's
namespace prefix.
The localName
attribute must return the context object's
local name.
The tagName attribute
must run these steps:
If context object's
namespace prefix is not
null, let qualified name be its
namespace prefix, followed
by a ":" (U+003A), followed by its
local name. Otherwise, let
qualified name be its
local name.
If the context object is in the HTML namespace and its node document is an HTML document, let qualified name be converted to ASCII uppercase.
Return qualified name.
Some attributes are defined to reflect 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 value be the result.
If value is null, return the empty string.
Return value.
On setting, set an attribute for the context object using the name of the attribute and the given value.
The id attribute must
reflect the "id"
content attribute.
The className
attribute must reflect the
"class" content attribute.
The classList
attribute must return the associated DOMTokenList object
representing the context object's
classes.
The attributes
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 getAttribute(name) method must run these steps:
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
Return the value of the first attribute in the context object's attribute list whose name is name, and null otherwise.
The
getAttributeNS(namespace, localName)
method must return the following steps:
If namespace is the empty string, set it to null.
Return getting an attribute for the context object using localName and namespace.
The
setAttribute(name, value)
method must run these steps:
If name 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 name be converted to ASCII lowercase.
Let attribute be the first attribute in the context object's attribute list whose name is name, or null if there is no such attribute.
If attribute is null, create an attribute whose local name is name and value is value, and then append this attribute to the context object and terminate these steps.
Change attribute from context object to value.
The
setAttributeNS(namespace, name, value)
method must run these steps:
If namespace is the empty string, set it to null.
If name does not match the
Name production in XML,
throw an
"InvalidCharacterError" exception.
If name does not match the
QName production in Namespaces in XML,
throw a
"NamespaceError" exception.
If name contains a ":" (U+003E),
then split the string on it and let prefix be the part
before and localName the part after. Otherwise, let
prefix be null and localName be
name.
If prefix is not null and
namespace is null, throw
a "NamespaceError" exception.
If prefix is "xml" and
namespace is not the XML namespace,
throw a
"NamespaceError" exception.
If name or prefix is
"xmlns" and namespace is not the
XMLNS namespace, throw a
"NamespaceError" exception.
If namespace is the XMLNS namespace
and neither name nor prefix is
"xmlns", throw a
"NamespaceError" exception.
Set an attribute for the context object using localName, value, and also name, prefix, and namespace.
The
removeAttribute(name)
method must run these steps:
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
Remove the first attribute from the context object whose name is name, if any.
The
removeAttributeNS(namespace, localName)
method must return the following steps:
If namespace is the empty string, set it to null.
Remove the attribute from the context object whose namespace is namespace and local name is localName, if any.
The
hasAttribute(name)
method must run these steps:
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
Return true if the context object has an attribute whose name is name, and false otherwise.
The
hasAttributeNS(namespace, localName)
method must run these steps:
If namespace is the empty string, set it to null.
Return true if the context object has an attribute whose namespace is namespace and local name is localName, and false otherwise.
element . matches(selectors)
Returns true if matching selectors against element's root yields element, and false otherwise.
To match a selectors string selectors against a set, run these steps:
Let s be the result of parse a selector from selectors. [SELECTORS]
If s is failure, throw a
JavaScript TypeError.
Return the result of evaluate a selector s using :scope elements set. [SELECTORS]
The matches(selectors)
method must return true if the context object is in the result of running
match a selectors string selectors against a set consisting
of context object, and false otherwise.
The
getElementsByTagName(localName)
method must return the
list of elements with local name localName
for the context object.
The
getElementsByTagNameNS(namespace, localName)
method must return the
list of elements with namespace namespace and local name localName
for the context object.
The
getElementsByClassName(classNames)
method must return the
list of elements with class names classNames
for the context object.
Attrinterface Attr {
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
attributes. They are sometimes referred
to as content attributes to avoid confusion with IDL attributes.
Attributes have a local name and value.
For legacy reasons, attributes also have an associated name, namespace, and namespace prefix.
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
A attribute
is an attribute whose
local name is
A and whose
namespace and
namespace prefix are
null.
The localName attribute
must return the local name.
The value attribute must
return the value.
Setting the value attribute must
change
value to the new value.
The name attribute must
return the name.
The namespaceURI
attribute must return the
namespace.
The prefix attribute must
return the
namespace prefix.
The specified attribute must return
true.
CharacterDatainterface CharacterData : Node {
[TreatNullAs=EmptyString] attribute DOMString data;
readonly attribute unsigned long length;
DOMString substringData(unsigned long offset, unsigned long count);
void appendData(DOMString data);
void insertData(unsigned long offset, DOMString data);
void deleteData(unsigned long offset, unsigned long count);
void replaceData(unsigned long offset, unsigned long count, DOMString data);
};
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 data.
To replace data of node node with offset offset, count count, and data data, run these steps:
Let length be node's
length attribute value.
If offset is greater than length,
throw an
"IndexSizeError" exception.
If offset plus count is greater than length let count be length minus offset.
Queue a mutation record of "characterData"
for node with oldValue node's
data.
Insert data into node's data after offset code units.
Let delete offset be offset plus the number of code units in data.
Starting from delete offset code units, remove count code units from node's data.
For each range whose start node is node and start offset is greater than offset but less than or equal to offset plus count, set its start offset to offset.
For each range whose end node is node and end offset is greater than offset but less than or equal to offset plus count, set its end offset to offset.
For each range whose start node is node and start offset is greater than offset plus count, increase its start offset by the number of code units in data, then decrease it by count.
For each range whose end node is node and end offset is greater than offset plus count, increase its end offset by the number of code units in data, then decrease it by count.
To substring data with node node, offset offset, and count count, run these steps:
Let length be node's
length attribute value.
If offset is greater than length,
throw an
"IndexSizeError" exception.
If offset plus count is greater than length, return a string whose value is the code units from the offsetth code unit to the end of node's data, and then terminate these steps.
Return a string whose value is the code units from the offsetth code unit to the offset+countth code unit in node's data.
The data 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 length
attribute must return the number of
code units in
data.
The
substringData(offset, count)
method must substring data with node
context object, offset offset, and count
count.
The
appendData(data)
method must replace data with node
context object, offset
length attribute value, count 0,
and data data.
The
insertData(offset, data)
method must replace data with node
context object, offset offset, count 0, and
data data.
The
deleteData(offset, count)
method must replace data with node
context object, offset offset, count
count, and data the empty string.
The
replaceData(offset, count, data)
method must replace data with node
context object, offset offset, count
count, and data data.
Text[Constructor(optional DOMString data = "")]
interface Text : CharacterData {
[NewObject] Text splitText(unsigned long offset);
readonly attribute DOMString wholeText;
};
text = new Text([data = ""])
text . splitText(offset)
Splits data at the given
offset and returns the remainder as Text
node.
text . wholeText
The Text(data) constructor
must return a new Text node whose
data is data and
node document is the global object's associated
document.
To split a Text
node node with offset
offset, run these steps:
Let length be node's
length attribute value.
If offset is greater than length,
throw an
"IndexSizeError" exception.
Let count be length minus offset.
Let new data be the result of substringing data with node node, offset offset, and count count.
Let new node be a new Text
node, with the same
node document as
node. Set new node's
data to new data.
Let parent be node's parent.
If parent is not null, run these substeps:
Insert new node into parent before node's next sibling.
For each range whose start node is node and start offset is greater than offset, set its start node to new node and decrease its start offset by offset.
For each range whose end node is node and end offset is greater than offset, set its end node to new node and decrease its end offset by offset.
For each range whose start node is parent and start offset is equal to the index of node + 1, increase its start offset by one.
For each range whose end node is parent and end offset is equal to the index of node + 1, increase its end offset by one.
Replace data with node node, offset offset, count count, and data the empty string.
If parent is null, run these substeps:
For each range whose start node is node and start offset is greater than offset, set its start offset to offset.
For each range whose end node is node and end offset is greater than offset, set its end offset to offset.
Return new node.
The
splitText(offset)
method must split the
context object with offset offset.
The contiguous Text nodes of a node are the node
itself, the
previous sibling
Text node (if any) and its
contiguous Text nodes, and the
next sibling Text
node (if any) and its contiguous Text nodes,
avoiding any duplicates.
The wholeText
attribute must return a concatenation of the
data of the
contiguous Text nodes of the
context object, in
tree order.
ProcessingInstructioninterface ProcessingInstruction : CharacterData {
readonly attribute DOMString target;
};
ProcessingInstruction nodes
have an associated target.
The target
attribute must return the target.
Comment[Constructor(optional DOMString data = "")]
interface Comment : CharacterData {
};
The Comment(data)
constructor must return a new Comment node
whose data is data and
node document is the global object's associated
document.
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.
p
In the node tree above, a
range can be used to represent the sequence
“syndata is awes”. Assuming p is assigned to the
p element, and
em 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 quoteAttributes 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.
Range[Constructor]
interface Range {
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 node, unsigned long offset);
void setEnd(Node node, unsigned long offset);
void setStartBefore(Node node);
void setStartAfter(Node node);
void setEndBefore(Node node);
void setEndAfter(Node node);
void collapse(optional boolean toStart = false);
void selectNode(Node node);
void selectNodeContents(Node node);
const unsigned short START_TO_START = 0;
const unsigned short START_TO_END = 1;
const unsigned short END_TO_END = 2;
const unsigned short END_TO_START = 3;
short compareBoundaryPoints(unsigned short how, Range sourceRange);
void deleteContents();
[NewObject] DocumentFragment extractContents();
[NewObject] DocumentFragment cloneContents();
void insertNode(Node node);
void surroundContents(Node newParent);
[NewObject] Range cloneRange();
void detach();
boolean isPointInRange(Node node, unsigned long offset);
short comparePoint(Node node, unsigned long offset);
boolean intersectsNode(Node node);
stringifier;
};
Range objects are simply known as
ranges.
A boundary point is a (node, offset) 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 (node A, offset A) and (node B, offset B) have the same root, the position of the first relative to the second is either before, equal, or after, as returned by the following algorithm:
If node A is the same as node B, return equal if offset A is the same as offset B, before if offset A is less than offset B, and after if offset A is greater than offset B.
If node A is following node B, compute the position of (node B, offset B) relative to (node A, offset A). If it is before, return after. If it is after, return before.
If node A is an ancestor of node B:
Return before.
Each range has two associated boundary points — a start and end.
For convenience, start node is start's node, start offset is start's offset, end node is end's node, and end offset is end's offset.
The root of a range is the root of its start node.
A node node is contained in a range range if node's root is the same as range's root, and (node, 0) is after range's start, and (node, length of node) is before range's end.
A node is partially contained 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 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.
range = new Range()
Returns a new range.
The Range() constructor must return a new
range with
(global object's associated document, 0) as its
start and
end.
startContainer
Returns range's start node.
startOffset
Returns range's start offset.
endContainer
Returns range's end node.
endOffset
Returns range's end offset.
collapsed
Returns true if range's start and end are the same, and false otherwise.
commonAncestorContainer
Returns the node, furthest away from the document, that is an ancestor of both range's start node and end node.
The startContainer
attribute must return the
start node.
The startOffset
attribute must return the
start offset.
The endContainer
attribute must return the
end node.
The endOffset
attribute must return the
end offset.
The collapsed attribute
must return true if start is the same
as end, and false otherwise.
The
commonAncestorContainer
attribute must run these steps:
Let container be start node.
While container is not an inclusive ancestor of end node, let container be container's parent.
Return container.
To set the start or end of a range to a boundary point (node, offset), run these steps:
If node is a
doctype,
throw an
"InvalidNodeTypeError" exception.
If offset is greater than
node's length,
throw an
"IndexSizeError" exception.
Let bp be the boundary point (node, offset).
The
setStart(node, offset)
method must set the start of the
context object to
boundary point
(node, offset).
The
setEnd(node, offset)
method must set the end of the
context object to
boundary point
(node, offset).
The
setStartBefore(node)
method must run these steps:
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError" exception.
Set the start of the context object to boundary point (parent, node's index).
The
setStartAfter(node)
method must run these steps:
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError" exception.
Set the start of the context object to boundary point (parent, node's index plus one).
The
setEndBefore(node)
method must run these steps:
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError" exception.
Set the end of the context object to boundary point (parent, node's index).
The
setEndAfter(node)
method must run these steps:
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError" exception.
Set the end of the context object to boundary point (parent, node's index plus one).
The
collapse(toStart)
method must if toStart is true, set
end to
start, and set
start to
end otherwise.
To select a node node within a range range, run these steps:
Let parent be node's parent.
If parent is null, throw an
"InvalidNodeTypeError".
Let index be node's index.
Set range's start to boundary point (parent, index).
Set range's end to boundary point (parent, index plus one).
The
selectNode(node)
method must select node within
context object.
The
selectNodeContents(node)
method must run these steps:
If node is a
doctype,
throw an
"InvalidNodeTypeError".
Let length be the length of node.
Set start to the boundary point (node, 0).
Set end to the boundary point (node, length).
The
compareBoundaryPoints(how, sourceRange)
method must run these steps:
If how is not one of
throw a
"NotSupportedError" exception.
If context object's
root is not the same as
sourceRange's root,
throw a
"WrongDocumentError" exception.
If how is:
START_TO_START:
Let this point be the context object's start.
Let other point be sourceRange's start.
START_TO_END:
Let this point be the context object's end.
Let other point be sourceRange's start.
END_TO_END:
Let this point be the context object's end.
Let other point be sourceRange's end.
END_TO_START:
Let this point be the context object's start.
Let other point be sourceRange's end.
If the position of this point relative to other point is
The deleteContents()
method must run these steps:
Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.
If original start node and
original end node are the same, and they are a
Text, ProcessingInstruction, or
Comment node,
replace data with node
original start node, offset
original start offset, count
original end offset minus
original start offset, and data the empty string, and then
terminate these steps.
Let nodes to remove 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 original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
Otherwise:
Let reference node equal original start node.
While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
Set new node to the parent of reference node, and new offset to one plus the index of reference node.
If reference node's parent were null, it would be the root of the context object, so would be an inclusive ancestor of original end node, and we could not reach this point.
If original start node is a Text,
ProcessingInstruction, or Comment
node,
replace data with node
original start node, offset
original start offset, count
original start node's
length minus
original start offset, data the empty string.
For each node in nodes to remove, in tree order, remove node from its parent.
If original end node is a Text,
ProcessingInstruction, or Comment
node,
replace data with node
original end node, offset 0, count
original end offset and data the empty string.
To extract a range range, run these steps:
Let fragment be a new DocumentFragment
node whose
node document is range's
start node's
node document.
Let original start node, original start offset, original end node, and original end offset be range's start node, start offset, end node, and end offset, respectively.
If original start node equals
original end node, and they are a Text,
ProcessingInstruction, or Comment
node:
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
Append clone to fragment.
Replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string.
Return fragment.
Let common ancestor be original start node.
While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
Let first partially contained child be null.
If original start node is not an inclusive ancestor of original end node, set first partially contained child to the first child of common ancestor that is partially contained in range.
Let last partially contained child be null.
If original end node is not an inclusive ancestor of original start node, set last partially contained child to the last child of common ancestor that is partially contained in range.
These variable assignments do actually always make sense. For instance, if original start node is not an inclusive ancestor of original end node, original start node is itself partially contained in range, and so are all its ancestors up until a child of common ancestor. common ancestor cannot be original start node, because it has to be an inclusive ancestor of original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
Let contained children be a list of all children of common ancestor that are contained in range, in tree order.
If any member of contained children 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 original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
Otherwise:
Let reference node equal original start node.
While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
Set new node to the parent of reference node, and new offset to one plus reference node's index.
If reference node's parent is null, it would be the root of range, so would be an inclusive ancestor of original end node, and we could not reach this point.
If first partially contained child is a
Text, ProcessingInstruction, or
Comment node:
In this case, first partially contained child is original start node.
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.
Append clone to fragment.
Replace data with node original start node, offset original start offset, count original start node's length minus original start offset, and data the empty string.
Otherwise, if first partially contained child is not null:
Let clone be a clone of first partially contained child.
Append clone to fragment.
Let subrange be a new range whose start is (original start node, original start offset) and whose end is (first partially contained child, first partially contained child's length).
Let subfragment be the result of extracting subrange.
Append subfragment to fragment.
For each contained child in contained children, append contained child to fragment.
If last partially contained child is a
Text, ProcessingInstruction, or
Comment node:
In this case, last partially contained child is original end node.
Let clone be a clone of original end node.
Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
Append clone to fragment.
Replace data with node original end node, offset 0, count original end offset, and data the empty string.
Otherwise, if last partially contained child is not null:
Let clone be a clone of last partially contained child.
Append clone to fragment.
Let subrange be a new range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
Let subfragment be the result of extracting subrange.
Append subfragment to fragment.
Return fragment.
The extractContents() method
must return the result of extracting
context object.
To clone a range range, run these steps:
Let fragment be a new DocumentFragment
node whose
node document is range's
start node's
node document.
Let original start node, original start offset, original end node, and original end offset be range's start node, start offset, end node, and end offset, respectively.
If original start node equals
original end node, and they are a Text,
ProcessingInstruction, or Comment
node:
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
Append clone to fragment.
Return fragment.
Let common ancestor be original start node.
While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
Let first partially contained child be null.
If original start node is not an inclusive ancestor of original end node, set first partially contained child to the first child of common ancestor that is partially contained in range.
Let last partially contained child be null.
If original end node is not an inclusive ancestor of original start node, set last partially contained child to the last child of common ancestor that is partially contained in range.
These variable assignments do actually always make sense. For instance, if original start node is not an inclusive ancestor of original end node, original start node is itself partially contained in range, and so are all its ancestors up until a child of common ancestor. common ancestor cannot be original start node, because it has to be an inclusive ancestor of original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
Let contained children be a list of all children of common ancestor that are contained in range, in tree order.
If any member of contained children 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 first partially contained child is a
Text, ProcessingInstruction, or
Comment node:
In this case, first partially contained child is original start node.
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.
Append clone to fragment.
Otherwise, if first partially contained child is not null:
Let clone be a clone of first partially contained child.
Append clone to fragment.
Let subrange be a new range whose start is (original start node, original start offset) and whose end is (first partially contained child, first partially contained child's length).
Let subfragment be the result of cloning subrange.
Append subfragment to fragment.
For each contained child in contained children:
If last partially contained child is a
Text, ProcessingInstruction, or
Comment node:
In this case, last partially contained child is original end node.
Let clone be a clone of original end node.
Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
Append clone to fragment.
Otherwise, if last partially contained child is not null:
Let clone be a clone of last partially contained child.
Append clone to fragment.
Let subrange be a new range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
Let subfragment be the result of cloning subrange.
Append subfragment to fragment.
Return fragment.
The cloneContents()
method must return the result of cloning
context object.
To insert a node node into a range range, run these steps:
If range's start node
is either a ProcessingInstruction or Comment
node, or a Text
node whose parent
is null, throw an "HierarchyRequestError"
exception.
Let referenceNode be null.
If range's start node
is a Text node,
split it with offset
range's start offset, and
set referenceNode to the result.
Otherwise, set referenceNode to the child of start node whose index is start offset, and null if there is no such child otherwise.
Let parent be range's start node if referenceNode is null, and referenceNode's parent otherwise.
Let newOffset be parent's length if referenceNode is null, and referenceNode's index otherwise.
Increase newOffset by node's
length if node is a
DocumentFragment node, and one otherwise.
Pre-insert node into parent before referenceNode.
If range's start and end are the same, set range's end to (parent, newOffset).
The insertNode(node)
method must insert node into
context object.
The
surroundContents(newParent)
method must run these steps:
If a non-Text node is
partially contained in the context object,
throw an
"InvalidStateError" exception.
If newParent is a Document,
DocumentType, or DocumentFragment
node,
throw an
"InvalidNodeTypeError" exception.
Let fragment be the result of extracting context object.
If newParent has children, replace all with null within newParent.
Insert newParent into context object.
Append fragment to newParent.
Select newParent within context object.
The cloneRange()
method must return a new range with the
same start and
end as the context object.
The detach() method must
do nothing. Its functionality (disabling a
Range object) was removed, but the method itself is preserved
for compatibility.
comparePoint( parent, offset )
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.
intersectsNode( node )
Returns whether range intersects node.
The
isPointInRange(node, offset)
must run these steps:
If node's root is different from the context object's root, return false.
If node is a
doctype,
throw an
"InvalidNodeTypeError" exception.
If offset is greater than
node's length,
throw an
"IndexSizeError" exception.
If (node, offset) is before start or after end, return false.
Return true.
The
comparePoint(node, offset)
method must run these steps:
If node's root is
different from the context object's
root,
throw a "WrongDocumentError"
exception.
If node is a
doctype,
throw an
"InvalidNodeTypeError" exception.
If offset is greater than
node's length,
throw an
"IndexSizeError" exception.
Return 0.
The
intersectsNode(node)
method must run these steps:
The stringifier must run these steps:
Let s 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
s the substring of that
node's
data from the
start offset until the end.
Append to s 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
s the substring of that
node's
data from its start until the
end offset.
Return s.
The
createContextualFragment(),
getClientRects(),
and
getBoundingClientRect()
methods are defined in other specifications.
[DOMPS]
[CSSOMVIEW]
NodeIterator and TreeWalker objects can be used
to filter and traverse node
trees.
Each NodeIterator and TreeWalker object has an
associated active flag to avoid
recursive invocations. It is initially unset.
Each NodeIterator and TreeWalker object also
has an associated root
node,
whatToShow bitmask, and
filter callback.
To filter node run these steps:
If active flag is set
throw an
"InvalidStateError".
Let n be node's
nodeType attribute value minus 1.
If the nth 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 result be the return value of invoking filter.
Unset the active flag.
If an exception was thrown, re-throw the exception.
Return result.
NodeIteratorinterface NodeIterator {
[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
iterator collection, 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 root attribute
must return root.
The
referenceNode
and
pointerBeforeReferenceNode
attributes must return what they were initialized to.
The whatToShow
attribute must return
whatToShow.
The filter
attribute must return filter.
To traverse in direction direction run these steps:
Let node be the value of the
referenceNode attribute.
Let before node be the value of the
pointerBeforeReferenceNode
attribute.
Run these substeps:
If before node is false, let node be the first node following node in the iterator collection. If there is no such node return null.
If before node is true, set it to false.
If before node is true, let node be the first node preceding node in the iterator collection. If there is no such node return null.
If before node is false, set it to true.
Filter node and let result be the return value.
If result is
FILTER_ACCEPT, go to the
next step in the overall set of steps.
Otherwise, run these substeps again.
Set the
referenceNode attribute
to node, set the
pointerBeforeReferenceNode
attribute to before node, and return
node.
The nextNode()
method must traverse in
direction next.
The
previousNode()
method must traverse in
direction previous.
The detach()
method must do nothing. Its functionality (disabling a
NodeIterator object) was removed, but the method itself is preserved
for compatibility.
TreeWalkerinterface TreeWalker {
[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 root attribute must
return root.
The whatToShow
attribute must return
whatToShow.
The filter attribute
must return filter.
The currentNode
attribute must return what it was initialized to.
Setting the currentNode
attribute must set it to the new value.
The parentNode()
method must run these steps:
Let node be the value of the
currentNode attribute.
While node is not null and is not root, run these substeps:
Let node be node's parent.
If node is not null and
filtering node
returns FILTER_ACCEPT,
then set the currentNode
attribute to node, return node.
Return null.
To traverse children of type type, run these steps:
Let node be the value
of the currentNode attribute.
Set node to node's first child if type is first, and node's last child if type is last.
Main: While node is not null, run these substeps:
Filter node and let result be the return value.
If result is
FILTER_ACCEPT, then set
the currentNode
attribute to node and return node.
If result is
FILTER_SKIP, run these
subsubsteps:
Let child be node's first child if type is first, and node's last child if type is last.
If child is not null, set node to child and goto Main.
While node is not null, run these subsubsteps:
Let sibling be node's next sibling if type is first, and node's previous sibling if type is last.
If sibling is not null, set node to sibling and goto Main.
Let parent be node's parent.
If parent is null, parent is
root, or
parent is
currentNode attribute's
value, return null.
Otherwise, set node to parent.
Return null.
The firstChild()
method must traverse children
of type first.
The lastChild()
method must traverse children
of type last.
To traverse siblings of type type run these steps:
Let node be the value of the
currentNode attribute.
If node is root, return null.
Run these substeps:
Let sibling be node's next sibling if type is next, and node's previous sibling if type is previous.
While sibling is not null, run these subsubsteps:
Set node to sibling.
Filter node and let result be the return value.
If result is
FILTER_ACCEPT, then set
the currentNode
attribute to node and return node.
Set sibling to node's first child if type is next, and node's last child if type is previous.
If result is
FILTER_REJECT or
sibling is null, then set sibling to
node's
next sibling if
type is next, and node's
previous sibling if
type is previous.
Set node to its parent.
If node is null or is root, return null.
Filter
node and if the return value is
FILTER_ACCEPT, then
return null.
Run these substeps again.
The
nextSibling()
method must traverse siblings
of type next.
The
previousSibling()
method must traverse siblings
of type previous.
The
previousNode()
method must run these steps:
Let node be the value of the
currentNode attribute.
While node is not root, run these substeps:
Let sibling be the previous sibling of node.
While sibling is not null, run these subsubsteps:
Set node to sibling.
Filter node and let result be the return value.
While result is not
FILTER_REJECT and
node has a
child, set node
to its last child and then
filter node and
set result to the return value.
If result is
FILTER_ACCEPT, then set
the currentNode
attribute to node and return node.
Set sibling to the previous sibling of node.
Set node to its parent.
Filter
node and if the return value is
FILTER_ACCEPT, then set
the currentNode attribute
to node and return node.
Return null.
The nextNode()
method must run these steps:
Let node be the value of the
currentNode attribute.
Let result be
FILTER_ACCEPT.
Run these substeps:
While result is not
FILTER_REJECT and
node has a child,
run these subsubsteps:
Set node to its first child.
Filter node and set result to the return value.
If result is
FILTER_ACCEPT, then set
the currentNode attribute
to node and return node.
If a node is following node and is not following root, set node to the first such node.
Otherwise, return null.
Filter node and set result to the return value.
If result is
FILTER_ACCEPT, then set
the currentNode attribute
to node and return node.
Run these substeps again.
NodeFiltercallback interface NodeFilter {
// 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 node);
};
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:
FILTER_ACCEPT (1);
FILTER_REJECT (2);
FILTER_SKIP (3).
These constants can be used for the whatToShow bitmask:
SHOW_ALL (4294967295, FFFFFFFF in hexadecimal);
SHOW_ELEMENT (1);
SHOW_TEXT (4);
SHOW_PROCESSING_INSTRUCTION (64, 40 in hexadecimal);
SHOW_COMMENT (128, 80 in hexadecimal);
SHOW_DOCUMENT (256, 100 in hexadecimal);
SHOW_DOCUMENT_TYPE (512, 200 in hexadecimal);
SHOW_DOCUMENT_FRAGMENT (1024, 400 in hexadecimal).
Yes, the names DOMTokenList and
DOMSettableTokenList are unfortunate legacy mishaps.
DOMTokenListinterface DOMTokenList {
readonly attribute unsigned long length;
getter DOMString? item(unsigned long index);
boolean contains(DOMString token);
void add(DOMString... tokens);
void remove(DOMString... tokens);
boolean toggle(DOMString token, optional boolean force);
stringifier;
};
A DOMTokenList object has an associated ordered set of
tokens, which is initially empty.
A DOMTokenList object also has an associated
element and an
attribute's
local name.
A DOMTokenList object's
update steps 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.
tokenlist . length
Returns the number of tokens.
tokenlist . item(index)
tokenlist[index]
Returns the token with index index.
tokenlist . contains(token)
Returns true if token is present, and false otherwise.
Throws a "SyntaxError" exception if token
is the empty string.
Throws an "InvalidCharacterError" exception if
token contains any
ASCII whitespace.
tokenlist . add(tokens…)
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.
tokenlist . remove(tokens…)
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.
tokenlist . toggle(token [, force])
If force is not given, "toggles"
token, removing it if it's present and adding it if it's
not. If force is true, adds token (same
as add()). If
force is false, removes token (same as
remove()).
Returns true if token is now present, and false otherwise.
Throws a "SyntaxError" exception if token is empty.
Throws an "InvalidCharacterError" exception if token contains any spaces.
The length
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
item(index)
method must run these steps:
If index is equal to or greater than the number of tokens in tokens, return null.
Return the indexth token in tokens.
The
contains(token)
method must run these steps:
If token is the empty string, then
throw a "SyntaxError"
exception.
If token contains any
ASCII whitespace, then
throw
an "InvalidCharacterError" exception.
Return true if token is in tokens, and false otherwise.
The
add(tokens…)
method must run these steps:
If one of tokens is the empty string,
throw a "SyntaxError"
exception.
If one of tokens contains any
ASCII whitespace, then
throw an
"InvalidCharacterError" exception.
For each token in tokens, in given order, that is not in tokens, append token to tokens.
Run the update steps.
The
remove(tokens…)
method must run these steps:
If one of tokens is the empty string,
throw a "SyntaxError"
exception.
If one of tokens contains any
ASCII whitespace, then
throw an
"InvalidCharacterError" exception.
For each token in tokens, remove token from tokens.
Run the update steps.
The
toggle(token, force)
method must run these steps:
If token is the empty string,
throw a "SyntaxError"
exception.
If token contains any
ASCII whitespace,
throw an
"InvalidCharacterError" exception.
If token is in tokens, run these substeps:
If force is either not passed or is false, then remove token from tokens, run the update steps, and return false.
Otherwise, return true.
Otherwise, run these substeps:
If force is passed and is false, return false.
Otherwise, append token to tokens, run the update steps, and return true.
The stringifier must return the result of the ordered set serializer for tokens.
DOMSettableTokenListinterface DOMSettableTokenList : DOMTokenList {
attribute DOMString value;
};
A DOMSettableTokenList object is equivalent to a
DOMTokenList object without an associated
attribute.
tokenlist . value
Returns the associated set as string.
Can be set, to change the associated set via a string.
The value
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.
As explained in goals this specification is a significant revision of various DOM specifications. This section attempts to enumerate the changes.
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]
MutationEvent, and
MutationNameEvent.
initEvent() rather than after
dispatch.
These are the changes made to the features described in DOM Level 3 Core.
DOMString and
DOMTimeStamp 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:
CDATASection
DOMConfiguration
DOMErrorHandler
DOMImplementationList
DOMImplementationSource
DOMLocator
DOMObject
DOMStringList
DOMUserData
Entity
EntityReference
NamedNodeMap
NameList
Notation
TypeInfo
UserDataHandler
Interface members:
Node
hasAttributes()
attributes
namespaceURI
prefix
localName
isSupported
getFeature()
getUserData()
setUserData()
isSameNode()
Document
createCDATASection()
createAttribute()
createAttributeNS()
createEntityReference()
inputEncoding
xmlEncoding
xmlStandalone
xmlVersion
strictErrorChecking
domConfig
normalizeDocument()
renameNode()
DOMImplementation
getFeature()
Attr
No longer inherits from Node and therefore completely
changed.
Element
getAttributeNode()
getAttributeNodeNS()
setAttributeNode()
removeAttributeNode()
schemaTypeInfo
setIdAttribute()
setIdAttributeNS()
setIdAttributeNode()
DocumentType
entities
notations
internalSubset
Text
isElementContentWhitespace
replaceWholeText()
These are the changes made to the features described in the "Document Object Model Range" chapter of DOM Level 2 Traversal and Range.
RangeException 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.
toString() is now defined through
IDL.
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.
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 Sam 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.