1. Conformance
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The keywords "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 keywords ("must", "should", "may", etc.) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can’t change the behavior by overriding attributes or methods with custom properties or functions in JavaScript.
Unless otherwise stated, string comparisons are done in a case-sensitive manner.
1.1. Dependencies
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
Some of the terms used in this specification are defined in Encoding, Selectors, WEBIDL, XML, and Namespaces in XML. [ENCODING][SELECTORS4][WEBIDL][XML][XML-NAMES]
1.2. Extensibility
Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.
When extensions are needed, the DOM Standard can be updated accordingly, or a new standard can be written that hooks into the provided extensibility hooks for applicable specifications.
2. Terminology
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.
2.1. Trees
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. The root of a tree is any object participating in thattree whose parent is null.
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 children.
The last child of an object is its last child or null if it has no children.
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.
2.2. Strings
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 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z), inclusive, and the corresponding characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z), inclusive, 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), inclusive, 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), inclusive, 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.
2.3. Ordered sets
An ordered set is a list that it must not contain the same item twice.
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.
- Skip ASCII whitespace.
-
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.
- Skip ASCII whitespace.
- Return tokens.
To replace within an ordered set set, given item and replacement, if item or replacement is in set, then replace the first instance of either with replacement and remove all other instances.
Replacing "a" with "c" within the ordered set « "a", "b", "c" » gives « "c", "b" ». Within « "c", "b", "a" » it gives « "c", "b" » as well.
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, if set is non-empty.
2.4. Selectors
To scope-match a selectors string selectors against a node, run these steps:
- Let s be the result of parse a selector selectors. [SELECTORS4]
-
If s is failure, then throw a
SyntaxError
. -
Return the result of evaluate a selector s against node’s root using scoping root node. [SELECTORS4].
Support for namespaces within selectors is not planned and will not be added.
2.5. Namespaces
To validate a qualifiedName, run these steps:
-
If qualifiedName does not match the
Name
production, then throw anInvalidCharacterError
. -
If qualifiedName does not match the
QName
production, then throw aNamespaceError
.
To validate and extract a namespace and qualifiedName, run these steps:
- If namespace is the empty string, set it to null.
- Validate qualifiedName. Rethrow any exceptions.
- Let prefix be null.
- Let localName be qualifiedName.
- If qualifiedName contains a "
:
" (U+003E), then split the string on it and set prefix to the part before and localName to the part after. - If prefix is non-null and namespace is null, then throw a
NamespaceError
. - If prefix is "
xml
" and namespace is not the XML namespace, then throw aNamespaceError
. - If either qualifiedName or prefix is
"
xmlns
" and namespace is not the XMLNS namespace, then throw aNamespaceError
. - If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "
xmlns
", then throw aNamespaceError
. - Return namespace, prefix, and localName.
The HTML namespace is http://www.w3.org/1999/xhtml
.
The SVG namespace is http://www.w3.org/2000/svg
.
The XML namespace is http://www.w3.org/XML/1998/namespace
.
The XMLNS namespace is http://www.w3.org/2000/xmlns/
.
3. Events
3.1. Introduction to "DOM Events"
Throughout the web platform events are dispatched to objects to signal an occurrence, such as network activity or user interaction. These objects implement the EventTarget
interface and can therefore add event listeners to observe events by calling addEventListener():
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 of 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, {capture: 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 event’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
.
3.2. Interface Event
[Constructor
(DOMStringtype
, optional EventIniteventInitDict
), Exposed=(Window,Worker)] interfaceEvent
{ readonly attribute DOMString type; readonly attribute EventTarget? target; readonly attribute EventTarget? currentTarget; sequence<EventTarget> composedPath(); 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(); attribute boolean cancelBubble; void stopImmediatePropagation(); readonly attribute boolean bubbles; readonly attribute boolean cancelable; void preventDefault(); readonly attribute boolean defaultPrevented; readonly attribute boolean composed; [Unforgeable] readonly attribute boolean isTrusted; readonly attribute DOMHighResTimeStamp timeStamp; void initEvent(DOMStringtype
, optional booleanbubbles
, optional booleancancelable
); // historical }; dictionaryEventInit
{ booleanbubbles
= false; booleancancelable
= false; booleancomposed
= false; };
An Event
object is simply named an event. It allows for
signaling that something has occurred, e.g., that an image has completed downloading.
An event has an associated relatedTarget (null or an EventTarget
object). Unless stated otherwise it is null.
Note: Other specifications use relatedTarget to define a relatedTarget
attribute. [UIEVENTS]
An event has an associated path. A path is a
list of tuples, each of which consists of an item (an EventTarget
object), target (null or an EventTarget
object), and a relatedTarget (null or an EventTarget
object). A tuple is formatted as (item, target, relatedTarget). A path is initially the empty list.
Specifications may define retargeting steps for all or some events. The algorithm is passed event, as indicated in the dispatch algorithm below.
- event = new Event(type [, eventInitDict])
-
Returns a new event whose
type
attribute value is set to type. The optional eventInitDict argument allows for setting thebubbles
andcancelable
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 to which event is dispatched.
- event .
currentTarget
-
Returns the object whose event listener’s callback is currently being invoked.
event .
composedPath()
-
Returns the item objects of event’s path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root’s mode is "
closed
" that are not reachable from event’scurrentTarget
. event .
eventPhase
-
Returns the event’s phase, which is one of
,NONE
,CAPTURING_PHASE
, andAT_TARGET
.BUBBLING_PHASE
- event .
stopPropagation()
-
When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.
- event .
stopImmediatePropagation()
-
Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.
- event .
bubbles
-
Returns true or false depending on how event was initialized. True if event 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, and while executing a listener for the event withpassive
set to false, signals to the operation that caused event to be dispatched that it needs to be canceled. - event .
defaultPrevented
-
Returns true if
preventDefault()
was invoked successfully to indicate cancellation, and false otherwise. event .
composed
-
Returns true or false depending on how event was initialized. True if event invokes listeners past a
ShadowRoot
node that is the root of itstarget
attribute value, and false otherwise. event .
isTrusted
-
Returns true if event was dispatched by the user agent, and false otherwise.
- event .
timeStamp
-
Returns the event’s timestamp as the number of milliseconds that measured relative to the time origin.
The type
attribute’s getter must return the value it was initialized to. When an event is created the attribute must be initialized to the empty string.
The target
attribute’s getter and currentTarget
attribute’s getter must return the values they were initialized to. When an event is created the attributes must be initialized to null.
The composedPath()
method, when invoked, must run these steps:
-
Let composedPath be a new empty list.
-
Let currentTarget be context object’s
currentTarget
attribute value. -
For each tuple in context object’s path:
-
If currentTarget is a
Window
object, then:-
If tuple’s item is not a node, or tuple’s item is not from tuple’s item’s shadow-including root, then append tuple’s item to composedPath.
-
-
Otherwise, if currentTarget is a node and tuple’s item is not from currentTarget, or currentTarget is not a node, then append tuple’s item to composedPath.
-
-
Return composedPath.
Note: This algorithm assumes that when the target argument to the dispatch algorithm is not a node, none of the tuples in event argument’s eventual path will contain a node either.
The eventPhase
attribute’s getter 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:
- stop propagation flag
- stop immediate propagation flag
- canceled flag
- in passive listener flag
- composed flag
- initialized flag
- dispatch flag
The stopPropagation()
method, when invoked, must set the context object’s stop propagation flag.
The cancelBubble
attribute’s getter must return true
if context object’s stop propagation flag is set, and false otherwise.
The cancelBubble
attribute’s setter must set context object’s stop propagation flag if the given value is true, and do nothing otherwise.
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.
The preventDefault()
method, when invoked, must set the canceled flag if the cancelable
attribute value is true and the in passive listener flag is unset.
This means there are scenarios where invoking preventDefault()
has no effect. User agents are encouraged to log the precise cause in a developer console, to aid
debugging.
The defaultPrevented
attribute must return true if the canceled flag is set and false otherwise.
The composed
attribute’s getter must return true if context object’s composed flag is set, and false otherwise.
The isTrusted
attribute’s getter must return the value it was initialized to. When an event is created the attribute must be
initialized to false.
Note: isTrusted
is a convenience that indicates whether an event is dispatched by the user agent
(as opposed to using dispatchEvent()
). The sole legacy exception is click()
, which causes
the user agent to dispatch an event whose isTrusted
attribute is initialized to false.
The timeStamp
attribute must return the value it was initialized to.
To initialize an event, with type, bubbles, and cancelable, run these steps:
-
Set the initialized flag.
-
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, when invoked, must run these steps:
-
If context object’s dispatch flag is set, terminate these steps.
-
Initialize the context object with type, bubbles, and cancelable.
Note: As events have constructors initEvent()
is redundant and incapable of setting composed
. It has to be supported for legacy content.
3.3. Interface CustomEvent
[Constructor
(DOMStringtype
, optional CustomEventIniteventInitDict
), Exposed=(Window,Worker)] interfaceCustomEvent
: Event { readonly attribute any detail; void initCustomEvent(DOMStringtype
, optional booleanbubbles
= false, optional booleancancelable
= false, optional anydetail
= null); }; dictionaryCustomEventInit
: EventInit { anydetail
= 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 thedetail
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.
The initCustomEvent(type, bubbles, cancelable, detail)
method, when invoked, must run these steps:
- If context object’s dispatch flag is set, terminate these steps.
- Initialize the context object with type, bubbles, and cancelable.
- Set context object’s
detail
attribute to detail.
3.4. Constructing events
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. -
Initialize event’s
timeStamp
attribute to aDOMHighResTimeStamp
representing the high resolution time from the time origin to the occurrence of the call to the event’s constructor. -
If there is an eventInitDict argument then for each dictionary member present, 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.
To create an event using eventInterface, which must be either Event
or an interface that inherits from
it, and optionally given a Realm realm, run these steps:
-
Create a new object event using eventInterface. If realm is given, use that Realm; otherwise, use the default behavior defined in Web IDL.
-
Set event’s initialized flag.
-
Let defaultEventInitDict be the result of converting the JavaScript value undefined to the dictionary type accepted by eventInterface’s constructor. (This dictionary type will either be
EventInit
or a dictionary that inherits from it.) - For each dictionary member present in defaultEventInitDict, find the attribute on event whose identifier matches the key of the dictionary member and then set the attribute to the default value of that dictionary member.
-
Set event’s
timeStamp
attribute to aDOMHighResTimeStamp
representing the high resolution time from the time origin to the occurrence that the event is signaling. -
Initialize event’s
isTrusted
attribute to true. -
Return event.
Create an event is meant to be used by other specifications which need to separately create and dispatch events, instead of simply firing them. It ensures the event’s attributes are initialized to the correct defaults.
3.5. Defining event interfaces
In general, when defining a new interface that inherits from Event
please always ask feedback from the WHATWG or the
W3C www-dom@w3.org mailing list.
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.
3.6. Interface EventTarget
[Exposed=(Window,Worker)] interfaceEventTarget
{ void addEventListener(DOMStringtype
, EventListener?callback
, optional (AddEventListenerOptions or boolean)options
); void removeEventListener(DOMStringtype
, EventListener?callback
, optional (EventListenerOptions or boolean)options
); boolean dispatchEvent(Eventevent
); }; callback interfaceEventListener
{ voidhandleEvent
(Eventevent
); }; dictionaryEventListenerOptions
{ booleancapture
= false; }; dictionaryAddEventListenerOptions
: EventListenerOptions { booleanpassive
= false; booleanonce
= false; };
The EventTarget
object represents the target to which an event is dispatched when something has occurred.
Each EventTarget
object has an associated list of event listeners.
An event listener can be used to observe a specific event.
An event listener consists of these fields:
- type (a string)
- callback (an
EventListener
) - capture (a boolean, initially false)
- passive (a boolean, initially false)
- once (a boolean, initially false)
- removed (a boolean for bookkeeping purposes, initially false)
Although callback is an EventListener
, as can be seen from the
fields above, an event listener is a broader concept.
Each EventTarget
object also has an associated get the parent algorithm,
which takes an event event, and returns an EventTarget
object. Unless
specified otherwise it returns null.
Note: Nodes, shadow roots, and documents override the get the parent algorithm.
Each EventTarget
object can have an associated activation behavior algorithm. The activation behavior algorithm is passed an event, as indicated in the dispatch algorithm.
This exists because user agents perform certain actions for certain EventTarget
objects, e.g., the area
element, in response to synthetic MouseEvent
events whose type
attribute is click
. Web compatibility prevented it
from being removed and it is now the enshrined way of defining an activation of something. [HTML51]
Each EventTarget
object that has activation behavior, can additionally
have both (not either) a legacy-pre-activation behavior algorithm
and a legacy-canceled-activation behavior algorithm.
These algorithms only exist for checkbox and radio input
elements and
are not to be used for anything else. [HTML51]
- target . addEventListener(type, callback [, options])
-
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.The options argument sets listener-specific options. For compatibility this can be just a boolean, in which case the method behaves exactly as if the value was specified as options’
capture
member.When set to true, options’
capture
member prevents callback from being invoked when the event’seventPhase
attribute value isBUBBLING_PHASE
. When false (or not present), callback will not be invoked when event’seventPhase
attribute value isCAPTURING_PHASE
. Either way, callback will be invoked if event’seventPhase
attribute value isAT_TARGET
.When set to true, options’
passive
member indicates that the callback will not cancel the event by invokingpreventDefault()
. This is used to enable performance optimizations described in §3.7 Observing event listeners.When set to true, options’s
once
member indicates that the callback will only be invoked once after which the event listener will be removed.The event listener is appended to target’s list of event listeners and is not appended if it is a duplicate, i.e., having the same type, callback, and capture values.
- target . removeEventListener(type, callback [, options])
- Remove the event listener in target’s list of event listeners with the same type, callback, and options.
- target . dispatchEvent(event)
- Dispatches a synthetic event event to target and returns true if either event’s
cancelable
attribute value is false or itspreventDefault()
method was not invoked, and false otherwise.
To flatten options, run these steps:
-
Let capture be false.
-
If options is a boolean, set capture to options.
-
If options is a dictionary, then set capture to options’s
capture
. -
Return capture.
To flatten more options, run these steps:
-
Let capture be the result of flattening options.
-
Let once and passive be false.
-
If options is a dictionary, then set passive to options’s
passive
and once to options’sonce
. -
Return capture, passive, and once.
The addEventListener(type, callback, options)
method, when invoked, must run these steps:
-
If context object’s relevant global object is a
ServiceWorkerGlobalScope
object and its associated service worker’s script resource’s has ever been evaluated flag is set, then throw aTypeError
. [SERVICE-WORKERS]To optimize storing the event types allowed for the service worker and to avoid non-deterministic changes to the event listeners, invocation of the method is allowed only during the very first evaluation of the service worker script.
-
If callback is null, then return.
-
Let capture, passive, and once be the result of flattening more options.
-
If context object’s associated list of event listener does not contain an event listener whose type is type, callback is callback, and capture is capture, then append a new event listener to it, whose type is type, callback is callback, capture is capture, passive is passive, and once is once.
The removeEventListener(type, callback, options)
method, when invoked, must run these steps:
-
If context object’s relevant global object is a
ServiceWorkerGlobalScope
object and its associated service worker’s script resource’s has ever been evaluated flag is set, then throw aTypeError
. [SERVICE-WORKERS] -
Let capture be the result of flattening options.
-
If there is an event listener in the associated list of event listeners whose type is type, callback is callback, and capture is capture, then set that event listener’s removed to true and remove it from the associated list of event listeners.
The dispatchEvent(event)
method, when invoked, must run these steps:
-
If event’s dispatch flag is set, or if its initialized flag is not set, throw an "
InvalidStateError
" exception.[WEBIDL] -
Initialize event’s
isTrusted
attribute to false. -
Dispatch the event and return the value that returns.
3.7. Observing event listeners
In general, developers do not expect the presence of an event listener to be observable. The impact of an event listener is determined by its callback. That is, a developer adding a no-op event listener would not expect it to have any side effects.
Unfortunately, some event APIs have been designed such that implementing them efficiently
requires observing event listeners. This can make the presence of listeners observable in
that even empty listeners can have a dramatic performance impact on the behavior of the application.
For example, touch and wheel events which can be used to block asynchronous scrolling. In some cases
this problem can be mitigated by specifying the event to be cancelable
only when there is
at least one non-passive
listener. For example,
non-passive
TouchEvent listeners must block scrolling, but if all
listeners are passive
then scrolling can be allowed to start in parallel by making the TouchEvent uncancelable (so that calls to preventDefault()
are ignored). So code dispatching an event is able to observe the absence
of non-passive
listeners, and use that to clear the cancelable
property of the event being dispatched.
Ideally, any new event APIs are defined such that they do not need this property (use public-script-coord@w3.org for discussion).
3.8. Dispatching events
To dispatch an event to a target, with an optional legacy target override flag, and an optional legacyOutputDidListenersThrowFlag, run these steps:
- Set event’s dispatch flag.
-
Let targetOverride be target, if legacy target override flag is not given, and target’s associated
Document
otherwise. [HTML]Note: legacy target override flag is only used by HTML and only when target is a
Window
object. - Let relatedTarget be the result of invoking retargeting event’s relatedTarget against target if event’s relatedTarget is non-null, and null otherwise.
-
If target is relatedTarget and target is not event’s relatedTarget, then return true.
-
Append (target, targetOverride, relatedTarget) to event’s path.
-
Let isActivationEvent be true, if event is a
MouseEvent
object and event’stype
attribute is "click
", and false otherwise. -
Let activationTarget be target, if isActivationEvent is true and target has activation behavior, and null otherwise.
-
Let parent be the result of invoking target’s get the parent with event.
-
While parent is non-null:
-
Let relatedTarget be the result of invoking retargeting event’s relatedTarget against parent if event’s relatedTarget is non-null, and null otherwise.
-
If target’s root is a shadow-including inclusive ancestor of parent, then:
-
If isActivationEvent is true, event’s
bubbles
attribute is true, activationTarget is null, and parent has activation behavior, then set activationTarget to parent. -
Append (parent, null, relatedTarget) to event’s path.
-
-
Otherwise, if parent and relatedTarget are identical, then set parent to null.
-
Otherwise, set target to parent and then:
-
If isActivationEvent is true, activationTarget is null, and target has activation behavior, then set activationTarget to target.
-
Append (parent, target, relatedTarget) to event’s path.
-
-
If parent is non-null, then set parent to the result of invoking parent’s get the parent with event.
-
-
Set event’s
eventPhase
attribute toCAPTURING_PHASE
. -
If activationTarget is non-null and activationTarget has legacy-pre-activation behavior, then run activationTarget’s legacy-pre-activation behavior.
-
For each tuple in event’s path, in reverse order:
-
Set event’s
target
attribute to the target of the last tuple in event’s path, that is either tuple or preceding tuple, whose target is non-null. -
Set event’s relatedTarget to tuple’s relatedTarget.
-
Run the retargeting steps with event.
-
If tuple’s target is null, then invoke tuple’s item with event and legacyOutputDidListenersThrowFlag if given.
-
-
For each tuple in event’s path, in order:
-
Set event’s
target
attribute to the target of the last tuple in event’s path, that is either tuple or preceding tuple, whose target is non-null. -
Set event’s relatedTarget to tuple’s relatedTarget.
-
Run the retargeting steps with event.
-
If tuple’s target is non-null, then set event’s
eventPhase
attribute toAT_TARGET
. -
Otherwise, set event’s
eventPhase
attribute toBUBBLING_PHASE
. -
If either event’s
eventPhase
attribute isBUBBLING_PHASE
and event’sbubbles
attribute is true or event’seventPhase
attribute isAT_TARGET
, then invoke tuple’s item with event and legacyOutputDidListenersThrowFlag if given.
-
-
Unset event’s dispatch flag, stop propagation flag and stop immediate propagation flag.
-
Set event’s
eventPhase
attribute toNONE
. -
If
target
's root is a shadow root, then set event’starget
attribute to null. -
Set event’s
currentTarget
attribute to null. -
Set event’s path to the empty list.
-
If activationTarget is non-null, then:
-
If event’s canceled flag is unset, then run activationTarget’s activation behavior with event.
-
Otherwise, if activationTarget has legacy-canceled-activation behavior, then run activationTarget’s legacy-canceled-activation behavior.
-
- Return false if event’s canceled flag is set, and true otherwise.
To invoke an object with event and optional legacyOutputDidListenersThrowFlag, run these steps:
-
If event’s stop propagation flag is set, then return.
- Let listeners be a copy of the event listeners associated with the object.
- Initialize event’s
currentTarget
attribute to the object. -
For each event listener in listeners, whose removed is false:
-
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 isCAPTURING_PHASE
and listener’s capture is false, terminate these substeps (and run them for the next event listener). -
If event’s
eventPhase
attribute value isBUBBLING_PHASE
and listener’s capture is true, terminate these substeps (and run them for the next event listener). -
If listener’s once is true, then remove listener from object’s associated list of event listeners.
-
If listener’s passive is true, then set event’s in passive listener flag.
-
Call listener’s callback’s
handleEvent
, with the event passed to this algorithm as the first argument and event’scurrentTarget
attribute value as callback this value. If this throws any exception, then:-
Set legacyOutputDidListenersThrowFlag if given.
The legacyOutputDidListenersThrowFlag is only used by Indexed Database API. [INDEXEDDB]
-
Unset event’s in passive listener flag.
-
If event’s stop immediate propagation flag is set, then return found.
-
3.9. Firing events
To fire an event named e at target, optionally using an eventConstructor, with a description of how IDL attributes are to be initialized, and a legacy target override flag, run these steps:
-
If eventConstructor is not given, then let eventConstructor be
Event
. -
Let event be the result of invoking the initial value of eventConstructor with the argument e.
-
Initialize event’s
isTrusted
attribute to true. -
Initialize any other IDL attributes of event as described in the invocation of this algorithm.
This also allows for the
isTrusted
attribute to be set to false. -
Return the result of dispatching event at target, with legacy target override flag set if set.
Note: 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
at target with its cancelable
attribute initialized to true".
Or, when a custom constructor is required, "fire an event named click
at target using MouseEvent
with its isTrusted
attribute initialized to
false".
Ocassionally the return value is important:
-
Let doAction be the result of firing an event named
like
at target. -
If doAction is true, then …
3.10. Action versus occurrence
An event signifies an occurrence, not an action. Phrased differently, it represents a notification from an algorithm and can be used to influence the future course of that algorithm (e.g., through invoking preventDefault()). Events must not be used as actions or initiators that cause some algorithm to start running. That is not what they are for.
This is called out here specifically because previous iterations of the DOM had a concept of "default actions" associated with events that gave folks all the wrong ideas. Events do not represent or cause actions, they can only be used to influence an ongoing one.
4. Nodes
4.1. Introduction to "The DOM"
In its original sense, "The DOM" is an API for accessing and manipulating documents (in particular, HTML and XML documents). In this specification, the term "document" is used for any markup-based resource, ranging from short static documents to long essays or reports with rich multimedia, as well as to fully-fledged interactive applications.
These documents are presented as a node tree. Some of the nodes in the tree can have children, while others are always 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 of HTML parser, not all ASCII whitespace were turned into Text
nodes, but the general concept is clear. Markup goes in, a tree of nodes comes out.
Note: The most excellent Live DOM Viewer can be used to explore this matter in more detail.
4.2. Node tree
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
orComment
. -
Optionally one
DocumentType
node. -
Zero or more nodes each of which is either
ProcessingInstruction
orComment
. -
Optionally one
Element
node. -
Zero or more nodes each of which is either
ProcessingInstruction
orComment
.
-
DocumentFragment
Element
-
Zero or more nodes each of which is one of
Element
,ProcessingInstruction
,Comment
, orText
. DocumentType
Text
ProcessingInstruction
Comment
-
None.
To determine the length of a node node, switch on node:
DocumentType
-
Zero.
Text
ProcessingInstruction
Comment
-
The number of code units in its data.
- Any other node
-
Its number of children.
A node is considered empty if its length is zero.
4.2.1. Document tree
A document tree is a node tree whose root is a document.
The document element of a document is the element whose parent is that document, if it exists, and null otherwise.
Note: Per the node tree constraints, there can be only one such element.
An element is in a document tree if its root is a document.
An element is in a document if it is in a document tree.
Note: The term in a document is no longer supposed to be used. It indicates that the standard using it has not been updated to account for shadow trees.
4.2.2. Shadow tree
A shadow tree is a node tree whose root is a shadow root.
A shadow root is always attached to another node tree through its host. A shadow tree is therefore never alone. The node tree of a shadow root’s host is sometimes referred to as the light tree.
Note: A shadow tree’s corresponding light tree can be a shadow tree itself.
An element is connected if its shadow-including root is a document.
4.2.2.1. Slots
A shadow tree contains zero or more elements that are slots.
Note: A slot can only be created through HTML’s slot
element.
A slot has an associated name (a string). Unless stated otherwise it is the empty string.
Use these attribute change steps to update a slot’s name:
-
If element is a slot, localName is
name
, and namespace is null, then:-
If value is oldValue, then return.
-
If value is null and oldValue is the empty string, then return.
-
If value is the empty string and oldValue is null, then return.
-
If value is null or the empty string, then set element’s name to the empty string.
-
Otherwise, set element’s name to value.
-
Run assign slotables for a tree with element’s tree.
-
Note: The first slot in a shadow tree, in tree order, whose name is the empty string, is sometimes known as the "default slot".
A slot has an associated assigned nodes (a list of slotables). Unless stated otherwise it is empty.
4.2.2.2. Slotables
Element
and Text
nodes are slotables.
Note: A slot can be a slotable.
A slotable has an associated name (a string). Unless stated otherwise it is the empty string.
Use these attribute change steps to update a slotable’s name:
-
If localName is
slot
and namespace is null, then:-
If value is oldValue, then return.
-
If value is null and oldValue is the empty string, then return.
-
If value is the empty string and oldValue is null, then return.
-
If value is null or the empty string, then set element’s name to the empty string.
-
Otherwise, set element’s name to value.
-
If element is assigned, then run assign slotables for element’s assigned slot.
-
Run assign a slot for element.
-
A slotable has an associated assigned slot (null or a slot). Unless stated otherwise it is null. A slotable is assigned if its assigned slot is non-null.
4.2.2.3. Finding slots and slotables
To find a slot for a given slotable slotable and an optional open flag (unset unless stated otherwise), run these steps:
-
If slotable’s parent is null, then return null.
-
Let shadow be slotable’s parent’s shadow root.
-
If shadow is null, then return null.
-
If the open flag is set and shadow’s mode is not "
open
", then return null. -
Return the first slot in shadow’s tree whose name is slotable’s name, if any, and null otherwise.
To find slotables for a given slot slot, run these steps:
-
Let result be an empty list.
-
If slot’s root is not a shadow root, then return result.
-
For each slotable child of host, slotable, in tree order:
-
Let foundSlot be the result of finding a slot given slotable.
-
If foundSlot is slot, then append slotable to result.
-
-
Return result.
To find flattened slotables for a given slot slot, run these steps:
-
Let result be an empty list.
-
If slot’s root is not a shadow root, then return result.
-
Let slotables be the result of finding slotables given slot.
-
If slotables is the empty list, then append each slotable child of slot, in tree order, to slotables.
-
For each node in slotables:
-
If node is a slot whose root is a shadow root, then:
-
Let temporaryResult be the result of finding flattened slotables given node.
-
Append each slotable in temporaryResult, in order, to result.
-
-
Otherwise, append node to result.
-
-
Return result.
4.2.2.4. Assigning slotables and slots
To assign slotables for a slot slot, run these steps:
-
Let slotables be the result of finding slotables for slot.
-
If slotables and slot’s assigned nodes are not identical, then run signal a slot change for slot.
-
Set slot’s assigned nodes to slotables.
-
For each slotable in slotables, set slotable’s assigned slot to slot.
To assign slotables for a tree, given a tree tree, run assign slotables for each slot slot in tree, in tree order.
To assign a slot, given a slotable slotable, run these steps:
-
Let slot be the result of finding a slot with slotable.
-
If slot is non-null, then run assign slotables for slot.
4.2.2.5. Signaling slot change
Each unit of related similar-origin browsing contexts has a signal slot list (a list of slots). Unless stated otherwise it is empty. [HTML]
To signal a slot change, for a slot slot, run these steps:
-
If slot is not in unit of related similar-origin browsing contexts' signal slot list, append slot to unit of related similar-origin browsing contexts' signal slot list.
4.2.3. Mutation algorithms
To ensure pre-insertion validity of a node into a parent before a child, run these steps:
-
If parent is not a
Document
,DocumentFragment
, orElement
node, throw aHierarchyRequestError
. -
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
. -
If node is not a
DocumentFragment
,DocumentType
,Element
,Text
,ProcessingInstruction
, orComment
node, throw aHierarchyRequestError
. -
If either node is a
Text
node and parent is a document, or node is a doctype and parent is not a document, throw aHierarchyRequestError
. -
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 aText
node child.Otherwise, if node has one
element
child and either parent has anelement
child, child is a doctype, or child is not null and a doctype is following child. element
-
parent has an
element
child, child is a doctype, or child is not null and a doctype is following child. - doctype
-
parent has a doctype child, child is non-null and an element is preceding child, or child is null and parent has an
element
child.
To pre-insert a node into a parent before a child, run these steps:
-
Ensure pre-insertion validity of node into parent before 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.
Specifications may define insertion steps for all or some nodes. The algorithm is passed newNode, as indicated in the insert algorithm below.
To insert a node into a parent before a child with an optional suppress observers flag, run these steps:
-
Let count be the number of children of node if it is a
DocumentFragment
node, and one otherwise. -
If child is non-null, run these substeps:
-
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, remove its children with the suppress observers flag set. -
If node is a
DocumentFragment
node, queue a mutation record of "childList
" for node with removedNodes nodes.Note: This step intentionally does not pay attention to the suppress observers flag.
-
Let previousSibling be child’s previous sibling or parent’s last child if child is null.
-
For each newNode in nodes, in tree order, run these substeps:
-
Insert newNode into parent before child or at the end of parent if child is null.
-
Run the insertion steps with newNode.
-
If parent is a shadow host and node is a slotable, then assign a slot for node.
-
If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.
-
Run assign slotables for a tree with node’s tree.
-
For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order:
-
Run the insertion steps with inclusiveDescendant.
-
If inclusiveDescendant is connected, then:
-
If inclusiveDescendant is custom, then enqueue a custom element callback reaction with inclusiveDescendant, callback name "
connectedCallback
", and an empty argument list. -
Otherwise, try to upgrade inclusiveDescendant.
If this successfully upgrades inclusiveDescendant, its
connectedCallback
will be enqueued automatically during the upgrade an element algorithm.
-
-
-
-
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.
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
, orElement
node, throw aHierarchyRequestError
. -
If node is a host-including inclusive ancestor of parent, throw a
HierarchyRequestError
. -
If child’s parent is not parent, throw a
NotFoundError
. -
If node is not a
DocumentFragment
,DocumentType
,Element
,Text
,ProcessingInstruction
, orComment
node, throw aHierarchyRequestError
. -
If either node is a
Text
node and parent is a document, or node is a doctype and parent is not a document, throw aHierarchyRequestError
. -
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.
- element
-
parent has an element child that is not child or a doctype is following child.
- doctype
- parent has a doctype child that is not child, or an element is preceding child.
Note: 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.
-
Let previousSibling be child’s previous sibling.
-
Adopt node into parent’s node document.
- Let removedNodes be the empty list.
-
If child’s parent is not null, run these substeps:
-
Set removedNodes to a list solely containing child.
-
Remove child from its parent with the suppress observers flag set.
Note: The above can only be false if child is node.
-
- Let nodes be node’s children if node is a
DocumentFragment
node, and a list containing solely node otherwise. -
Insert node into parent before reference child with the suppress observers flag set.
-
Queue a mutation record of "
childList
" for target parent with addedNodes nodes, removedNodes a list solely containing child, nextSibling reference child, and previousSibling previousSibling. -
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, in tree order, 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.
Note: This algorithm does not make any checks with regards to the node tree constraints. Specification authors need to use it wisely.
To pre-remove a child from a parent, run these steps:
-
If child’s parent is not parent, throw a
NotFoundError
. -
Remove child from parent.
-
Return child.
Specifications may define removing steps for all or some nodes. The algorithm is passed removedNode, and optionally oldParent, as indicated in the remove algorithm below.
To remove a node from a parent with an optional suppress observers flag set, run these steps:
-
Let index be node’s index.
-
For each range whose start node is an inclusive descendant of node, set its start to (parent, index).
-
For each range whose end node is an inclusive 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.
-
For each
NodeIterator
object iterator whose root’s node document is node’s node document, run theNodeIterator
pre-removing steps given node and iterator. -
Let oldPreviousSibling be node’s previous sibling.
-
Let oldNextSibling be node’s next sibling.
-
Remove node from its parent.
-
If node is assigned, then run assign slotables for node’s assigned slot.
-
If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.
-
If node has an inclusive descendant that is a slot, then:
-
Run assign slotables for a tree with parent’s tree.
-
Run assign slotables for a tree with node’s tree.
-
-
Run the removing steps with node and parent.
-
If node is custom, then enqueue a custom element callback reaction with node, callback name "
disconnectedCallback
", and an empty argument list.It is intentional for now that custom elements do not get parent passed. This might change in the future if there is a need.
-
For each shadow-including descendant descendant of node, in shadow-including tree order, run these substeps:
-
Run the removing steps with descendant.
-
If descendant is custom, then enqueue a custom element callback reaction with descendant, callback name ""
disconnectedCallback
", and an empty argument list.
-
-
For each inclusive ancestor inclusiveAncestor of node, if inclusiveAncestor has any registered observers whose options'
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. -
If suppress observers flag is unset, queue a mutation record of "
childList
" for parent with removedNodes a list solely containing node, nextSibling oldNextSibling, and previousSibling oldPreviousSibling.
4.2.4. Interface NonElementParentNode
Note: Web compatibility prevents the getElementById()
method from being exposed on elements (and therefore on ParentNode
).
[NoInterfaceObject, Exposed=Window] interfaceNonElementParentNode
{ Element? getElementById(DOMStringelementId
); }; 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, when invoked, 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.
4.2.5. Interface DocumentOrShadowRoot
[NoInterfaceObject,
Exposed=Window]
interface DocumentOrShadowRoot
{
};
Document implements DocumentOrShadowRoot;
ShadowRoot implements DocumentOrShadowRoot;
Note: The DocumentOrShadowRoot
interface is expected to be used by other
standards that want to define APIs shared between document and shadow roots.
4.2.6. Interface ParentNode
ParentNode
To convert nodes into a node, given nodes and document, run these steps:
- Let node be null.
- Replace each string in nodes with a new
Text
node whose data is the string and node document is document. - If nodes contains one node, set node to that node.
- Otherwise, set node to a new
DocumentFragment
whose node document is document, and then append each node in nodes, if any, to it. - Return node.
[NoInterfaceObject, Exposed=Window] interfaceParentNode
{ [SameObject] readonly attribute HTMLCollection children; readonly attribute Element? firstElementChild; readonly attribute Element? lastElementChild; readonly attribute unsigned long childElementCount; [CEReactions, Unscopable] void prepend((Node or DOMString)...nodes
); [CEReactions, Unscopable] void append((Node or DOMString)...nodes
); Element? querySelector(DOMStringselectors
); [NewObject] NodeList querySelectorAll(DOMStringselectors
); }; 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 . prepend(nodes)
-
Inserts nodes before the first child of node, while replacing strings in nodes with equivalent
Text
nodes.Throws a
HierarchyRequestError
if the constraints of the node tree are violated. node . append(nodes)
-
Inserts nodes after the last child of node, while replacing strings in nodes with equivalent
Text
nodes.Throws a HierarchyRequestError if the constraints of the node tree are violated.
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’s getter must return an HTMLCollection
collection rooted at the context object matching only element children.
The firstElementChild
attribute’s getter must return the first child that is an element, and null otherwise.
The lastElementChild
attribute’s getter must return the last child that is an element, and null otherwise.
The childElementCount
attribute’s getter must return the number of children of the context object that are elements.
The prepend(nodes)
method, when invoked, must run these steps:
-
Let node be the result of converting nodes into a node given nodes and context object’s node document.
-
Pre-insert node into context object before the context object’s first child.
The append(nodes)
method, when invoked, must run these steps:
-
Let node be the result of converting nodes into a node given nodes and context object’s node document.
-
Append node to context object.
The querySelector(selectors)
method, when invoked, 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, when invoked, must return the static result of running scope-match a selectors string selectors against the context object.
4.2.7. Interface NonDocumentTypeChildNode
Note: Web compatibility prevents the previousElementSibling
and nextElementSibling
attributes from being exposed on doctypes (and therefore on ChildNode
).
[NoInterfaceObject, Exposed=Window] interfaceNonDocumentTypeChildNode
{ 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’s getter must return the first preceding sibling that is an element, and null otherwise.
The nextElementSibling attribute’s getter must return the first following sibling that is an element, and null otherwise.
4.2.8. Interface ChildNode
[NoInterfaceObject, Exposed=Window] interfaceChildNode
{ [CEReactions, Unscopable] void before((Node or DOMString)...nodes
); [CEReactions, Unscopable] void after((Node or DOMString)...nodes
); [CEReactions, Unscopable] void replaceWith((Node or DOMString)...nodes
); [CEReactions, Unscopable] void remove(); }; DocumentType implements ChildNode; Element implements ChildNode; CharacterData implements ChildNode;
node . before(nodes)
-
Inserts nodes just before node, while replacing strings in nodes with equivalent
Text
nodes.Throws a
HierarchyRequestError
if the constraints of the node tree are violated. node . after(nodes)
-
Inserts nodes just after node, while replacing strings in nodes with equivalent
Text
nodes.Throws a
HierarchyRequestError
if the constraints of the node tree are violated. node . replaceWith(nodes)
-
Replaces node with nodes, while replacing strings in nodes with equivalent
Text
nodes.Throws a
HierarchyRequestError
if the constraints of the node tree are violated. - node .
remove()
-
Removes node.
The before(nodes)
method, when invoked,
must run these steps:
-
Let parent be context object’s parent.
-
If parent is null, then return.
-
Let viablePreviousSibling be context object’s first preceding sibling not in nodes, and null otherwise.
-
Let node be the result of converting nodes into a node, given nodes and context object’s node document.
-
If viablePreviousSibling is null, set it to parent’s first child, and to viablePreviousSibling’s next sibling otherwise.
-
Pre-insert node into parent before viablePreviousSibling.
The after(nodes)
method, when invoked, must run these steps:
-
Let parent be context object’s parent.
-
If parent is null, then return.
-
Let viableNextSibling be context object’s first following sibling not in nodes, and null otherwise.
-
Let node be the result of converting nodes into a node, given nodes and context object’s node document.
-
Pre-insert node into parent before viableNextSibling.
The replaceWith(nodes)
method, when invoked, must run these steps:
-
Let parent be context object’s parent.
-
If parent is null, then return.
-
Let viableNextSibling be context object’s first following sibling not in nodes, and null otherwise.
-
Let node be the result of converting nodes into a node, given nodes and context object’s node document.
-
If context object’s parent is parent, replace the context object with node within parent.
Context object could have been inserted into node.
-
Otherwise, pre-insert node into parent before viableNextSibling.
The remove()
method, when invoked, 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.
4.2.9. Interface Slotable
[NoInterfaceObject,
Exposed=Window]
interface Slotable
{
readonly attribute HTMLSlotElement? assignedSlot;
};
Element implements Slotable;
Text implements Slotable;
The assignedSlot
attribute’s getter must return
the result of find a slot given context object and with the open flag set.
4.2.10. Old-style collections: NodeList
and HTMLCollection
NodeList
HTMLCollection
A collection is an object that represents a lists of DOM nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.
If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.
When a collection is created, a filter and a root are associated with it.
The collection then represents a view of the subtree rooted at the collection’s root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.
4.2.10.1. Interface NodeList
A NodeList
object is a collection of nodes.
[Exposed=Window] interfaceNodeList
{ getter Node? item(unsigned longindex
); readonly attribute unsigned long length; iterable<Node>; };
- collection .
length
-
Returns the number of nodes in the collection.
- element = collection .
item(index)
- element = collection[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’s getter 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.
4.2.10.2. Interface HTMLCollection
[Exposed=Window] interfaceHTMLCollection
{ readonly attribute unsigned long length; getter Element? item(unsigned longindex
); getter Element?namedItem
(DOMStringname
); };
An HTMLCollection
object is a collection of elements.
Note: HTMLCollection
is an historical artifact we cannot rid the web of.
While developers are of course welcome to keep using it, new API standard designers ought not to use
it (use sequence<T>
in IDL instead).
- collection .
length
-
Returns the number of elements in the collection.
- element = collection .
item(index)
- element = collection[index]
-
Returns the element with index index from the collection. The elements are sorted in tree order.
- element = collection .
namedItem(name)
- element = collection[name]
-
Returns the first element with ID or name namefrom the collection.
The object’s supported property indices are the numbers in the range zero to one less than the number of elements represented by the collection. If there are no such elements, then there are no supported property indices.
The length
attribute’s getter must return the number of nodes represented by the collection.
The item(index)
method, when invoked, must return the indexth element in the collection. If there is no indexth element in the collection, then the method, when invoked, must return null.
The supported property names 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 not 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’sname
attribute value to result.
-
-
Return result.
The namedItem(key)
method, when invoked, must run these steps:
- If key is the empty string, return null.
-
Return the first element in the collection for which at least one of the following is true:
- it has an ID which is key;
- it is in the HTML namespace and has a
name
attribute whose value is key;
or null if there is no such element.
4.3. Mutation observers
Each unit of related similar-origin browsing contexts has a mutation observer compound microtask queued flag, which is initially unset,
and an associated list of MutationObserver
objects, which is initially empty.
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' list of
objects.MutationObserver
-
Let signalList be a copy of unit of related similar-origin browsing contexts' signal slot list.
-
Empty unit of related similar-origin browsing contexts' signal slot list.
-
For each
MutationObserver
object mo in notify list, execute a compound microtask subtask to run these steps:-
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, call mo’s callback with queue as first argument, and mo (itself) as second argument and callback this value. If this throws an exception, report the exception.
-
-
For each slot slot in signalList, in order, fire an event named
slotchange
, with itsbubbles
attribute set to true, at slot.
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.
Note: Transient registered observers are used to track
mutations within a given node’s descendants after node has been
removed so they do not get lost when subtree
is set to true on node’s parent.
4.3.1. Interface MutationObserver
[Constructor(MutationCallbackcallback
), Exposed=Window] interfaceMutationObserver
{ void observe(Nodetarget
, optional MutationObserverInitoptions
); void disconnect(); sequence<MutationRecord> takeRecords(); }; callbackMutationCallback
= void (sequence<MutationRecord>mutations
, MutationObserverobserver
); dictionaryMutationObserverInit
{ booleanchildList
= false; booleanattributes
; booleancharacterData
; booleansubtree
= false; booleanattributeOldValue
; booleancharacterDataOldValue
; 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 ofMutationRecord
objects as first argument and the constructedMutationObserver
object as second argument. It is invoked after nodes registered with theobserve()
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/orattributeFilter
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' list of MutationObserver
objects, and then return it.
The observe(target, options)
method, when invoked, must run these steps:
-
If either options’
attributeOldValue
orattributeFilter
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 none of options’
childList
,attributes
, andcharacterData
is true, throw aTypeError
. -
If options’
attributeOldValue
is true and options’attributes
is false, throw a JavaScriptTypeError
. -
If options’
attributeFilter
is present and options’attributes
is false, throw a JavaScriptTypeError
. -
If options’
characterDataOldValue
is true and options’characterData
is false, throw a JavaScriptTypeError
. -
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, when invoked, 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, when invoked, must return a copy of the record queue and then empty the record queue.
4.3.2. Queuing a mutation record
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, run these substeps:
-
If none of the following are true
- node is not target and options’
subtree
is false - type is "
attributes
" and options’attributes
is false - type is "
attributes
", options’attributeFilter
is present, and options’attributeFilter
does not contain name or namespace is non-null - type is "
characterData
" and options’characterData
is false - type is "
childList
" and options’childList
is false
then run these subsubsteps:
-
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’attributeOldValue
is true, or type is "characterData
" and options’characterDataOldValue
is true, set the paired string of registered observer’s observer in interested observers to oldValue.
- node is not target and options’
-
-
Then, for each observer in interested observers:
-
Let record be a new
MutationRecord
object with itstype
set to type andtarget
set to target. -
If name and namespace are given, set record’s
attributeName
to name, and record’sattributeNamespace
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.
-
4.3.3. Interface MutationRecord
[Exposed=Window]
interface MutationRecord
{
readonly attribute DOMString type;
[SameObject] 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 aCharacterData
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 theCharacterData
node. For "childList
", it is the node whose children changed. - record .
addedNodes
- record .
removedNodes
- record .
-
Return the nodes added and removed respectively.
- record .
previousSibling
- record .
nextSibling
- record .
-
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
attribute’s getter and target
attribute’s getter must return the values they were initialized to.
The addedNodes
attribute’s getter and removedNodes
attribute’s getter 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
attribute’s getter, nextSibling
attribute’s getter, attributeName
attribute’s gettr, attributeNamespace
attribute’s getter, and oldValue
attribute’s getter must return the values they were initialized to. Unless stated otherwise, when a MutationRecord
object is created, they must be initialized to null.
4.3.4. Garbage collection
Nodes have a strong reference to registered observers in their list of registered observers.
Registered observers in a node’s list of registered observers have a weak reference to the node.
4.4. Interface Node
[Exposed=Window] interfaceNode
: EventTarget { const unsigned shortELEMENT_NODE
= 1; const unsigned shortATTRIBUTE_NODE
= 2; const unsigned shortTEXT_NODE
= 3; const unsigned shortCDATA_SECTION_NODE
= 4; const unsigned shortENTITY_REFERENCE_NODE
= 5; // historical const unsigned shortENTITY_NODE
= 6; // historical const unsigned shortPROCESSING_INSTRUCTION_NODE
= 7; const unsigned shortCOMMENT_NODE
= 8; const unsigned shortDOCUMENT_NODE
= 9; const unsigned shortDOCUMENT_TYPE_NODE
= 10; const unsigned shortDOCUMENT_FRAGMENT_NODE
= 11; const unsigned shortNOTATION_NODE
= 12; // historical readonly attribute unsigned short nodeType; readonly attribute DOMString nodeName; readonly attribute USVString 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; [CEReactions] attribute DOMString? nodeValue; [CEReactions] attribute DOMString? textContent; [CEReactions] void normalize(); [CEReactions, NewObject] Node cloneNode(optional booleandeep
= false); boolean isEqualNode(Node?other
); const unsigned shortDOCUMENT_POSITION_DISCONNECTED
= 0x01; const unsigned shortDOCUMENT_POSITION_PRECEDING
= 0x02; const unsigned shortDOCUMENT_POSITION_FOLLOWING
= 0x04; const unsigned shortDOCUMENT_POSITION_CONTAINS
= 0x08; const unsigned shortDOCUMENT_POSITION_CONTAINED_BY
= 0x10; const unsigned shortDOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
= 0x20; unsigned short compareDocumentPosition(Nodeother
); boolean contains(Node?other
); DOMString? lookupPrefix(DOMString?namespace
); DOMString? lookupNamespaceURI(DOMString?prefix
); boolean isDefaultNamespace(DOMString?namespace
); [CEReactions] Node insertBefore(Nodenode
, Node?child
); [CEReactions] Node appendChild(Nodenode
); [CEReactions] Node replaceChild(Nodenode
, Nodechild
); [CEReactions] Node removeChild(Nodechild
); };
Note: 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.
Note: A node’s node document can be changed by the adopt algorithm.
A node’s get the parent algorithm, given an event, returns the node’s assigned slot, if node is assigned, and node’s parent otherwise.
- node .
nodeType
-
Returns the type of node, represented by a number from the following list:
Node
.ELEMENT_NODE
(1)- node is an element.
Node
.ATTRIBUTE_NODE
(2)- node is an attribute.
Node
.TEXT_NODE
(3)- node is a
Text
node. Node
.CDATA_SECTION_NODE
(4)- node is a
CDATASection
node. Node
.PROCESSING_INSTRUCTION_NODE
(7)- node is a
ProcessingInstruction
node. Node
.COMMENT_NODE
(8)- node is a
Comment
node. Node
.DOCUMENT_NODE
(9)- node is a document.
Node
.DOCUMENT_TYPE_NODE
(10)- node is a doctype.
Node
.DOCUMENT_FRAGMENT_NODE
(11)- node is a
DocumentFragment
node.
- node .
nodeName
-
Returns a string appropriate for the type of node, as follows:
Element
- Its
tagName
attribute value. Attr
- Its
qualified name
. Text
- "
#text
". CDATASection
- "
#cdata-section
". ProcessingInstruction
- Its target.
Comment
- "
#comment
". Document
- "
#document
". DocumentType
- Its name.
DocumentFragment
- "
#document-fragment
".
The nodeType
attribute’s getter, when invoked, must return the first matching statement, switching on the context object:
Element
- ELEMENT_NODE (1);
Attr
- ATTRIBUTE_NODE (2);
Text
- TEXT_NODE (3);
CDATASection
- CDATA_SECTION_NODE (4);
ProcessingInstruction
- PROCESSING_INSTRUCTION_NODE (7);
Comment
- COMMENT_NODE (8);
Document
- DOCUMENT_NODE (9);
DocumentType
- DOCUMENT_TYPE_NODE (10);
DocumentFragment
- DOCUMENT_FRAGMENT_NODE (11).
The nodeName
attribute’s getter must return the first matching statement, switching on the context object:
Element
-
Its
tagName
attribute value. Attr
- Its
qualified name
. Text
-
"
#text
". CDATASection
- "
#cdata-section
". ProcessingInstruction
-
Its target.
Comment
-
"
#comment
". Document
-
"
#document
". DocumentType
-
Its name.
DocumentFragment
-
"
#document-fragment
".
- node .
baseURI
-
Returns node’s node document’s document base URL.
The baseURI
attribute’s getter must return node document’s document 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’s getter must return null, if the context object is a document, and the context object’s node document otherwise.
Note: The node document of a document is that document itself. All nodes have a document at all times.
The parentNode
attribute’s getter must return the context object’s parent.
Note: An Attr
node has no parent.
The parentElement
attribute’s getter must return the context object’s parent element.
The hasChildNodes()
method, when invoked, must return true if the context object has children, and false otherwise.
The childNodes
attribute’s getter must return a NodeList
rooted at the context object matching only children.
The firstChild
attribute’s getter must return the context object’s first child.
The lastChild
attribute’s getter must return the context object’s last child.
The previousSibling
attribute’s getter must return the context object’s previous sibling.
Note: An Attr
node has no siblings.
The nextSibling
attribute’s getter must return the context object’s next sibling.
The nodeValue
attribute’s getter must return the following, depending on the context object:
Attr
Text
Comment
ProcessingInstruction
-
The context object’s data.
- Any other node
-
Null.
The nodeValue
attribute’s setter must, 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:
Attr
-
Set an existing attribute value with context object and new value.
Text
Comment
ProcessingInstruction
-
Replace data with node context object, offset 0, count context object’s length, and data new value.
- Any other node
-
Do nothing.
The textContent
attribute’s getter must return the following, switching on context object:
DocumentFragment
Element
-
The concatenation of data of all the
Text
node descendants of the context object, in tree order. Attr
Text
ProcessingInstruction
Comment
-
The context object’s data.
- Any other node
-
Null.
The textContent
attribute’s setter must, 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.
-
Attr
-
Set an existing attribute value with context object and new value.
Text
ProcessingInstruction
Comment
-
Replace data with node context object, offset 0, count context object’s length, and data new value.
- Any other node
-
Do nothing.
node .
normalize()
-
Removes empty exclusive
Text
nodes and concatenates the data of remaining contiguous exclusiveText
nodes into the first of their nodes.
The normalize()
method, when invoked, must run these steps for each descendant exclusive Text
node node of context object:
- Let length be node’s length.
- If length is zero, then remove node and continue with the next exclusive
Text
node, if any. - Let data be the concatenation of the data of node’s contiguous exclusive
Text
nodes (excluding itself), in tree order. - Replace data with node node, offset length, count 0, and data data.
- Let currentNode be node’s next sibling.
-
While currentNode is an exclusive
Text
node:-
For each range whose start node is currentNode, add length to its start offset and set its start node to node.
-
For each range whose end node is currentNode, add length to its end offset and set its end node to node.
-
For each range whose start node is currentNode’s parent and start offset is currentNode’s index, set its start node to node and its start offset to length.
-
For each range whose end node is currentNode’s parent and end offset is currentNode’s index, set its end node to node and its end offset to length.
-
Add currentNode’s length to length.
-
Set currentNode to its next sibling.
-
- Remove node’s contiguous exclusive
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 an optional clone children flag, as indicated in the clone algorithm.
Note: 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, with an optional document and clone children flag, run these steps:
-
If document is not given, let document be node’s node document.
-
If node is an element, then:
- let copy be a node that implements the same interfaces as node.
-
Set copy’s local name, namespace, namespace prefix, to those of node. The synchronous custom elements flag should be unset.
-
For each attribute in node’s attribute list, in order, run these substeps:
-
Otherwise, let copy be a node that implements the same interfaces as node, and fulfills these additional requirements, switching on node:
Document
-
Set copy’s encoding, content type, URL, origin, type, and mode, to those of node.
DocumentType
-
Set copy’s name, public ID, and system ID, to those of node.
Attr
-
Set copy’s namespace, namespace prefix, local name, and value, to those of node.
Text
Comment
- Set copy’s data, to that of node.
ProcessingInstruction
- Set copy’starget and data to those of node.
- Any other node
-
—
-
Set copy’s node document and document to copy, if copy is a document, and set copy’s node document to document otherwise.
-
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, when
invoked, must run these steps:
-
If context object is a shadow root, then throw a
NotSupportedError
. -
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.
Attr
-
Its namespace, local name, and value.
ProcessingInstruction
Text
Comment
-
Its data.
- Any other node
-
—
-
If A is an element, each attribute in its attribute list has an attribute that equals 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(other)
method, when invoked, must return true if other is not null and context object equals other, 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)- Set when node and other are not in the same tree.
Node
. DOCUMENT_POSITION_PRECEDING (2)- Set when other is preceding node.
Node
. DOCUMENT_POSITION_FOLLOWING (4)- Set when other is following node.
Node
. DOCUMENT_POSITION_CONTAINS (8)- Set when other is an ancestor of node.
Node
. DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)- Set when other is a descendant of node.
- 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, when invoked, must run these steps:
-
If context object is other, then return zero.
-
Let node1 be other and node2 be context object.
-
Let attr1 and attr2 be null.
-
If node1 is an attribute, then set attr1 to node1 and node1 to attr1’s element.
-
If node2 is an attribute, then:
-
Set attr2 to node2 and node2 to attr2’s element.
-
If attr1 and node1 are non-null, and node2 is node1, then:
-
For each attribute attr in node2’s attribute list:
-
If attr equals attr1, then return the result of adding
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
andDOCUMENT_POSITION_PRECEDING
. -
If attr equals attr2, then return the result of adding
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
andDOCUMENT_POSITION_FOLLOWING
.
-
-
-
-
If node1 or node2 is null, or node1’s root is not node2’s root, then return the result of adding
DOCUMENT_POSITION_DISCONNECTED
,DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
, and eitherDOCUMENT_POSITION_PRECEDING
orDOCUMENT_POSITION_FOLLOWING
, with the constraint that this is to be consistent, together.Note: Whether to return
DOCUMENT_POSITION_PRECEDING
orDOCUMENT_POSITION_FOLLOWING
is typically implemented via pointer comparison. In JavaScript implementations a cachedMath.random()
value can be used. -
If node1 is an ancestor of node2 and attr1 is null, or node1 is node2 and attr2 is non-null, then return the result of adding
DOCUMENT_POSITION_CONTAINS
toDOCUMENT_POSITION_PRECEDING
. -
If node1 is a descendant of node2 and attr2 is null, or node1 is node2 and attr1 is non-null, then return the result of adding
DOCUMENT_POSITION_CONTAINED_BY
toDOCUMENT_POSITION_FOLLOWING
. -
If node1 is preceding node2, then return
DOCUMENT_POSITION_PRECEDING
.Note: Due to the way attributes are handled in this algorithm this results in a node’s attributes counting as preceding that node’s children, despite attributes not participating in a tree.
-
Return
DOCUMENT_POSITION_FOLLOWING
.
The contains(other)
method, when invoked, must return true if other is an inclusive descendant of 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, then 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, then return the result of running locate a namespace prefix on that element using namespace.
-
Return null.
To locate a namespace for a node using prefix switch on node:
Element
-
-
If its namespace is not null and its namespace prefix is prefix, then 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
", then return its value if it is not the empty string, and null otherwise. -
If its parent element is null, then return null.
-
Return the result of running locate a namespace on its parent element using prefix.
-
Document
-
-
If its document element is null, then return null.
-
Return the result of running locate a namespace on its document element using prefix.
-
DocumentType
DocumentFragment
-
Return null.
Attr
-
-
If its element is null, then return null.
-
Return the result of running locate a namespace on its element using prefix.
-
- Any other node
-
-
If its parent element is null, then return null.
-
Return the result of running locate a namespace on its parent element using prefix.
-
The lookupPrefix(namespace)
method, when invoked, must run these steps:
-
If namespace is null or the empty string, then return null.
-
Switch on the context object:
Element
-
Return the result of locating a namespace prefix for it using namespace.
Document
-
Return the result of locating a namespace prefix for its document element, if its document element is non-null, and null otherwise.
DocumentType
DocumentFragment
-
Return null.
Attr
-
Return the result of locating a namespace prefix for its element, if its element is non-null, and null otherwise.
- Any other node
-
Return the result of locating a namespace prefix for its parent element, if its parent element is non-null, and null otherwise.
The lookupNamespaceURI(prefix)
method, when invoked, must run these steps:
-
If prefix is the empty string, then set it to null.
-
Return the result of running locate a namespace for the context object using prefix.
The isDefaultNamespace(namespace)
method, when invoked, must run these steps:
-
If namespace is the empty string, then set it to null.
-
Let defaultNamespace be the result of running locate a namespace for context object using null.
-
Return true if defaultNamespace is the same as namespace, and false otherwise.
The insertBefore(node, child)
method, when invoked, must return the result of pre-inserting node into context object before child.
The appendChild(node)
method, when invoked, must return the result of appending node to context object.
The replaceChild(node, child)
method, when invoked, must return the result of replacing child with node within context object.
The removeChild(child)
method, when invoked, must return the result of pre-removing child from 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 aHTMLCollection
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 the following descendant elements:- Whose namespace is the HTML namespace and whose local name is localName converted to ASCII lowercase.
- Whose namespace is not the HTML namespace and whose local name is localName.
-
Otherwise, return a
HTMLCollection
rooted at root, whose filter matches descendant elements whose local name is localName.
When invoked with the same argument, and as long as root’s node document’s type has not changed,
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 aHTMLCollection
rooted at root, whose filter matches descendant elements. -
Otherwise, if namespace is "
*
" (U+002A), return aHTMLCollection
rooted at root, whose filter matches descendant elements whose local name is localName. -
Otherwise, if localName is "
*
" (U+002A), return aHTMLCollection
rooted at root, whose filter matches descendant elements whose namespace is namespace. -
Otherwise, return a
HTMLCollection
rooted at root, whose filter matches descendant 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 descendant elements that have all their classes in classes.The comparisons for the classes must be done in an ASCII case-insensitive manner if root’s node document’s mode is "
quirks
", 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.
4.5. Interface Document
[Constructor, Exposed=Window] interfaceDocument
: Node { [SameObject] readonly attribute DOMImplementation implementation; readonly attribute USVString URL; readonly attribute USVString documentURI; readonly attribute USVString origin; readonly attribute DOMString compatMode; readonly attribute DOMString characterSet; readonly attribute DOMStringcharset
; // for legacy use, alias of .characterSet readonly attribute DOMStringinputEncoding
; // for legacy use, alias of .characterSet readonly attribute DOMString contentType; readonly attribute DocumentType? doctype; readonly attribute Element? documentElement; HTMLCollection getElementsByTagName(DOMStringlocalName
); HTMLCollection getElementsByTagNameNS(DOMString?namespace
, DOMStringlocalName
); HTMLCollection getElementsByClassName(DOMStringclassNames
); [CEReactions, NewObject] Element createElement(DOMStringlocalName
, optional ElementCreationOptionsoptions
); [CEReactions, NewObject] Element createElementNS(DOMString?namespace
, DOMStringqualifiedName
, optional ElementCreationOptionsoptions
); [NewObject] DocumentFragment createDocumentFragment(); [NewObject] Text createTextNode(DOMStringdata
); [NewObject] CDATASection createCDATASection(DOMStringdata
); [NewObject] Comment createComment(DOMStringdata
); [NewObject] ProcessingInstruction createProcessingInstruction(DOMStringtarget
, DOMStringdata
); [CEReactions, NewObject] Node importNode(Nodenode
, optional booleandeep
= false); [CEReactions] Node adoptNode(Nodenode
); [NewObject] Attr createAttribute(DOMStringlocalName
); [NewObject] Attr createAttributeNS(DOMString?namespace
, DOMStringqualifiedName
); [NewObject] Event createEvent(DOMStringinterface
); [NewObject] Range createRange(); // NodeFilter.SHOW_ALL = 0xFFFFFFFF [NewObject] NodeIterator createNodeIterator(Noderoot
, optional unsigned longwhatToShow
= 0xFFFFFFFF, optional NodeFilter?filter
= null); [NewObject] TreeWalker createTreeWalker(Noderoot
, optional unsigned longwhatToShow
= 0xFFFFFFFF, optional NodeFilter?filter
= null); }; [Exposed=Window] interfaceXMLDocument
: Document {}; dictionaryElementCreationOptions
{ DOMStringis
; };
Document
nodes are simply known as documents.
Each document has an associated encoding (an encoding), content type (a string), URL (a URL), origin (an origin), type ("xml
" or "html
"), and mode ("no-quirks
", "quirks
", or "limited-quirks
"). [ENCODING] [URL] [HTML51]
Unless stated otherwise, a document’s encoding is the utf-8 encoding, its content type is "application/xml
", its URL is "about:blank
", origin is an opaque origin
, type is "xml
", and its mode is "no-quirks
".
A document is said to be an XML document if its type is "xml
", and an HTML document otherwise. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.
A document is said to be in no-quirks mode if its mode is "no-quirks
", quirks mode if its mode is "quirks
", and limited-quirks mode if its mode is "limited-quirks
".
The mode is only ever changed from the default for documents created by the HTML parser based on the presence, absence, or value of the DOCTYPE string, and by a new browsing context (initial "about:blank
"). [HTML51]
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
- document .
-
Returns document’s URL.
- document .
origin
-
Returns document’s origin.
- document .
compatMode
-
Returns the string "
BackCompat
" if document’s mode is "quirks mode
", and "CSS1Compat
" otherwise. - document .
characterSet
-
Returns document’s encoding.
- document .
contentType
-
Returns document’s content type.
The Document()
constructor must return a new document whose origin is the origin of the global object’s associated document. [HTML51]
Note: Unlike createDocument()
, this constructor does not return an XMLDocument
object, but a document (Document
object).
The implementation
attribute’s getter must return the DOMImplementation
object that is associated with the document.
The URL
’s getter and documentURI
attribute’s getter must return the URL.
The origin
attribute’s getter must return the Unicode serialization of context object’s origin.
The compatMode
attribute’s getter must return "BackCompat
" if the context object’s mode is "quirks
", and "CSS1Compat
" otherwise.
The characterSet
attribute’s getter, charSet attribute’s getter, and inputEncoding attribute’s getter, must return context object’s encoding’s name.
The contentType
attribute’s getter must return the content type.
- document .
doctype
-
Returns the doctype or null if there is none.
- document .
documentElement
-
Returns the document element.
- collection = document .
getElementsByTagName(localName)
-
If localName is "
*
" returns aHTMLCollection
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.) - collection = document .
getElementsByTagNameNS(namespace, localName)
-
If namespace and localName are "
*
" returns aHTMLCollection
of all descendant elements.If only namespace is "
*
" returns aHTMLCollection
of all descendant elements whose local name is localName.If only localName is "
*
" returns aHTMLCollection
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. - collection = document .
getElementsByClassName(classNames)
- collection = element .
getElementsByClassName(classNames)
- collection = element .
-
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’s getter must return the child of the document that is a doctype, and null otherwise.
The documentElement
attribute’s getter must return the document element.
The getElementsByTagName(localName)
method, when invoked, must return the list of elements with local name localName for the context object.
Note: 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, when invoked, must return the list of elements with namespace namespace and local name localName for the context object.
The getElementsByClassName(classNames)
method, when invoked, 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.
element = document . createElement(localName [, options])
-
Returns an element with localName as local name (if document is an HTML document, localName gets lowercased). The element’s namespace is the HTML namespace when document is an HTML document or document’s content type is "
application/xhtml+xml
", and null otherwise.When supplied, options’
is
member can be used to create a customized built-in element. element = document . createElementNS(namespace, qualifiedName [, options])
-
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 anInvalidCharacterError
will be thrown.If one of the following conditions is true a
NamespaceError
will be thrown:- localName does not match the
QName
production. - Namespace prefix is not null and namespace is the empty string.
- Namespace prefix is "
xml
" and namespace is not the XML namespace. - qualifiedName or namespace prefix is "
xmlns
" and namespace is not the XMLNS namespace. - namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "
xmlns
".
When supplied, options’
is
member can be used to create a customized built-in element. - localName does not match the
- documentFragment = document .
createDocumentFragment()
-
Returns a
DocumentFragment
node. - text = document .
createTextNode(data)
- cdataSection = document .
createCDATASection(data)
-
Returns a
CDATASection
node whose data is data. - comment = document .
createComment(data)
- processingInstruction = document .
createProcessingInstruction(target, data)
-
Returns a
ProcessingInstruction
node whose target is target and data is data.If target does not match the
Name
production anInvalidCharacterError
will be thrown.If data contains "
?>
" anInvalidCharacterError
will be thrown.
The element interface for any name and namespace is Element
, unless stated otherwise.
Note: The HTML Standard will e.g. define that for html
and the HTML namespace, the HTMLHtmlElement
interface is used. [[!HTML5]
The createElement(localName, options)
method, when invoked, must run the these steps:
-
If localName does not match the
Name
production, throw anInvalidCharacterError
. -
If the context object is an HTML document, let localName be converted to ASCII lowercase.
-
Let is be the value of
is
member of options, or null if no such member exists. -
Let namespace be the HTML namespace, if the context object is an HTML document or the context object’s content type is "
text/html
" or "application/xhtml+xml
", and null otherwise. -
Let element be the result of creating an element given the context object, localName, namespace, null, is and with the synchronous custom elements flag set. Rethrow any exceptions.
- If is is non-null, then set an attribute for element using "
is
" and is. -
Return element.
The createElementNS(namespace, qualifiedName)
method, when invoked, must run these steps:
-
Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract. Rethrow any exceptions.
-
Let is be the value of
is
member of options, or null if no such member exists. -
Let element be the result of creating an element given the context object, localName, namespace, prefix, is and with the synchronous custom elements flag set. Rethrow any exceptions.
-
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.
- If is is non-null, then set an attribute for element using "
is
" and is. -
Return element.
The createDocumentFragment()
method, when invoked, must return a new DocumentFragment
node with its node document set to the context object.
The createTextNode(data)
method, when invoked, must return a new Text
node with its data set to data and node document set to the context object.
Note: No check is performed that data consists of characters that match the Char
production.
The createCDATASection(data)
method, when
invoked, must run these steps:
-
If context object is an HTML document, then throw a
NotSupportedError
. -
If data contains the string "
]]>
", then throw anInvalidCharacterError
. -
Return a new
CDATASection
node with its data set to data and node document set to the context object.
The createComment(data)
method, when invoked, must return a new Comment
node with its data set to data and node document set to the context object.
Note: 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, when invoked, must run these steps:
-
If target does not match the
Name
production, throw anInvalidCharacterError
. -
If data contains the string "
?>
", throw anInvalidCharacterError
. -
Return a new
ProcessingInstruction
node, with target set to target, data set to data, and node document set to the context object.
Note: No check is performed that target contains "xml
" or ":
", or that data contains characters that match the Char
production.
- clone = document . 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 or a shadow root, throws a
NotSupportedError
. - node = document .
adoptNode(node)
-
Moves node from another document and returns it.
If node is a document throws a
NotSupportedError
or, if node is a shadow root, throws aHierarchyRequestError
.
The importNode(node, deep)
method, when invoked, must run these steps:
-
If node is a document or shadow root, throw a
NotSupportedError
. -
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.
-
If document is not the same as oldDocument, run these substeps:
-
For each inclusiveDescendant in node’s inclusive descendants, run these subsubsteps:
-
Set inclusiveDescendant’s node document to document.
-
If inclusiveDescendant is an element, then set the node document of each attribute in inclusiveDescendant’s attribute list to document.
-
-
For each inclusiveDescendant in node’s shadow-including inclusive descendants that is a custom element, enqueue a custom element callback reaction with inclusiveDescendant, callback name "
adoptedCallback
", and an empty argument list. -
For each inclusiveDescendant in node’s inclusive descendants, in tree order, run the adopting steps with inclusiveDescendant and oldDocument.
-
The adoptNode(node)
method, when invoked, must run these steps:
-
If node is a document, throw a
NotSupportedError
. -
If node is a shadow root, throw a
HierarchyRequestError
. -
Adopt node into the context object.
-
Return node.
The createAttribute(localName)
method, when
invoked, must run these steps:
-
If localName does not match the
Name
production in XML, then throw anInvalidCharacterError
. - If the context object is an HTML document, then set localName to localName in ASCII lowercase.
- Return a new attribute whose local name is localName and node document is context object.
The createAttributeNS(namespace, qualifiedName)
method, when invoked, must run these steps:
-
Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract.
-
Return a new attribute whose namespace is namespace, namespace prefix is prefix, local name is localName, and node document is context object.
The createEvent(interface)
method, when invoked, must run these steps:
-
Let constructor be null.
-
If interface is an ASCII case-insensitive match for any of the strings in the first column in the following table, then set constructor to the interface in the second column on the same row as the matching string:
String Interface Notes " compositionevent
"CompositionEvent
[UIEVENTS] " customevent
"CustomEvent
" event
"Event
" event
"Event
" events
"Event
" hashchangeevent
"HashChangeEvent
[HTML51] " htmlevents
"Event
" keyboardevent
"KeyboardEvent
[UIEVENTS] " messageevent
"MessageEvent
[WEBMESSAGING] " mouseevent
"MouseEvent
[UIEVENTS] " mouseevents
"MouseEvent
[UIEVENTS] " storageevent
"StorageEvent
[WEBSTORAGE] " uievent
"UIEvent
[UIEVENTS] " uievents
"UIEvent
[UIEVENTS] -
If constructor is null, throw a
NotSupportedError
. -
If the interface indicated by constructor is not exposed on the relevant global object of the context object, then throw a
NotSupportedError
.Typically user agents disable support for touch events in some configurations, in which case this clause would be triggered for the interface TouchEvent.
-
Let event be the result of creating an event given constructor.
-
Initialize event’s
type
attribute to the empty string. -
Initialize event’s
timeStamp
attribute to aDOMHighResTimeStamp
representing the high resolution time from the time origin to now. -
Initialize event’s
isTrusted
attribute to false. -
Unset event’s initialized flag.
-
Return event.
Note: Event constructors ought to be used instead.
The createRange()
method, when invoked, must return a new range with (context object, 0) as its start and end.
Note: The Range()
constructor ought to be used instead.
The createNodeIterator(root, whatToShow, filter)
method, when invoked, must run these steps:
-
Create a
NodeIterator
object. -
Set root to 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, when invoked, must run these steps:
-
Create a
TreeWalker
object. -
Set root to 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.
4.5.1. Interface DOMImplementation
User agents must create a DOMImplementation
object whenever a document is created and associate it with that document.
[Exposed=Window] interfaceDOMImplementation
{ [NewObject] DocumentType createDocumentType(DOMStringqualifiedName
, DOMStringpublicId
, DOMStringsystemId
); [NewObject] XMLDocument createDocument(DOMString?namespace
, [TreatNullAs=EmptyString] DOMStringqualifiedName
, optional DocumentType?doctype
= null); [NewObject] Document createHTMLDocument(optional DOMStringtitle
); 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, anInvalidCharacterError
is thrown, and if it does not match theQName
production, aNamespaceError
is thrown. - doc = document .
implementation
. createDocument(namespace, qualifiedName [, doctype = null]) -
Returns an
XMLDocument
[see bug 22960], 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, when invoked, must run these steps:
-
Validate qualifiedName.
-
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.
Note: 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, when invoked, must run these steps:
-
Let document be a new
XMLDocument
[see bug 22960]. -
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. Rethrow any exceptions. -
If doctype is not null, append doctype to document.
-
If element is not null, append element to document.
-
document’s origin is context object’s associated document’s origin.
-
document’s content type is determined by namespace:
- HTML namespace
application/xhtml+xml
- SVG namespace
image/svg+xml
- Any other namespace
application/xml
-
Return document.
The createHTMLDocument(title)
method, when invoked, 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 a
html
element in the HTML namespace, and append it to doc. -
Create a
head
element in the HTML namespace, and append it to thehtml
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 thehtml
element created in the earlier step. -
document’s origin is context object’s associated document’s origin.
-
Return doc.
The hasFeature()
method, when invoked, must return true.
Note: 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.
4.6. Interface DocumentFragment
[Constructor,
Exposed=Window]
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.
Note: The
node’s host concept is useful for HTML’s template element and for shadow root, and impacts the pre-insert and replace algorithms. DocumentFragment
- tree = new
DocumentFragment
() -
Returns a new
DocumentFragment
node.
The DocumentFragment()
constructor must return a new DocumentFragment
node whose node document is current global object’s associated Document
.
4.7. Interface DocumentType
[Exposed=Window]
interface 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’s getter must return the context object’s name.
The publicId
attribute’s getter must return the context object’s public ID.
The systemId
attribute’s getter must return the context object’s system ID.
4.8. Interface ShadowRoot
[Exposed=Window] interfaceShadowRoot
: DocumentFragment { readonly attribute ShadowRootMode mode; readonly attribute Element host; }; enumShadowRootMode
{"open"
,"closed"
};
ShadowRoot
nodes are simply known as shadow roots.
Shadow roots have an associated mode ("open
"
or "closed
").
Shadow roots’s associated host is never null.
A shadow root’s get the parent algorithm, given an event, returns null if event’s composed flag is unset and shadow root is the root of event’s path’s first tuple’s item, and shadow root’s host otherwise.
The mode
attribute’s getter must return the context object’s mode.
The host
attribute’s getter must return the context object’s host.
In shadow-including tree order, is shadow-including preorder, depth-first traversal of a node tree. shadow-including preorder, depth-first traversal of a node tree tree is preorder, depth-first traversal of tree, with for each shadow host encountered in tree, shadow-including preorder, depth-first traversal of that element’s shadow root’s node tree just after it is encountered.
The shadow-including root of an object is its root’s host’s shadow-including root, if the object’s root is a shadow root, and its root otherwise.
An object A is a shadow-including descendant of an object B, if A is a descendant of B, or A’s root is a shadow root and A’s root’s host is a shadow-including inclusive descendant of B.
A shadow-including inclusive descendant is an object or one of its shadow-including descendants.
An object A is a shadow-including ancestor of an object B, if and only if B is a shadow-including descendant of A.
A shadow-including inclusive ancestor is an object or one of its shadow-including ancestors.
A node A is closed-shadow-hidden from a node B if all of the following conditions are true:
-
A’s root is a shadow root.
-
A’s root is not a shadow-including inclusive ancestor of B.
-
A’s root is a shadow root whose mode is "
closed
" or A’s root’s host is from B.
To retarget an object A against an object B, repeat these steps until they return an object:
-
If A’s root is not a shadow root, or A’s root is a shadow-including inclusive ancestor of B, then return A.
4.9. Interface Element
[Exposed=Window] interfaceElement
: Node { readonly attribute DOMString? namespaceURI; readonly attribute DOMString? prefix; readonly attribute DOMString localName; readonly attribute DOMString tagName; [CEReactions] attribute DOMString id; [CEReactions] attribute DOMString className; [SameObject] readonly attribute DOMTokenList classList; [CEReactions, Unscopable] attribute DOMString slot; boolean hasAttributes(); [SameObject] readonly attribute NamedNodeMap attributes; DOMString? getAttribute(DOMStringqualifiedName
); DOMString? getAttributeNS(DOMString?namespace
, DOMStringlocalName
); [CEReactions] void setAttribute(DOMStringqualifiedName
, DOMStringvalue
); [CEReactions] void setAttributeNS(DOMString?namespace
, DOMStringqualifiedName
, DOMStringvalue
); [CEReactions] void removeAttribute(DOMStringqualifiedName
); [CEReactions] void removeAttributeNS(DOMString?namespace
, DOMStringlocalName
); booleanhasAttribute
(DOMStringqualifiedName
); boolean hasAttributeNS(DOMString?namespace
, DOMStringlocalName
); Attr?getAttributeNode
(DOMStringqualifiedName
); Attr? getAttributeNodeNS(DOMString?namespace
, DOMStringlocalName
); [CEReactions] Attr? setAttributeNode(Attrattr
); [CEReactions] Attr?setAttributeNodeNS
(Attrattr
); [CEReactions] Attr removeAttributeNode(Attrattr
); ShadowRoot attachShadow(ShadowRootInitinit
); readonly attribute ShadowRoot? shadowRoot; Element? closest(DOMStringselectors
); boolean matches(DOMStringselectors
); boolean webkitMatchesSelector(DOMStringselectors
); // historical alias of .matches HTMLCollection getElementsByTagName(DOMStringlocalName
); HTMLCollection getElementsByTagNameNS(DOMString?namespace
, DOMStringlocalName
); HTMLCollection getElementsByClassName(DOMStringclassNames
); [CEReactions] Element? insertAdjacentElement(DOMStringwhere
, Elementelement
); // historical void insertAdjacentText(DOMStringwhere
, DOMStringdata
); // historical }; dictionaryShadowRootInit
{ required ShadowRootModemode
; };
Element
nodes are simply known as elements.
Elements have an associated namespace, namespace prefix, local name, custom element state, custom element definition, and is
value. When an element is created, all of these values are initialized.
An element’s custom element state is one of "undefined
", "failed
", "uncustomized
", or "custom
". An element whose custom element state is "uncustomized
" or "custom
" is said to be defined. An element whose custom element state is "custom
" is said to be custom.
Whether or not an element is defined is used to determine the behavior of the :defined pseudo-class. Whether or not an element is custom is used to determine the behavior of the mutation algorithms. The "failed
" state is used to ensure that if a custom element constructor fails to execute correctly the first time, it is not executed again by an upgrade.
The following code illustrates elements in each of these four states:
<!DOCTYPE html>
<script>
window.customElements.define("sw-rey", class extends HTMLElement {})
window.customElements.define("sw-finn", class extends HTMLElement {}, { extends: "p" })
window.customElements.define("sw-kylo", class extends HTMLElement {
constructor() {
// super() intentionally omitted for this example
}
})
</script>
<!-- "undefined" (not defined, not custom) -->
<sw-han></sw-han>
<p is="sw-luke"></p>
<p is="asdf"></p>
<!-- "failed" (not defined, not custom) -->
<sw-kylo></sw-kylo>
<!-- "uncustomized" (defined, not custom) -->
<p></p>
<asdf></asdf>
<!-- "custom" (defined, custom) -->
<sw-rey></sw-rey>
<p is="sw-finn"></p>
Elements also have an associated shadow root (null or a shadow root). Null unless otherwise stated.
An element’s qualified name is its local name if its namespace prefix is null, or its namespace prefix, followed by ":
", followed by its local name.
Elements also have an attribute list, which is a list exposed through a NamedNodeMap
. 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.
This and other specifications may define attribute change steps for elements. The algorithm is passed element, localName, oldValue, value, and namespace.
To create an element, given a document, localName, namespace, prefix, is, and optional synchronous custom elements flag, run these steps:
-
Let result be null.
-
Let definition be the result of looking up a custom element definition given document, namespace, localName, and is.
-
If definition is non-null, and definition’s name is not equal to its local name (i.e., definition represents a customized built-in element), then:
-
Let interface be the element interface for localName and the HTML namespace.
-
Set result to a new element that implements interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "
undefined
", custom element definition set to null,is
value set to is, and node document set to document. -
If the synchronous custom elements flag is set, upgrade element using definition.
-
Otherwise, enqueue a custom element upgrade reaction given result and definition.
-
-
Otherwise, if definition is non-null, then:
-
If the synchronous custom elements flag is set, then run these subsubsteps while catching any exceptions:
-
Let C be definition’s constructor.
-
Set result to Construct(C). Rethrow any exceptions.
-
If result does not implement the
HTMLElement
interface, throw aTypeError
exception.This is meant to be a brand check to ensure that the object was allocated by the HTML element constructor. See webidl #97 about making this more precise.
If this check passes, then result will already have its custom element state and custom element definition initialized.
-
If result’s attribute list is not empty, throw a
NotSupportedError
exception. -
If result has children, throw a
NotSupportedError
exception. -
If result’s parent is not null, throw a
NotSupportedError
exception. -
If result’s node document is not document, throw a
NotSupportedError
exception. -
If result’s namespace is not the HTML namespace, throw a
NotSupportedError
exception.Note: As of the time of this writing, every element that implements the
HTMLElement
interface is also in the HTML namespace, so this check is currently redundant with the above brand check. However, this is not guaranteed to be true forever in the face of potential specification changes, such as converging certain SVG and HTML interfaces. -
If result’s local name is not equal to localName, throw a
NotSupportedError
exception. -
Set result’s namespace prefix to prefix.
-
Set result’s
is
value to null.
If any of these subsubsteps threw an exception, then:
-
Set result to a new element that implements the
HTMLUnknownElement
interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "failed
", custom element definition set to null,is
value set to null, and node document set to document.
-
-
Otherwise:
-
Set result to a new element that implements the
HTMLElement
interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "undefined
", custom element definition set to null,is
value set to null, and node document set to document. -
Enqueue a custom element upgrade reaction given result and definition.
-
-
-
Otherwise:
-
Let interface be the element interface for localName and namespace.
-
Set result to a new element that implements interface, with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "
uncustomized
", custom element definition set to null,is
value set to is, and node document set to document. -
If namespace is the HTML namespace, and either localName is a valid custom element name or is is is non-null, set result’s custom element state to "
undefined
".
-
-
Return result.
To replace an attribute oldAttr by an attribute newAttr in an element element, run these steps:
-
Queue a mutation record of "
attributes
" for element with name oldAttr’s local name, namespace oldAttr’s namespace, and oldValue oldAttr’s value. -
Run the attribute change steps with element, oldAttr’s local name, oldAttr’s value, newAttr’s value, and oldAttr’s namespace.
-
If element is custom, then enqueue a custom element callback reaction with element, callback name "
attributeChangedCallback
", and an argument list containing oldAttr’s local name, oldAttr’s value, newAttr’s value, and oldAttr’s namespace. -
Replace oldAttr by newAttr in the element’s attribute list.
-
Set oldAttr’s element to null.
-
Set newAttr’s element to element.
To get an attribute by name given a qualifiedName and element element, run these steps:
-
If element is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
-
Return the first attribute in element’s attribute list whose qualified name is qualifiedName, and null otherwise.
To get an attribute by namespace and local name given a namespace, localName, and element element, run these steps:
- If namespace is the empty string, set it to null.
- Return the attribute in element’s attribute list whose namespace is namespace and local name is localName, if any, and null otherwise.
To get an attribute value given element element, localName, and an optional namespace (null unless stated otherwise), run these steps:
-
Let attr be the result of getting an attribute given namespace, localName, and element.
-
If attr is null, then return the empty string.
-
Return attr’s value.
To set an attribute given an attr and element, run these steps:
-
If attr’s element is neither null nor element, throw an
InUseAttributeError
. -
Let oldAttr be the result of getting an attribute given attr’s namespace, attr’s local name, and element.
-
If oldAttr is attr, return attr.
-
If oldAttr is non-null, replace it by attr in element.
-
Otherwise, append attr to element.
-
Return oldAttr.
To set an attribute value for an element element using a localName and value, and an optional prefix, and an optional namespace, run these steps:
- If prefix is not given, set it to null.
- If namespace is not given, set it to null.
- Let attribute be the result of getting an attribute given namespace, localName, and element.
- If attribute is null, create an attribute whose namespace is namespace, namespace prefix is prefix, local name is localName, value is value, and node document is element’s node document, then append this attribute to element, and then 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. -
If element is custom, then enqueue a custom element callback reaction with element, callback name "
attributeChangedCallback
", and an argument list containing attribute’s local name, attribute’s value, value, and attribute’s namespace. -
Run the attribute change steps with element, attribute’s local name, attribute’s value, value, and attribute’s namespace.
-
Set attribute’s value to value.
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. -
If element is custom, then enqueue a custom element callback reaction with element, callback name "
attributeChangedCallback
", and an argument list containing attribute’s local name, null, attribute’s value, and attribute’s namespace. -
Run the attribute change steps with element, attribute’s local name, attribute’s value, value, and attribute’s namespace.
-
Append the attribute to the element’s attribute list.
- Set attribute’s element to element.
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. -
Run the attribute change steps with element, attribute’s local name, attribute’s value, value, and attribute’s namespace.
-
If element is custom, then enqueue a custom element callback reaction with element, callback name "
attributeChangedCallback
", and an argument list containing attribute’s local name, attribute’s value, null, and attribute’s namespace. -
Remove attribute from the element’s attribute list.
- Set attribute’s element to null.
To remove an attribute by name given a qualifiedName and element element, run these steps:
-
Let attr be the result of getting an attribute given qualifiedName and element.
-
If attr is non-null, remove it from element.
-
Return attr.
To remove an attribute by namespace and local name given a namespace, localName, and element element, run these steps:
- Let attr be the result of getting an attribute given namespace, localName, and element.
-
If attr is non-null, remove it from element.
-
Return attr.
An element can have an associated unique identifier (ID).
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.
Use these attribute change steps to update an element’s ID:
-
If the given attribute’s localName is
id
, namespace is null, and value is null or the empty string, then unset element’s ID. -
Otherwise, if localName is
id
, namespace is null, then set element’s ID to value.
Note: While this specification defines requirements for class
and id
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.
- namespace = element .
namespaceURI
-
Returns the namespace.
- prefix = element .
prefix
-
Returns the namespace prefix.
- localName = element .
localName
-
Returns the local name.
- qualifiedName = element .
tagName
- Returns the qualified name. (The return value is uppercased in an HTML document.)
The namespaceURI
attribute’s getter must return the context object’s namespace.
The prefix
attribute’s getter must return the context object’s namespace prefix.
The localName
attribute’s getter must return the context object’s local name.
The tagName
attribute’s getter must run these steps:
-
Let qualifiedName be context object’s qualified name.
-
If the context object is in the HTML namespace and its node document is an HTML document, let qualifiedName be converted to ASCII uppercase.
-
Return qualifiedName.
IDL attributes that are defined to reflect a content attribute of a given name, must have a getter and setter that follow these steps:
- getter
-
Return the result of running get an attribute value given context object and name.
- setter
-
Set an attribute value for the context object using name 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’s getter must return the associated
object representing the context object’s classes.
The token setof this particular DOMTokenList
DOMTokenList
object are also known as the element’s classes.
The slot
attribute must reflect the
"slot
" content attribute.
id
, class
, and slot
are effectively
superglobal attributes as they can appear on any element, regardless of that element’s namespace.
The hasAttributes()
method, when invoked, must return
false if context object’s attribute list is empty, and
true otherwise.
The attributes
attribute’s getter must return a NamedNodeMap
.
The getAttribute(qualifiedName)
method, when invoked, must run these steps:
-
Let attr be the result of getting an attribute given qualifiedName and the context object.
-
If attr is null, return null.
-
Return attr’s value.
The getAttributeNS(namespace, localName)
method, when invoked, 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(qualifiedName, value)
method, when invoked, must run these steps:
-
If name does not match the
QName
production in XML, throw anInvalidCharacterError
. -
If the context object is in the HTML namespace and its node document is an HTML document, let qualifiedName be converted to ASCII lowercase.
-
Let attribute be the first attribute in the context object’s attribute list whose name is qualifiedName, or null if there is no such attribute.
-
If attribute is null, create an attribute whose local name is qualifiedName, value is value, and node document is context object’s node document, and then append this attribute to the context object and terminate these steps.
-
Change attribute from context object to value.
The setAttributeNS(namespace, qualifiedName, value)
method, when invoked, must run these steps:
-
Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract. Rethrow any exceptions.
-
Set an attribute value for the context object using localName, value, and also prefix and namespace.
The removeAttribute(qualifiedName)
method, when invoked, must remove an attribute given qualifiedName and the context object, and then return undefined.
The removeAttributeNS(namespace, localName)
method, when invoked, must remove an attribute given namespace, localName, and context object, and then return undefined.
The hasAttribute(name)
method, when invoked, 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 qualifiedName is qualifiedName, and false otherwise.
The hasAttributeNS(namespace, localName)
method, when invoked, 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.
var shadow = element .
attachShadow(init)
-
Creates a shadow root for element and returns it.
var shadow = element .
shadowRoot
-
Returns element’s shadow root, if any, and if shadow root’s mode is "
open
", and null otherwise.
The attachShadow(init)
method, when
invoked, must run these steps:
-
If context object’s namespace is not the HTML namespace, then throw a
NotSupportedError
. -
If context object’s local name is not a valid custom element name, "
article
", "aside
", "blockquote
", "body
", "div
", "footer
", "h1
", "h2
", "h3
", "h4
", "h5
", "h6
", "header
", "main
" "nav
", "p
", "section
", or "span
", then throw aNotSupportedError
. -
If context object is a shadow host, then throw an
InvalidStateError
. -
Let shadow be a new shadow root whose node document is context object’s node document, host is context object, and mode is init’s
mode
. -
Set context object’s shadow root to shadow.
-
Return shadow.
The shadowRoot
attribute’s getter must run these
steps:
-
Let shadow be context object’s shadow root.
-
If shadow is null or its mode is "
closed
", then return null. -
Return shadow.
element .
closest(selectors)
- Returns the first (starting at element) inclusive ancestor that matches selectors, and null otherwise.
- element .
matches(selectors)
- Returns true if matching selectors against element’s root yields element, and false otherwise.
The closest(selectors)
method, when invoked, must run these steps:
- Let s be the result of parse a selector from selectors. [SELECTORS4]
- If s is failure, throw a
SyntaxError
. - Let elements be context object’s inclusive ancestors that are elements, in reverse tree order.
- For each element in elements, if match a selector against an element, using s, element, and :scope element context object, returns success, return element. [SELECTORS4]
- Return null.
The matches(selectors)
and webkitMatchesSelector(selectors)
methods, when invoked, must run these steps:
- Let s be the result of parse a selector from selectors. [SELECTORS4]
- If s is failure, throw a
SyntaxError
. - Return true if the result of match a selector against an element, using s, element, and :scope element context object, returns success, and false otherwise. [SELECTORS4]
The getAttributeNode(name)
method, when invoked, must return the result of getting an attribute given qualifiedName and the context object.
The getAttributeNodeNS(namespace, localName)
method, when invoked,
must return the result of getting an attribute given namespace, localName, and the context object.
The setAttributeNode(attr)
and settAttributeNodeNS(attr) method,
when invoked, must return the result of setting an attribute given attr and the context object.
The removeAttributeNode(attr)
method, when invoked, must run these steps:
-
If context object’s attribute list doesn’t contain attr, attribute list, throw a
NotFoundError
. -
Remove attr from context object.
- Return attr.
The getElementsByTagName(localName)
method, when invoked, must return the list of elements with local name localName for the context object.
The getElementsByTagNameNS(namespace, localName)
method, when invoked, must return the list of elements with namespace namespace and local name localName for the context object.
The getElementsByClassName(classNames)
method, when invoked, must return the list of elements with class names classNames for context object.
To insert adjacent, given an element element, string where, and a node node, run the steps associated with the first ASCII case-insensitive match for where:
- "
beforebegin
" -
If element’s parent is null, return null.
Return the result of pre-inserting node into element’s parent before element. Rethrow any exceptions.
- "
afterbegin
" -
Return the result of pre-inserting node into element before element’s first child. Rethrow any exceptions.
- "
beforeend
" -
Return the result of pre-inserting node into element before null. Rethrow any exceptions.
- "
afterend
" -
If element’s parent is null, return null.
Return the result of pre-inserting node into element’s parent before element’s next sibling. Rethrow any exceptions.
- Otherwise
-
Throw a
SyntaxError
.
The insertAdjacentElement(where, element)
method, when invoked, must return the result of running insert adjacent, given context object, where, and element. Rethrow any exceptions.
The insertAdjacentText(where, data)
method, when invoked, must run these steps:
-
Let text be a new
Text
object whose data is data. -
Run insert adjacent, given context object, where, and text. Rethrow any exceptions.
Note: This method returns nothing because it existed before we had a chance to design it.
4.9.1. Interface NamedNodeMap
[Exposed=Window, LegacyUnenumerableNamedProperties] interfaceNamedNodeMap
{ readonly attribute unsigned long length; getter Attr? item(unsigned longindex
); getter Attr? getNamedItem(DOMStringqualifiedName
); Attr? getNamedItemNS(DOMString?namespace
, DOMStringlocalName
); [CEReactions] Attr? setNamedItem(Attrattr
); [CEReactions] Attr? setNamedItemNS(Attrattr
); [CEReactions] Attr removeNamedItem(DOMStringqualifiedName
); [CEReactions] Attr removeNamedItemNS(DOMString?namespace
, DOMStringlocalName
); };
A NamedNodeMap
has an associated element (an element).
A NamedNodeMap
object’s attribute list is its element’s attribute list.
A NamedNodeMap
object’s supported property indices are the numbers in the range zero to the number of attributes in its attribute list map minus one, unless the attribute list is empty, in which case
there are no supported property indices.
The length
attribute’s getter must return
the number of attributes in the attribute list.
The item(index)
method, when
invoked, must run these steps:
-
If index is equal to or greater than the number of attributes in the attribute list, return null.
-
Otherwise, return the indexth attribute in the attribute list.
A NamedNodeMap
object’s supported property names are the return value of running these
steps:
-
Let names be the qualified names of the attributes in this
NamedNodeMap
object’s attribute list, with duplicates omitted, in order. -
If this
NamedNodeMap
object’s element is in the HTML namespace and its node document is an HTML document, then for each name in names, run these substeps:-
Let lowercaseName be name, in ASCII lowercase.
-
If lowercaseName is not equal to name, remove name from names.
-
-
Return names.
The getNamedItem(qualifiedName)
method, when invoked, must return the result of getting an attribute given qualifiedName and element.
The getNamedItemNS(namespace, localName)
method, when invoked, must return the result of getting an attribute given namespace, localName, and element.
The setNamedItem(attr)
and setNamedItemNS(attr)
methods, when invoked, must return the result of setting an attribute given attr and element. Rethrow any exceptions.
The removeNamedItem(qualifiedName)
method, when invoked, must run these steps:
-
Let attr be the result of removing an attribute given qualifiedName and element.
-
If attr is null, then throw a
NotFoundError
. -
Return attr.
The removeNamedItemNS(namespace, localName)
method, when invoked, must run these steps:
-
Let attr be the result of removing an attribute given namespace, localName, and element.
-
If attr is null, then throw a
NotFoundError
. -
Return attr.
4.9.2. Interface Attr
[Exposed=Window]
interface Attr
: Node {
readonly attribute DOMString? namespaceURI;
readonly attribute DOMString? prefix;
readonly attribute DOMString localName;
readonly attribute DOMString name;
readonly attribute DOMString nodeName; // for legacy use, alias of .name
[CEReactions] attribute DOMString value;
readonly attribute Element? ownerElement;
readonly attribute boolean specified; // useless; always returns true
};
Attr
nodes are simply known as attributes. They are sometimes referred to as content attributes to avoid confusion with IDL attributes.
Attributes have a namespace (null or a non-empty string), namespace prefix (null or a non-empty string), local name (a non-empty string), name (a non-empty string), value (a string), and element (null or an element).
Note: If designed today they would just have a name and value.
An attribute’s qualified name is its local name if its namespace prefix is null, and its namespace prefix, followed by ":
", followed by its local name, otherwise.
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 namespaceURI
attribute’s getter must return the namespace.
The prefix
attribute’s getter must return the namespace prefix.
The localName
attribute’s getter must return the local name.
The name
attribute’s getter and nodeName
attribute’s getter must return the name.
The value
attribute’s getter must both return the value.
To set an existing attribute value, given an attribute attribute and string value, run these steps:
- If attribute’s element is null, then set attribute’s value to value.
- Otherwise, change attribute from attribute’s element to value.
The value
attribute’s setter must set an existing attribute value with context object and the given value.
The ownerElement
attribute’s getter must return context object’s element.
The specified
attribute’s getter must return true.
4.10. Interface CharacterData
[Exposed=Window] interfaceCharacterData
: Node { [TreatNullAs=EmptyString] attribute DOMString data; readonly attribute unsigned long length; DOMString substringData(unsigned longoffset
, unsigned longcount
); void appendData(DOMStringdata
); void insertData(unsigned longoffset
, DOMStringdata
); void deleteData(unsigned longoffset
, unsigned longcount
); void replaceData(unsigned longoffset
, unsigned longcount
, DOMStringdata
); };
Note: 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
. -
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 whos 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.
-
If offset is greater than length, throw an
IndexSizeError
. -
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’s getter must return context object’s data, and on setting, must replace data with node context object offset 0, count context object’s length, and data new value.
The length
attribute’s getter must return context object’s length.
The substringData(offset, count)
method, when invoked, must substring data with node context object, offset offset, and count count.
The appendData(data)
method, when invoked, must replace data with node context object, offset context object’s length, count 0, and data data.
The insertData(offset, data)
method, when invoked, must replace data with node context object, offset offset, count 0, and data data.
The deleteData(offset, count)
method, when invoked, must replace data with node context object, offset offset, count count, and data the empty string.
The replaceData(offset, count, data)
method, when invoked, must replace data with node context object, offset offset, count count, and data data.
4.11. Interface Text
[Constructor(optional DOMStringdata
= ""), Exposed=Window] interfaceText
: CharacterData { [NewObject] Text splitText(unsigned longoffset
); readonly attribute DOMString wholeText; };
An exclusive Text
node is a Text
node that is not a CDATASection
node.
The contiguous Text
nodes of a node node are node, node’s previous sibling Text
node, if any, and its contiguous Text
nodes, and node’s next sibling Text
node, if any, and its contiguous Text
nodes, avoiding any duplicates.
The contiguous exclusive Text
nodes of a node node are node, node’s previous sibling exclusive Text
node,
if any, and its contiguous exclusive Text
nodes, and node’s next sibling exclusive Text
node, if any, and its contiguous exclusive Text
nodes, avoiding any duplicates.
- 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, when invoked, 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.
-
If offset is greater than length, throw an
IndexSizeError
. -
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.
-
Return new node.
The splitText(offset)
method, when invoked, must split the context object with offset offset.
The wholeText
attribute’s getter must return a concatenation of the data of the contiguous Text
nodes of the context object, in tree order.
4.12. Interface CDATASection
[Exposed=Window]
interface CDATASection
: Text {
};
4.13. Interface ProcessingInstruction
[Exposed=Window]
interface ProcessingInstruction
: CharacterData {
readonly attribute DOMString target;
};
ProcessingInstruction
nodes have an associated target.
The target
attribute must return the target.
4.14. Interface Comment
[Constructor(optional DOMStringdata
= ""), Exposed=Window] interfaceComment
: CharacterData { };
The Comment(data)
constructor, when invoked, must return a new Comment
node whose data is data and node document is current global object’s associated Document
.
5. Ranges
5.1. Introduction to "DOM Ranges"
A Range
object (range) represents a sequence of content within a node tree. Each range has a start and an end which are boundary points. A boundary point is a tuple consisting of a node and a non-negative numeric offset. So in other words, a range represents a piece of content within a node tree between two boundary points.
Ranges are frequently used in editing for selecting and copying content.
-
Element
:p
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 quote
Note: Attributes such as src
and alt
in the node tree above cannot be represented by a range. The ranges concept is only useful for nodes.
Ranges are affected by mutations to the node tree. Such mutations will not invalidate a range and will try to ensure that the range still represents the same piece of content. Necessarily, a range might itself be modified as part of the mutation to the node tree when e.g. part of the content it represents is mutated.
Note: See the insert and remove algorithms, the normalize()
method, and the replace data and split algorithms for the hairy details.
5.2. Interface Range
[Constructor, Exposed=Window] interfaceRange
{ 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(Nodenode
, unsigned longoffset
); void setEnd(Nodenode
, unsigned longoffset
); void setStartBefore(Nodenode
); void setStartAfter(Nodenode
); void setEndBefore(Nodenode
); void setEndAfter(Nodenode
); void collapse(optional booleantoStart
= false); void selectNode(Nodenode
); void selectNodeContents(Nodenode
); const unsigned shortSTART_TO_START
= 0; const unsigned shortSTART_TO_END
= 1; const unsigned shortEND_TO_END
= 2; const unsigned shortEND_TO_START
= 3; short compareBoundaryPoints(unsigned shorthow
, RangesourceRange
); [CEReactions] void deleteContents(); [CEReactions, NewObject] DocumentFragment extractContents(); [CEReactions, NewObject] DocumentFragment cloneContents(); [CEReactions] void insertNode(Nodenode
); [CEReactions] void surroundContents(NodenewParent
); [NewObject] Range cloneRange(); void detach(); boolean isPointInRange(Nodenode
, unsigned longoffset
); short comparePoint(Nodenode
, unsigned longoffset
); boolean intersectsNode(Nodenode
); stringifier; };
Range
objects are simply known as ranges.
A boundary point is a (node, offset) tuple, where offset is a non-negative integer.
Note: 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
, orComment
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 a partially contained node if and only if the start node and end node are different.
-
The
commonAncestorContainer
attribute value is neither contained nor partially contained. - If the start node is an ancestor of the end node, the common inclusive ancestor will be the start node. Exactly one of its children will be partially contained, and a child will be contained if and only if it precedes the partially contained child. If the end node is an ancestor of the start node, the opposite holds.
-
If the start node is not an inclusive ancestor of the end node, nor vice versa, the common inclusive ancestor will be distinct from both of them. Exactly two of its children will be partially contained, and a child will be contained if and only if it lies between those two.
- range = new Range()
-
Returns a new range.
The Range()
constructor must return a new range with (current global object’s associated Document
, 0) as its start and end.
- node = range .
startContainer
-
Returns range’s start node.
- offset = range .
startOffset
-
Returns range’s start offset.
- node = range .
endContainer
-
Returns range’s end node.
- offset = range .
endOffset
-
Returns range’s end offset.
- collapsed = range .
collapsed
-
Returns true if range’s start and end are the same, and false otherwise.
- container = range .
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’s getter must return the start node.
The startOffset
attribute’s getter must return the start offset.
The endContainer
attribute’s getter must return the end node.
The endOffset
attribute’s getter must return the end offset.
The collapsed
attribute’s getter must return true if start is the same as end, and false otherwise.
The commonAncestorContainer
attribute’s getter 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
. - If offset is greater than node’s length, throw an
IndexSizeError
. - Let bp be the boundary point (node, offset).
-
- If these steps were invoked as "set the start"
- If these steps were invoked as "set the end"
The setStart(node, offset)
method, when invoked, must set the start of the context object to boundary point (node, offset).
The setEnd(node, offset)
method, when invoked, must set the end of the context object to boundary point (node, offset).
The setStartBefore(node)
method, when invoked, must run these steps:
-
Let parent be node’s parent.
-
If parent is null, throw an
InvalidNodeTypeError
. -
Set the start of the context object to boundary point (parent, node’s index).
The setStartAfter(node)
method, when invoked, must run these steps:
-
Let parent be node’s parent.
-
If parent is null, throw an
InvalidNodeTypeError
. -
Set the start of the context object to boundary point (parent, node’s index plus one).
The setEndBefore(node)
method, when invoked, must run these steps:
-
Let parent be node’s parent.
-
If parent is null, throw an
InvalidNodeTypeError
. -
Set the end of the context object to boundary point (parent, node’s index).
The setEndAfter(node)
method, when invoked, must run these steps:
-
Let parent be node’s parent.
-
If parent is null, throw an
InvalidNodeTypeError
. -
Set the end of the context object to boundary point (parent, node’s index plus one).
The collapse(toStart)
method, when invoked, 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, when invoked, must select node within context object.
The selectNodeContents(node)
method, when invoked, 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, when invoked, must run these steps:
-
If how is not one of
throw a
NotSupportedError
. -
If context object’s root is not the same as sourceRange’s root, throw a
WrongDocumentError
. -
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, when invoked, 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
, orComment
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.
Note: 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
, orComment
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
, orComment
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 is original end node, and they are a
Text
,ProcessingInstruction
, orComment
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.
Note: 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
.Note: 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.
Note: 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
, orComment
node:Note: 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 clone.
-
-
For each contained child in contained children, append contained child to fragment.
-
If last partially contained child is a
Text
,ProcessingInstruction
, orComment
node:Note: 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 clone.
-
-
Return fragment.
The extractContents()
method, when invoked, must return the result of extracting context object.
To clone the contents of 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 is original end node, and they are a
Text
,ProcessingInstruction
, orComment
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.
Note: 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
.Note: 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
, orComment
node:Note: 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 clone.
-
-
For each contained child in contained children:
-
If last partially contained child is a
Text
,ProcessingInstruction
, orComment
node:Note: 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:
-
Return fragment.
The cloneContents()
method, when invoked, must return the result of cloning the contents of context object.
To insert a node node into a range range, run these steps:
-
If range’s start node is a
ProcessingInstruction
orComment
node, is aText
node whose parent is null, or is node, then throw anHierarchyRequestError
. -
Let referenceNode be null.
-
If range’s start node is a
Text
node, set referenceNode to thatText
node. -
Otherwise, set referenceNode to the child of start node whose index is start offset, and null if there is no such child.
-
Let parent be range’s start node if referenceNode is null, and referenceNode’s parent otherwise.
-
Ensure pre-insertion validityof node into parent before referenceNode.
-
If range’s start node is a
Text
node, split it with offset range’s start offset, set referenceNode to the result, and set parent to referenceNode’s parent. -
If node is referenceNode, set referenceNode to its next sibling.
-
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, when invoked, must range insert node into context object.
The surroundContents(newParent)
method, when invoked, must run these steps:
-
If a non-
Text
node is partially contained in the context object, throw anInvalidStateError
. -
If newParent is a
Document
,DocumentType
, orDocumentFragment
node, throw anInvalidNodeTypeError
. -
Let fragment be the result of extracting context object.
-
If newParent has children, replace all with null within newParent.
-
Range insert newParent into context object.
-
Append fragment to newParent.
-
Select newParent within context object.
The cloneRange()
method, when invoked, must return a new range with the same start and end as the context object.
The detach()
method, when invoked, must do nothing. Note: Its functionality (disabling a Range
object) was removed, but the method itself is preserved for compatibility.
- position = range .
comparePoint(node, 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.
- intersects = range .
intersectsNode(node)
-
Returns whether range intersects node.
The isPointInRange(node, offset)
method, when invoked, 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
. -
If (node, offset) is before start or after end, return false.
-
Return true.
The comparePoint(node, offset)
method, when invoked, must run these steps:
-
If node’s root is different from the context object’s root, throw a
WrongDocumentError
. -
If node is a doctype, throw an
InvalidNodeTypeError
. -
If offset is greater than node’s length, throw an
IndexSizeError
. -
Return 0.
The intersectsNode(node)
method, when invoked, must run these steps:
The stringification behavior must run these steps:
-
Let s be the empty string.
-
If start node is end node, and it is a
Text
node, return the substring of thatText
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
node
, append to s the substring of that node’s data from its start until the end offset. -
Return s.
Note: The createContextualFragment()
, getClientRects()
, and getBoundingClientRect()
methods are defined in other specifications.[DOM-PARSING][CSSOM-VIEW-1]
6. Traversal
NodeIterator
and TreeWalker
objects can be used to filter and traverse node trees.
Each NodeIterator
and TreeWalker
object also has an associated root node, whatToShow bitmask, and filter callback.
To filter node run these steps:
-
Let n be node’s
attribute value minus 1.nodeType
-
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
. -
Let result be the return value of calling filter’s
acceptNode
with node as argument. Rethrow any exceptions. -
Return result.
6.1. Interface NodeIterator
[Exposed=Window]
interface 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();
};
Note: 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.
Note: As mentioned earlier NodeIterator
objects have an associated root node, whatToShow bitmask, and filter callback as well.
The NodeIterator
pre-removing steps given a nodeIterator and toBeRemovedNode, are as followings:
-
If toBeRemovedNode is not an inclusive ancestor of the
referenceNode
attribute value, then return. -
If the
pointerBeforeReferenceNode
attribute value is true, then:-
Let next be toBeRemovedNode’s first following node that is an inclusive descendant of nodeIterator’s root and is not an inclusive descendant of toBeRemovedNode, and null if there is no such node.
-
If next is non-null, then set nodeIterator’s
referenceNode
attribute to next and return. -
Otherwise, set nodeIterator’s
pointerBeforeReferenceNode
attribute to false.Steps are not terminated here.
-
-
Set nodeIterator’s
referenceNode
attribute to toBeRemovedNode’s parent, if toBeRemovedNode’s previous sibling is null, and to the inclusive descendant of toBeRemovedNode’s previous sibling that appears last in tree order otherwise.
The root
attribute’s getter must return root.
The referenceNode
and pointerBeforeReferenceNode
attributes must return what they were initialized to.
The whatToShow
attribute’s getter must return whatToShow.
The filter
attribute’s getter 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 direction is next
-
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 direction is previous
-
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 thepointerBeforeReferenceNode
attribute to before node, and return node.
The nextNode()
method, when invoked, must return the result of traversing in direction next.
The previousNode()
method, when invoked, must return the result of traversing in direction previous.
The detach()
method, when invoked, must do nothing. Note: Its functionality (disabling a NodeIterator
object) was removed, but the method itself is preserved for compatibility.
6.2. Interface TreeWalker
[Exposed=Window]
interface 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();
};
Note: TreeWalker
objects can be created using the createTreeWalker()
method.
Note: As mentioned earlier TreeWalker
objects have an associated root node, whatToShow bitmask, and filter callback.
The root
attribute’s getter must return root.
The whatToShow
attribute’s getter must return whatToShow.
The filter
attribute’s getter must return filter.
The currentNode
attribute’s getter must return what it was initialized to.
Setting the currentNode
attribute must set it to the new value.
The parentNode()
method, when invoked, 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 thecurrentNode
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.
-
If node is null, return null.
-
Main: Repeat these substeps:
-
Filter node and let result be the return value.
-
If result is
FILTER_ACCEPT
, then set thecurrentNode
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.
-
-
Repeat these substeps:
-
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.
-
-
The firstChild()
method, when invoked, must traverse children of type first.
The lastChild()
method, when invoked, 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 thecurrentNode
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, when invoked, must traverse siblings of type next.
The previousSibling()
method, when invoked, must traverse siblings of type previous.
The previousNode()
method, when invoked, 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 thecurrentNode
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 thecurrentNode
attribute to node and return node.
-
-
Return null.
The nextNode()
method, when invoked, 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 thecurrentNode
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 thecurrentNode
attribute to node and return node. -
Run these substeps again.
-
6.3. Interface NodeFilter
[Exposed=Window] callback interfaceNodeFilter
{ // Constants for acceptNode() const unsigned shortFILTER_ACCEPT
= 1; const unsigned shortFILTER_REJECT
= 2; const unsigned shortFILTER_SKIP
= 3; // Constants for whatToShow const unsigned longSHOW_ALL
= 0xFFFFFFFF; const unsigned longSHOW_ELEMENT
= 0x1; const unsigned longSHOW_ATTRIBUTE
= 0x2; const unsigned longSHOW_TEXT
= 0x4; const unsigned longSHOW_CDATA_SECTION
= 0x8; const unsigned longSHOW_ENTITY_REFERENCE
= 0x10; // historical const unsigned longSHOW_ENTITY
= 0x20; // historical const unsigned longSHOW_PROCESSING_INSTRUCTION
= 0x40; const unsigned longSHOW_COMMENT
= 0x80; const unsigned longSHOW_DOCUMENT
= 0x100; const unsigned longSHOW_DOCUMENT_TYPE
= 0x200; const unsigned longSHOW_DOCUMENT_FRAGMENT
= 0x400; const unsigned longSHOW_NOTATION
= 0x800; // historical unsigned shortacceptNode
(Nodenode
); };
NodeFilter
objects can be used as filter callback and provide
constants for the whatToShow bitmask.
Note: It is typically implemented as a 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_ATTRIBUTE (2);
- SHOW_TEXT (4);
- SHOW_CDATA_SECTION (8);
- 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).
7. Sets
Note: Yes, the name DOMTokenList
is an unfortunate legacy mishap.
7.1. Interface DOMTokenList
[Exposed=Window] interfaceDOMTokenList
{ readonly attribute unsigned long length; getter DOMString? item(unsigned longindex
); boolean contains(DOMStringtoken
); [CEReactions] void add(DOMString...tokens
); [CEReactions] void remove(DOMString...tokens
); [CEReactions] boolean toggle(DOMStringtoken
, optional booleanforce
); [CEReactions] void replace(DOMStringtoken
, DOMStringnewToken
); boolean supports(DOMStringtoken
); [CEReactions] stringifier attribute DOMString value; iterable<DOMString>; };
A DOMTokenList
object has an associated of token set (an ordered set), which is initially empty.
A DOMTokenList
object also has an associated element and an attribute’s local name.
Specifications may define supported tokens for a DOMTokenList
's associated attribute’s local name.
A DOMTokenList
object’s validation steps for a given token are:
- If the associated attribute’s local name does not define supported tokens, then throw a "
TypeError
". - Let lowercase token be a copy of token, in ASCII lowercase.
- If lowercase token is present in supported tokens, return true.
- Return false.
A
object’s update steps are: DOMTokenList
- If the associated element does not have an associated attribute and token set is empty, then return.
- Set an attribute value for the associated element using associated attribute’s local name and the result of running the ordered set serializer for token set.
A DOMTokenList
object’s serialize steps are to return the result of running get an attribute value given the associated element and the associated attribute’s local name.
- 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.
- tokenlist . add(tokens…)
-
Adds all arguments passed, except those already present.
Throws a
SyntaxError
if one of the arguments is the empty string.Throws an
InvalidCharacterError
if one of the arguments contains any ASCII whitespace. - tokenlist . remove(tokens…)
-
Removes arguments passed, if they are present.
Throws a
SyntaxError
if one of the arguments is the empty string.Throws an
InvalidCharacterError
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 asremove()
).Returns true if token is now present, and false otherwise.
Throws a
SyntaxError
if token is empty.Throws an
InvalidCharacterError
if token contains any spaces. - tokenlist .
replace(token, newToken)
-
Replaces token with newToken.
Throws a
SyntaxError
if one of the arguments is the empty string.Throws an
InvalidCharacterError
if one of the arguments contains any ASCII whitespace. - tokenlist .
supports(token)
-
Returns true if token is in the associated attribute’s supported tokens. Returns false otherwise.
Throws a
TypeError
if the associated attribute has no supported tokens defined. - tokenlist .
value
-
Returns the associated set as string.
Can be set, to change the associated set.
The length
attribute’s getter must return the number of tokens in the context object’s token set.
The object’s supported property indices are the numbers in the range zero to the number of tokens in token set minus one, unless token set is empty, in which case there are no supported property indices.
The item(index)
method, when invoked, must run these steps:
-
If index is equal to or greater than the number of tokens in token set, then return null.
-
Return the indexth token in the context object’s token set.
The contains(token)
method, when invoked, must return true if token is in token set,
and false otherwise.
The add(tokens…)
method, when invoked, must run these steps:
-
For each token in tokens:
-
If token is the empty string, then throw a
SyntaxError
. -
If token contains any ASCII whitespace, then throw an "
InvalidCharacterError
.
-
-
For each token in tokens, append token to token set.
-
Run the update steps.
The remove(tokens…)
method, when invoked, must run these steps:
-
For each token in tokens:
-
If token is the empty string, then throw a
SyntaxError
. -
If token contains any ASCII whitespace, then throw an
InvalidCharacterError
.
-
-
For each token in tokens, remove token from token set.
-
Run the update steps.
The toggle(token, force)
method, when invoked, must run these steps:
-
If token is the empty string, then throw a
SyntaxError
. -
If token contains any ASCII whitespace, then throw an
InvalidCharacterError
. -
If token is in token set, then:
-
If force is either not given or is false, then remove token from token set, run the update steps and return false.
-
Otherwise, return true.
-
-
Otherwise, if force is either not given or is true, append token to token set, run the update steps and return true.
- Return false.
The update steps are not always run for toggle()
for web compatibility.
The replace(token, newToken)
method, when invoked, must run these steps:
-
If either token or newToken is the empty string, then throw a
SyntaxError
. -
If either token or newToken contains any ASCII whitespace, then throw an
InvalidCharacterError
. -
If token is not in token set, then return.
-
Run the update steps.
The update steps are not always run for replace()
for web compatibility.
The supports(token)
method, when invoked, must return the result of running validation steps for the given token.
The value
attribute’s getter must return the result of running context object’s serialize steps for token set.
Setting the value
attribute must run the ordered set parser for the given value and set token set to the result.
8. Historical
This section outlines *notable* changes between Working Drafts. A complete history of revisions for this version is available in the W3C DOM 4.1 repository.
8.1. Changes between this draft and the 2nd Working Draft of DOM 4.1
- Use a single concept for attribute change steps of Element
-
Updates to Event
- added
EventListernerOptions
/AddEventListenerOptions
, and make some changes to the steps of dispatching events, and - imported realm from ES standard to ensure security
- added
-
Changes to Sets
- define token set for
DOMTokenList
, and - define
supports()
forDOMTokenList
, and - updated the
normalize()
method ofDOMTokenList
to avoid duplication
- define token set for
- Add append()/prepend() to ParentNode
- Throw an error if the event constructor isn’t exposed
- Throw an
HierarchyRequestError
if range’s start node is node - Add createAttribute()/createAttributeNS() to Document
- Apply pre-removing steps to mutation algorithms and NodeIterator
- Define replaceWith(), after(), before() for ChildNode
- Calculate the length of CharacterData in the Node level
- Use the declaration of web compability to prevent being exposed in NonElementParentNode and NonDocumentTypeChildNode
- Define
hasAttributes()
for Element - Bring CDATASection to Node/Traversal
- Clarify the replace operation of ordered set
- Define get/setAttributeNode, get/setAttributeNodeNS, and removeAttributeNode for Element
- Define closest(), matches() and webkitMatchesSelector() for Element
- Clean up the unsupported events in the createEvent interface
- Improve the insertion/removing steps for descendants
- Use previousSibling in the replacing a node algorithm
- Update the HTMLCollection algorithm in node
-
Introduce firing an event
- Use the relevant realm of the event target when firing an event
- Also note the difference between firing and dispatching an event
- Change add/removeEventListener for service worker
- Make Event’s timeStamp use DOMHighResTimeStamp
- Add [Exposed=Window] to MutationObserver and DOMTokenList
- Return the result of traversing
-
Add support for custom elements
- This is the first part of upstreaming custom elements into the DOM and HTML Standards, instead of having them be in a separate spec that is essentially a bunch of monkeypatches. The second part will be upstreaming the remaining portions into HTML.
- Add Shadow DOM support:
- Clear event’s target when dispatch ends at a shadow root
-
Integrate changes against DOMTokenList
DOMTokenList
should not add empty attributes- The update steps are not always run for toggle and replace methods for web compatibility.
- Set the stage for preventing double custom element constructor calls
8.2. Changes between the 2nd Working Draft of DOM 4.1 and the First Public Working Draft of DOM 4.1.
- Add
insertAdjacentElement()
andinsertAdjacentText()
methods - Add event types from other specifications to createEvent()
-
Remove
XMLDocument.prototype.load
- This is not implemented widely and has long been deprecated
- Set a document’s content-type for createDocument based on namespace
- Add getters and setters
- Add
NamedNodeMap
- Queue a mutation record after all operations
-
Improve
node replacement specification
- Do not record removal when a node is replaced by itself…
-
Refine
adopting a node for a document.
- Only do it if
document
changes, and - Apply recursively to dependents
- Only do it if
-
Make
attr
inherit from node- (again)
8.3. Changes between the First Public Working Draft of DOM 4.1 and the DOM 4 Recommendation
- Use “is” for comparisons
-
Add
.NodeName
for interface Attr.nodeName
is still being used. It’s an alias of .name attribute.
-
Update the IDL for the Node interface;
- The attributes related to base URL are not optional and should be type of USVString instead of DOMString. Use the normalized name by following the HTML spec.
- Update the description for the HTMLCollection interface
- Add two clarifications for "Mutation observers"
-
Clarify the
isTrusted
attribute;- Add a note for
Event.isTrusted
to clarify that mouse click event generated by a user is trusted though historically itsisTrusted
attribute is initialized tofalse
- Add a note for
-
Update the steps for
qualifiedName()
method and the way to validate a qualifiedName.- Add Qualified name definition for Element and Attr. There are several attribute related methods of Interface Element to use name instead of qualified name. Moreover, combine and refine some duplicated functions into one procedure, like 'get an attribute by name', 'remove an attribute by name', etc.
-
Update the algorithm of the
nodeType
attribute.- Cleanup
nodeType
andnodeName
getter attribute’s description. Also changenodeType
’s list style to be similar tonodeName
- Cleanup
-
Always queue mutation records after mutations
- Queuing of mutation records looks inconsistent. To replace a child with node within a parent,
the mutation record should be queued after the removal of
child
and insertion ofnode
- Queuing of mutation records looks inconsistent. To replace a child with node within a parent,
the mutation record should be queued after the removal of
-
Remove the
unenumable
keyword- For compatibility with WEBIDL [WEBIDL]
8.4. DOM Specification History
The W3C produced the first Working Draft of a "Document Object Model Specification" in October 1997, and a year later a version 1.0 Recommendation.Between 2000 and 2003 a set of Recommendations collectively forming DOM 2.0 was published, and in 2004 a set of DOM 3.0 Recommendations were published.
The Element Traversal Recommendation was published in 2008, and the Selectors API Recommendation was published in February 2013. The UI Events specification, and its predecessors, have been in development since around 2000.
Other DOM specifications have been in development during that time, and continue to be developed.
Around 2009 some employees of Opera software began to write a new version of a DOM specification, which was then worked on by the "Web Hypertext Application Technology Working Group", and subsequently developed jointly with the W3C. The eventual goals of that works were described in the DOM 4 Recommendation. In November 2013 W3C produced a W3C First Public Working draft based on that work, and after subsequent development that became the W3C Recommendation DOM 4, in November 2015.
The current DOM 4.1 revision is produced by W3C, with the primary aim of documenting what is interoperably implemented and is, or is likely to become, a core part of the Web Platform. An important secondary goal is to minimise incompatibility with the ongoing work at WHATWG.
Acknowledgements
Very many people that have contributed to earlier versions of DOM, to the WHATWG’s version, and to making DOM implementations more interoperable, over many years.
Some contributions are are acknowledged in particular specification versions and implementations, some are not. Without all of them this specification would be much poorer.
For specific contributions to this version, thanks are due to: Cindy Wu Xiaoqian, Donglei Wu "wucongdonglai", Guangzhen Li "kurli", Hao Chen "horkychen", Hongbo Min "hmin", Honghao Jin "jinhoward", Rick Byers, Philippe Le Hégaret, Shouqun Liu "shouqun", Zhiping Lin "linzhiping", Zhiqiang Zhang "zqzhang".