+Group: WHATWG +Date: 2018-06-21 +H1: DOM +Shortname: dom +Text Macro: TWITTER thedomstandard +Abstract: DOM defines a platform-neutral model for events, aborting activities, and node trees. +Translation: ja https://triple-underscore.github.io/DOM4-ja.html +Ignored Terms: EmptyString, Array, Document +Indent: 1 ++ +
+urlPrefix: https://www.w3.org/TR/xml/#NT- + type: type + text: Name; url: Name + text: Char; url: Char + text: PubidChar; url: PubidChar +urlPrefix: https://www.w3.org/TR/xml-names/#NT- + type: type + text: QName; url: QName +url: https://w3c.github.io/DOM-Parsing/#dfn-createcontextualfragment-fragment + type: method; text: createContextualFragment(); for: Range +type: interface + url: https://w3c.github.io/touch-events/#idl-def-touchevent + text: TouchEvent + url: https://w3c.github.io/deviceorientation/spec-source-orientation.html#devicemotion + text: DeviceMotionEvent + text: DeviceOrientationEvent + url: https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.15 + text: WebGLContextEvent +urlPrefix: https://tc39.github.io/ecma262/#; spec: ECMASCRIPT + text: Construct; url: sec-construct; type: abstract-op + text: Realm; url: realm; type: dfn +urlPrefix: https://w3c.github.io/hr-time/#; spec: HR-TIME + type:typedef; urlPrefix: dom-; text: DOMHighResTimeStamp + type:dfn; text: time origin + type:dfn; text: clock resolution ++ +
+spec:html; type:element + text: title + text: script +spec:infra; type:dfn; text:list ++ +
By consolidating DOM Level 3 Core [[DOM-Level-3-Core]], + Element Traversal [[ELEMENTTRAVERSAL]], + Selectors API Level 2 [[SELECTORS-API2]], the + "DOM Event Architecture" and "Basic Event Interfaces" chapters of + DOM Level 3 Events [[uievents-20031107]] (specific types of events do not + belong in the DOM Standard), and DOM Level 2 Traversal and Range + [[DOM-Level-2-Traversal-Range]], and: + +
By moving features from the HTML Standard [[!HTML]] that make more sense to be + specified as part of the DOM Standard. + +
By defining a replacement for the "Mutation Events" and + "Mutation Name Event Types" chapters of DOM Level 3 Events + [[uievents-20031107]] as the old model + was problematic. + +
The old model is expected to be removed from implementations + in due course. + +
By defining new features that simplify common DOM operations. +
This specification depends on the Infra Standard. [[!INFRA]] + +
Some of the terms used in this specification are defined in Encoding, +Selectors, Web IDL, XML, and Namespaces in XML. +[[!ENCODING]] +[[!SELECTORS4]] +[[!WEBIDL]] +[[!XML]] +[[!XML-NAMES]] + +
The term context object means the object on which the algorithm, +attribute getter, attribute setter, or method being discussed was called. + +
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. + + + +
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 +null or an object, and has +children, which is an +ordered set of 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 that tree 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 inclusive sibling is an +object or one of its siblings. + +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, or 0 if it has none. + + +
The ordered set parser takes a string +input and then runs these steps: + +
Let inputTokens be the result of + splitting input on ASCII whitespace. + +
Let tokens be a new ordered set. + +
For each token in inputTokens, append + token to tokens. + +
The ordered set serializer takes a +set and returns the concatenation of set using U+0020 SPACE. + + +
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!!exception}}" + {{DOMException}}. + +
Return the result of match a selector against a tree with s and + node's root using scoping root node. [[!SELECTORS4]]. +
Support for namespaces within selectors is not planned and will not be +added. + + +
To validate a qualifiedName, throw an
+"{{InvalidCharacterError!!exception}}" {{DOMException}} if qualifiedName does not match
+the Name or QName production.
+
+To validate and extract a namespace and qualifiedName,
+run these steps:
+
+
:" (U+003E), then split the
+ string on it and set prefix to the part before and localName to
+ the part after.
+
+ xml" and namespace is not the
+ XML namespace, then throw a "{{NamespaceError!!exception}}" {{DOMException}}.
+
+ xmlns" and namespace is not the
+ XMLNS namespace, then throw a
+ "{{NamespaceError!!exception}}" {{DOMException}}.
+
+ xmlns", then throw a "{{NamespaceError!!exception}}"
+ {{DOMException}}.
+
+
+obj.addEventListener("load", imgFetched)
+
+function imgFetched(ev) {
+ // great success
+ …
+}
+
+
+Event listeners can be removed
+by utilizing the
+{{EventTarget/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
+{{Event/type}} attribute value
+("load" in the above example). The
+event's
+{{Event/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
+{{Event/type}} attribute value is
+"submit" is
+dispatched. If this
+event's
+{{Event/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
+{{EventTarget/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
+{{Event/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
+{{Event/target}} attribute value will be the
+span element. The
+first time {{Event/currentTarget}} attribute's
+value will be the document, the second
+time the body element.
+{{Event/eventPhase}} attribute's value
+switches from {{Event/CAPTURING_PHASE}}
+to {{Event/BUBBLING_PHASE}}. If an
+event listener was registered for
+the span element,
+{{Event/eventPhase}} attribute's value
+would have been {{Event/AT_TARGET}}.
+
+
+
+[Constructor(DOMString type, optional EventInit eventInitDict),
+ Exposed=(Window,Worker,AudioWorklet)]
+interface Event {
+ readonly attribute DOMString type;
+ readonly attribute EventTarget? target;
+ readonly attribute EventTarget? srcElement; // historical
+ 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; // historical alias of .stopPropagation
+ void stopImmediatePropagation();
+
+ readonly attribute boolean bubbles;
+ readonly attribute boolean cancelable;
+ attribute boolean returnValue; // historical
+ void preventDefault();
+ readonly attribute boolean defaultPrevented;
+ readonly attribute boolean composed;
+
+ [Unforgeable] readonly attribute boolean isTrusted;
+ readonly attribute DOMHighResTimeStamp timeStamp;
+
+ void initEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false); // historical
+};
+
+dictionary EventInit {
+ boolean bubbles = false;
+ boolean cancelable = false;
+ boolean composed = 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.
+ +A potential event target is null or an {{EventTarget}} object. + +
An event has an associated target (a +potential event target). Unless stated otherwise it is null. + +
An event has an associated relatedTarget (a +potential event target). Unless stated otherwise it is null. + +
Other specifications use relatedTarget to define a
+relatedTarget attribute. [[UIEVENTS]]
+
+
An event has an associated touch target list (a +list of zero or more potential event targets). Unless stated otherwise it is the +empty list. + +
The touch target list is for the exclusive use of defining the +{{TouchEvent}} interface and related interfaces. [[TOUCH-EVENTS]] + +
An event has an associated path. A path is a +list of structs. Each struct consists of an +item (an {{EventTarget}} object), an +item-in-shadow-tree (a boolean), a target (a +potential event target), a +relatedTarget (a +potential event target), a touch target list (a list +of potential event targets), a root-of-closed-tree (a boolean), and +a slot-in-closed-tree (a boolean). A path is initially +the empty list.
+ +event = new Event(type [, eventInitDict])
+ event . {{Event/type}}
+ click", "hashchange", or
+ "submit".
+
+ event . {{Event/target}}
+ event . {{Event/currentTarget}}
+ event . {{Event/composedPath()}}
+ closed" that are not reachable from event's {{Event/currentTarget}}.
+
+ event . {{Event/eventPhase}}
+ event . stopPropagation()
+ event . stopImmediatePropagation()
+ event . {{Event/bubbles}}
+ event . {{Event/cancelable}}
+ event . preventDefault()
+ event . {{Event/defaultPrevented}}
+ event . {{Event/composed}}
+ event . {{Event/isTrusted}}
+ event . {{Event/timeStamp}}
+ The type attribute must return the value it was
+initialized to. When an event is created the attribute must be initialized to the empty
+string.
+
+
The target attribute's getter, when invoked, must
+return the context object's target.
+
+
The srcElement attribute's getter, when invoked, must
+return the context object's target.
+
+
The currentTarget attribute must return the value it
+was initialized to. When an event is created the attribute must be initialized to null.
+
+
The composedPath() method, when invoked, must run these
+steps:
+
+
Let reversedComposedPath be an empty list. + +
Let hiddenSubtreeLevel be 0. + +
Let hasSeenCurrentTarget be false. + +
Let currentTarget be the context object's {{Event/currentTarget}} + attribute value. + +
Let reversedPath be the context object's path, in reverse + order. + +
For each struct in reversedPath: + +
If struct's item is currentTarget, then set + hasSeenCurrentTarget to true. + +
Otherwise, if hasSeenCurrentTarget is true and struct's + root-of-closed-tree is true, then increase hiddenSubtreeLevel by + 1. + +
If hiddenSubtreeLevel is 0, then append struct's + item to reversedComposedPath. + +
If struct's slot-in-closed-tree is true and + hiddenSubtreeLevel is greater than 0, then decrease hiddenSubtreeLevel by + 1. +
Return reversedComposedPath, in reverse order. +
The eventPhase attribute must return the value it was
+initialized to, which must be one of the following:
+
+
Initially the attribute must be initialized to {{Event/NONE}}. + +
Each event has the following associated flags that are all initially unset: + +
The stopPropagation() method, when invoked, must set the
+context object's stop propagation flag.
The cancelBubble attribute's getter, when invoked,
+must return true if the context object's stop propagation flag is set, and false
+otherwise.
+
+
The {{Event/cancelBubble}} attribute's setter, when invoked, must set the context object's +stop propagation flag if the given value is true, and do nothing otherwise. + +
The stopImmediatePropagation() method, when invoked,
+must set the context object's stop propagation flag and the context object's
+stop immediate propagation flag.
The bubbles and
+cancelable attributes must return the values they were
+initialized to.
+
+
To set the canceled flag, given an event event, if +event's {{Event/cancelable}} attribute value is true and event's +in passive listener flag is unset, then set event's canceled flag, and do +nothing otherwise. + +
The returnValue attribute's getter, when invoked,
+must return false if context object's canceled flag is set, and true otherwise.
+
+
The {{Event/returnValue}} attribute's setter, when invoked, must set the canceled flag +with the context object if the given value is false, and do nothing otherwise. + +
The preventDefault() method, when invoked, must
+set the canceled flag with the context object.
+
+
There are scenarios where invoking {{Event/preventDefault()}} has no +effect. User agents are encouraged to log the precise cause in a developer console, to aid +debugging. + +
The defaultPrevented attribute's getter, when
+invoked, must return true if the context object's canceled flag is set, and false
+otherwise.
The composed attribute's getter, when invoked, must
+return true if the context object's composed flag is set, and false otherwise.
The isTrusted attribute must return the value it was
+initialized to. When an event is created the attribute must be initialized to false.
+
+
{{Event/isTrusted}} is a convenience that indicates whether an +event is dispatched by the user agent (as opposed to using +{{EventTarget/dispatchEvent()}}). The sole legacy exception is {{HTMLElement/click()}}, which causes +the user agent to dispatch an event whose {{Event/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 event's initialized flag. + +
Unset event's stop propagation flag, + stop immediate propagation flag, and canceled flag. + +
Set event's {{Event/isTrusted}} attribute to false. + +
Set event's target to null. + +
Set event's {{Event/type}} attribute to type. + +
Set event's {{Event/bubbles}} attribute to bubbles. + +
Set event's {{Event/cancelable}} attribute to cancelable. +
The
+initEvent(type, bubbles, cancelable)
+method, when invoked, must run these steps:
If the context object's dispatch flag is set, then return. + +
Initialize the context object with type, bubbles, and + cancelable. +
As events have constructors {{Event/initEvent()}} is redundant and +incapable of setting {{Event/composed}}. It has to be supported for legacy content. + + +
+partial interface Window {
+ [Replaceable] readonly attribute any event; // historical
+};
+
+
+Each {{Window}} object has an associated current event (undefined or an +{{Event}} object). Unless stated otherwise it is undefined. + +
The event attribute's getter, when invoked, must
+return the context object's current event.
+
+
Web developers are strongly encouraged to instead rely on the {{Event}} object passed +to event listeners, as that will result in more portable code. This attribute is not available in +workers or worklets, and is inaccurate for events dispatched in shadow trees. + + +
+[Constructor(DOMString type, optional CustomEventInit eventInitDict),
+ Exposed=(Window,Worker)]
+interface CustomEvent : Event {
+ readonly attribute any detail;
+
+ void initCustomEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional any detail = null);
+};
+
+dictionary CustomEventInit : EventInit {
+ any detail = null;
+};
+
+
+Events using the
+{{CustomEvent}} interface can be used to carry custom data.
+
+event = new CustomEvent(type [, eventInitDict])
+ event . {{CustomEvent/detail}}
+ The detail attribute must return the value it
+was initialized to.
+
+
The
+initCustomEvent(type, bubbles, cancelable, detail)
+method must, when invoked, run these steps:
+
+
If the context object's dispatch flag is set, then return. + +
Initialize the context object with type, bubbles, and + cancelable. + +
Set the context object's {{CustomEvent/detail}} attribute to detail. +
This construct can be used by {{Event}} subclasses that have a more complex structure +than a simple 1:1 mapping between their initializing dictionary members and IDL attributes. + +
When a constructor of the {{Event}} +interface, or of an interface that inherits from the {{Event}} interface, is invoked, these steps +must be run, given the arguments type and eventInitDict: + +
Let event be the result of running the inner event creation steps with + this interface, null, now, and eventInitDict. + +
Initialize event's {{Event/type}} attribute to type. + +
Return 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:
+ +If realm is not given, then set it to null. + +
Let dictionary 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.) + +
This does not work if members are required; see + whatwg/dom#600. + +
Let event be the result of running the inner event creation steps with + eventInterface, realm, the time of the occurrence that the event is + signaling, and dictionary. + +
In macOS the time of the occurrence for input
+ actions is available via the timestamp property of NSEvent objects.
+
+
Initialize event's {{Event/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.
+ +The inner event creation steps, given an interface, +realm, time, and dictionary, are as follows:
+ +Let event be the result of creating a new object using eventInterface. If + realm is non-null, then use that Realm; otherwise, use the default behavior defined in + Web IDL. + +
As of the time of this writing Web IDL does not yet define any default behavior; + see heycam/webidl#135. + +
Set event's initialized flag. + +
Initialize event's {{Event/timeStamp}} attribute to a {{DOMHighResTimeStamp}} + representing the high resolution time from the time origin to time. + +
User agents should set a minimum resolution of event's + {{Event/timeStamp}} attribute to 5 microseconds following the existing clock resolution + recommendation. [[!HR-TIME]] + +
For each member → value in dictionary, if + event has an attribute whose identifier is member, then + initialize that attribute to value. + +
Run the event constructing steps with event. + +
Return event. +
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.
+
+
+
+[Constructor,
+ Exposed=(Window,Worker,AudioWorklet)]
+interface EventTarget {
+ void addEventListener(DOMString type, EventListener? callback, optional (AddEventListenerOptions or boolean) options);
+ void removeEventListener(DOMString type, EventListener? callback, optional (EventListenerOptions or boolean) options);
+ boolean dispatchEvent(Event event);
+};
+
+callback interface EventListener {
+ void handleEvent(Event event);
+};
+
+dictionary EventListenerOptions {
+ boolean capture = false;
+};
+
+dictionary AddEventListenerOptions : EventListenerOptions {
+ boolean passive = false;
+ boolean once = false;
+};
+
+
+An {{EventTarget}} object represents a target to which an event can be dispatched +when something has occurred. + +
Each {{EventTarget}} object has an associated event listener list (a +list of zero or more event listeners). It is initially the empty list. + + +
An event listener can be used to observe a specific +event and consists of: + +
Although callback is an {{EventListener}} +object, an event listener is a broader concept as can be seen above. + +
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. + +
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 {{Event/type}} attribute is click. Web compatibility prevented it
+from being removed and it is now the enshrined way of defining an activation of something. [[!HTML]]
+
+
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. [[!HTML]] + +
target = new EventTarget();
+ Creates a new {{EventTarget}} object, which can be used by developers to dispatch and + listen for events. + +
target . addEventListener(type, callback [, options])
+ Appends an event listener for events whose {{Event/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 a + boolean, in which case the method behaves exactly as if the value was specified as + options's {{EventListenerOptions/capture}}. + +
When set to true, options's {{EventListenerOptions/capture}} prevents + callback from being invoked when the event's + {{Event/eventPhase}} attribute value is {{Event/BUBBLING_PHASE}}. When false (or not present), + callback will not be invoked when event's {{Event/eventPhase}} + attribute value is {{Event/CAPTURING_PHASE}}. Either way, callback + will be invoked if event's {{Event/eventPhase}} attribute value is {{Event/AT_TARGET}}. + +
When set to true, options's {{AddEventListenerOptions/passive}} indicates that the + callback will not cancel the event by invoking + {{Event/preventDefault()}}. This is used to enable performance optimizations described in + [[#observing-event-listeners]]. + +
When set to true, options's {{AddEventListenerOptions/once}} 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 + event listener list and is not appended if it has the same + type, callback, and + capture. + +
target . removeEventListener(type, callback [, options])
+ Removes the event listener in target's + event listener list with the same type, callback, and + options. + +
target . dispatchEvent(event)
+ Dispatches a synthetic event event to target and returns true + if either event's {{Event/cancelable}} attribute value is false or its + {{Event/preventDefault()}} method was not invoked, and false otherwise. +
To flatten options, run these +steps: + +
If options is a boolean, then return options. + +
Return options's {{EventListenerOptions/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
+ {{AddEventListenerOptions/passive}} and once to options's
+ {{AddEventListenerOptions/once}}.
+
+
Return capture, passive, and once. +
The EventTarget() constructor, when invoked,
+must return a new {{EventTarget}}.
+
+
Because of the defaults stated elsewhere, the returned {{EventTarget}}'s +get the parent algorithm will return null, and it will have no activation behavior, +legacy-pre-activation behavior, or legacy-canceled-activation behavior. + +
In the future we could allow custom get the parent algorithms. Let us know +if this would be useful for your programs. For now, all author-created {{EventTarget}}s do not +participate in a tree structure.
+ +To add an event listener given an {{EventTarget}} object eventTarget +and an event listener listener, run these steps: + +
If eventTarget'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 a
+ TypeError.
+ [[!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 listener's callback is null, then return. + +
If eventTarget's event listener list does not contain an + event listener whose type is listener's + type, callback is listener's + callback, and capture is + listener's capture, then append + listener to eventTarget's event listener list. +
The add an event listener concept exists to ensure event handlers use +the same code path. [[HTML]] + +
The
+addEventListener(type, callback, options)
+method, when invoked, must run these steps:
+
+
Let capture, passive, and once be the result of + flattening more options. + +
Add an event listener with the context object and an event listener + whose type is type, callback is + callback, capture is capture, + passive is passive, and once is + once. +
To remove an event listener, given an {{EventTarget}} object eventTarget +and an event listener listener, set listener's +removed to true and remove listener from +eventTarget's event listener list. + + +
To remove all event listeners, given an {{EventTarget}} object +eventTarget, for each listener of eventTarget's +event listener list, remove an event listener with +eventTarget and listener. + +
HTML needs this to define document.open(). [[HTML]]
+
+
The
+removeEventListener(type, callback, options)
+method, when invoked, must run these steps:
+
+
If the 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 a
+ TypeError. [[!SERVICE-WORKERS]]
+
+
Let capture be the result of flattening options. + +
If the context object's event listener list + contains an event listener whose type is + type, callback is callback, and + capture is capture, then remove an event listener + with the context object and that event listener. +
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, then throw an "{{InvalidStateError!!exception}}" {{DOMException}}. + +
Initialize event's {{Event/isTrusted}} attribute to false. + +
Return the result of dispatching event to the context object. +
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 {{Event/cancelable}} only when there is +at least one non-{{AddEventListenerOptions/passive}} listener. For example, +non-{{AddEventListenerOptions/passive}} {{TouchEvent}} listeners must block scrolling, but if all +listeners are {{AddEventListenerOptions/passive}} then scrolling can be allowed to start +in parallel by making the {{TouchEvent}} uncancelable (so that calls to +{{Event/preventDefault()}} are ignored). So code dispatching an event is able to observe the absence +of non-{{AddEventListenerOptions/passive}} listeners, and use that to clear the {{Event/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). + + +
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]]
+
+
legacy target override flag is only used by HTML and only when + target is a {{Window}} object. + +
Let activationTarget be null. + +
Let relatedTarget be the result of retargeting event's + relatedTarget against target. + +
If target is not relatedTarget or target is event's + relatedTarget, then: + +
Let touchTargets be a new list. + +
For each touchTarget of event's + touch target list, append the result of retargeting + touchTarget against target to touchTargets. + +
Append to an event path with event, target, + targetOverride, relatedTarget, touchTargets, and false. + +
Let isActivationEvent be true, if event is a {{MouseEvent}} object
+ and event's {{Event/type}} attribute is "click", and false otherwise.
+
+
If isActivationEvent is true and target has + activation behavior, then set activationTarget to + target. + +
Let slotable be target, if target is a slotable + and is assigned, and null otherwise. + +
Let slot-in-closed-tree be false. + +
Let parent be the result of invoking target's get the parent + with event. + +
While parent is non-null:
+ +If slotable is non-null: + +
Assert: parent is a slot. + +
Set slotable to null. + +
If parent's root is a shadow root whose
+ mode is "closed", then set slot-in-closed-tree
+ to true.
+
If parent is a slotable and is assigned, then set + slotable to parent. + +
Let relatedTarget be the result of retargeting event's + relatedTarget against parent. + +
Let touchTargets be a new list. + +
For each touchTarget of event's + touch target list, append the result of retargeting + touchTarget against parent to touchTargets. + +
If parent is a node and target's root is a + shadow-including inclusive ancestor of parent, then: + +
If isActivationEvent is true, event's {{Event/bubbles}} + attribute is true, activationTarget is null, and parent has + activation behavior, then set activationTarget to + parent. + +
Append to an event path with event, parent, null, + relatedTarget, touchTargets, and slot-in-closed-tree. +
Otherwise, if parent is relatedTarget, 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 to an event path with event, parent, + target, relatedTarget, touchTargets, and + slot-in-closed-tree. +
If parent is non-null, then set parent to the result of invoking + parent's get the parent with event. + +
Set slot-in-closed-tree to false. +
Let clearTargetsTuple be the last tuple in event's + path whose target is non-null. + +
Let clearTargets be true if clearTargetsTuple's + target, clearTargetsTuple's relatedTarget, + or an {{EventTarget}} object in clearTargetsTuple's + touch target list is a node and its root is a + shadow root, and false otherwise. + +
Set event's {{Event/eventPhase}} attribute to {{Event/CAPTURING_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: + +
+ +For each tuple in event's path, in order: + +
If tuple's target is non-null, then set + event's {{Event/eventPhase}} attribute to {{Event/AT_TARGET}}. + +
Otherwise, set event's {{Event/eventPhase}} attribute to + {{Event/BUBBLING_PHASE}}. + +
If either event's {{Event/eventPhase}} attribute is {{Event/BUBBLING_PHASE}} + and event's {{Event/bubbles}} attribute is true or event's + {{Event/eventPhase}} attribute is {{Event/AT_TARGET}}, then invoke with + tuple, event, and legacyOutputDidListenersThrowFlag if given. +
Set event's {{Event/eventPhase}} attribute to {{Event/NONE}}. + +
Set event's {{Event/currentTarget}} attribute to null. + +
Set event's path to the empty list. + +
Unset event's dispatch flag, stop propagation flag, and + stop immediate propagation flag. + +
If clearTargets, then: + +
Set event's target to null. + +
Set event's relatedTarget to null. + +
Set event's touch target list 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 append to an event path, given an +event, target, targetOverride, relatedTarget, +touchTargets, and a slot-in-closed-tree, run these steps:
+ +Let item-in-shadow-tree be false. + +
If target is a node and its root is a + shadow root, then set item-in-shadow-tree to true. + +
Let root-of-closed-tree be false. + +
If target is a shadow root whose mode is
+ "closed", then set root-of-closed-tree to true.
+
+
Append a new struct to event's path + whose item is target, item-in-shadow-tree is + item-in-shadow-tree, target is targetOverride, + relatedTarget is relatedTarget, + touch target list is touchTargets, + root-of-closed-tree is root-of-closed-tree, and + slot-in-closed-tree is slot-in-closed-tree. +
To invoke, given a tuple, +event, and an optional legacyOutputDidListenersThrowFlag, run these steps: + +
Set event's target 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. + +
Set event's touch target list to tuple's + touch target list. + +
If event's stop propagation flag is set, then return. + +
Initialize event's {{Event/currentTarget}} attribute to tuple's + item. + +
Let listeners be a clone of event's + {{Event/currentTarget}} attribute value's event listener list. + +
This avoids event listeners added after this point from being + run. Note that removal still has an effect due to the removed field. + +
Let found be the result of running inner invoke with event, + listeners, and legacyOutputDidListenersThrowFlag if given. + +
If found is false and event's {{Event/isTrusted}} attribute is true, + then: + +
Let originalEventType be event's {{Event/type}} attribute value. + +
If event's {{Event/type}} attribute value is a match for any of the strings in the + first column in the following table, set event's {{Event/type}} attribute value to + the string in the second column on the same row as the matching string, and return otherwise. + +
| Event type | Legacy event type + |
|---|---|
"animationend" | "webkitAnimationEnd"
+ |
"animationiteration" | "webkitAnimationIteration"
+ |
"animationstart" | "webkitAnimationStart"
+ |
"transitionend" | "webkitTransitionEnd"
+ |
Inner invoke with event, listeners, and + legacyOutputDidListenersThrowFlag if given. + +
Set event's {{Event/type}} attribute value to originalEventType. +
To inner invoke, given an +event, listeners, and an optional +legacyOutputDidListenersThrowFlag, run these steps: + +
Let found be false. + +
For each listener in listeners, whose + removed is false: + +
If event's {{Event/type}} attribute value is not listener's + type, then continue. + +
Set found to true. + +
If event's {{Event/eventPhase}} attribute value is {{Event/CAPTURING_PHASE}} + and listener's capture is false, then + continue. + +
If event's {{Event/eventPhase}} attribute value is {{Event/BUBBLING_PHASE}} and + listener's capture is true, then + continue. + +
If listener's once is true, then + remove listener from event's {{Event/currentTarget}} + attribute value's event listener list. + + +
Let global be listener callback's + associated Realm's global object. + +
Let currentEvent be undefined. + +
If global is a {{Window}} object, then: + +
Set currentEvent to global's current event. + +
If tuple's item-in-shadow-tree is false, then set + global's current event to event. +
If listener's passive is true, then set + event's in passive listener flag. + +
Call a user object's operation with listener's
+ callback, "handleEvent", « event », and
+ event's {{Event/currentTarget}} attribute value. If this throws an exception, then:
+
+
Report the exception. + +
Set legacyOutputDidListenersThrowFlag if given. + +
The legacyOutputDidListenersThrowFlag is only used by Indexed + Database API. [[INDEXEDDB]] +
Unset event's in passive listener flag. + +
If global is a {{Window}} object, then set global's + current event to currentEvent. + +
If event's stop immediate propagation flag is set, then return + found. +
Return found. +
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 creating an event given + eventConstructor, in the relevant Realm of target. + +
Initialize event's {{Event/type}} attribute to e. + +
Initialize any other IDL attributes of event as described in the invocation of this + algorithm. + +
This also allows for the {{Event/isTrusted}} attribute to be set to false. + +
Return the result of dispatching event at target, with + legacy target override flag set if set. +
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 {{Event/bubbles}} or {{Event/cancelable}} attribute initialized,
+ one could write "fire an event named submit at target with its
+ {{Event/cancelable}} attribute initialized to true".
+
+
Or, when a custom constructor is needed, "fire an event named click at
+ target using {{MouseEvent}} with its {{UIEvent/detail}} attribute initialized to 1".
+
+
Occasionally the return value is important: + +
Let doAction be the result of firing an event named
+ like at target.
+
+
If doAction is true, then … +
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 {{Event/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. + + + +
Though promises do not have a built-in aborting mechanism, many APIs using them require abort +semantics. {{AbortController}} is meant to support these requirements by providing an +{{AbortController/abort()}} method that toggles the state of a corresponding {{AbortSignal}} object. +The API which wishes to support aborting can accept an {{AbortSignal}} object, and use its state to +determine how to proceed. + +
APIs that rely upon {{AbortController}} are encouraged to respond to {{AbortController/abort()}} +by rejecting any unsettled promise with a new "{{AbortError!!exception}}" {{DOMException}}. + +
A hypothetical doAmazingness({ ... }) method could accept an {{AbortSignal}} object
+ in order to support aborting as follows:
+
+
+const controller = new AbortController();
+const signal = controller.signal;
+
+startSpinner();
+
+doAmazingness({ ..., signal })
+ .then(result => ...)
+ .catch(err => {
+ if (err.name == 'AbortError') return;
+ showUserErrorMessage();
+ })
+ .then(() => stopSpinner());
+
+// …
+
+controller.abort();doAmazingness could be implemented as follows:
+
+
+function doAmazingness({signal}) {
+ if (signal.aborted) {
+ return Promise.reject(new DOMException('Aborted', 'AbortError'));
+ }
+
+ return new Promise((resolve, reject) => {
+ // Begin doing amazingness, and call resolve(result) when done.
+ // But also, watch for signals:
+ signal.addEventListener('abort', () => {
+ // Stop doing amazingness, and:
+ reject(new DOMException('Aborted', 'AbortError'));
+ });
+ });
+}
+APIs that require more granular control could extend both {{AbortController}} and + {{AbortSignal}} objects according to their needs. +
+[Constructor,
+ Exposed=(Window,Worker)]
+interface AbortController {
+ [SameObject] readonly attribute AbortSignal signal;
+
+ void abort();
+};
+
+controller = new AbortController()
+ controller . signal
+ controller . abort()
+ An {{AbortController}} object has an associated signal (an +{{AbortSignal}} object). + +
The AbortController() constructor, when
+invoked, must run these steps:
+
+
Let signal be a new {{AbortSignal}} object. + +
Let controller be a new {{AbortController}} object whose + signal is signal. + +
Return controller. +
The signal attribute's getter, when
+invoked, must return the context object's signal.
+
+
The abort() method, when invoked, must
+signal abort on the context object's
+signal.
+
+
+
+[Exposed=(Window,Worker)]
+interface AbortSignal : EventTarget {
+ readonly attribute boolean aborted;
+
+ attribute EventHandler onabort;
+};
+
+signal . aborted
+ An {{AbortSignal}} object has an associated aborted flag. It is +unset unless specified otherwise. + +
An {{AbortSignal}} object has associated abort algorithms, which is a +set of algorithms which are to be executed when its [=AbortSignal/aborted flag=] is +set. Unless specified otherwise, its value is the empty set. + +
To add an algorithm algorithm to an {{AbortSignal}} +object signal, run these steps: + +
If signal's aborted flag is set, then return. + +
Append algorithm to signal's + abort algorithms. +
To remove an algorithm algorithm from an +{{AbortSignal}} signal, remove algorithm from +signal's abort algorithms. + +
The [=AbortSignal/abort algorithms=] enable APIs with complex +requirements to react in a reasonable way to {{AbortController/abort()}}. For example, a given API's +[=AbortSignal/aborted flag=] might need to be propagated to a cross-thread environment, such as a +service worker. + +
The aborted attribute's getter, when invoked, must return +true if the context object's [=AbortSignal/aborted flag=] is set, and false otherwise. + +
Changes to an {{AbortSignal}} object represent the wishes of the corresponding +{{AbortController}} object, but an API observing the {{AbortSignal}} object can chose to ignore +them. For instance, if the operation has already completed. + +
To signal abort, given a {{AbortSignal}} object +signal, run these steps: + +
If signal's [=AbortSignal/aborted flag=] is set, then return. + +
Set signal's [=AbortSignal/aborted flag=]. + +
For each algorithm in signal's + [=AbortSignal/abort algorithms=]: run algorithm. + +
Empty signal's abort algorithms. + +
[=Fire an event=] named abort at signal.
+
A followingSignal (an {{AbortSignal}}) is made to +follow a parentSignal (an {{AbortSignal}}) by running +these steps: + +
If followingSignal's [=AbortSignal/aborted flag=] is set, then return. + +
If parentSignal's [=AbortSignal/aborted flag=] is set, then + signal abort on followingSignal. + +
Otherwise, add the following abort steps to + parentSignal: + +
Signal abort on followingSignal. +
Any web platform API using promises to represent operations that can be aborted must adhere to +the following: + +
signal dictionary member.
+ The steps for a promise-returning method doAmazingness(options) could be as
+ follows:
+
+
Let |p| be [=a new promise=]. + +
If |options|' signal member is present, then:
+
+
If |options|' signal's [=AbortSignal/aborted flag=] is set, then [=reject=]
+ |p| with an "{{AbortError!!exception}}" {{DOMException}} and return |p|.
+
+
[=AbortSignal/Add|Add the following abort steps=] to |options|' signal:
+
+
Stop doing amazing things. + +
[=Reject=] |p| with an "{{AbortError!!exception}}" {{DOMException}}. +
Run these steps [=in parallel=]: + +
Let |amazingResult| be the result of doing some amazing things. + +
[=/Resolve=] |p| with |amazingResult|. +
Return |p|. +
APIs not using promises should still adhere to the above as much as possible. + + + +
Each such document is represented as a node tree. Some of the nodes in a +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: + +
html
+ html class="e"
+ head
+ title
+ body
+ Note that, due to the magic that is HTML parsing, not all +ASCII whitespace were turned into {{Text}} nodes, but the general concept is +clear. Markup goes in, a tree of nodes comes out. + + +
The most excellent +Live DOM Viewer +can be used to explore this matter in more detail. + + +
{{Document}}, {{DocumentType}}, {{DocumentFragment}}, {{Element}}, {{Text}}, +{{ProcessingInstruction}}, and {{Comment}} objects (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: + +
In tree order: +
Zero or more nodes each of which is {{ProcessingInstruction}} or {{Comment}}. +
Optionally one {{DocumentType}} node. +
Zero or more nodes each of which is {{ProcessingInstruction}} or {{Comment}}. +
Optionally one {{Element}} node. +
Zero or more nodes each of which is {{ProcessingInstruction}} or {{Comment}}. +
Zero or more nodes each of which is {{Element}}, {{Text}}, {{ProcessingInstruction}}, or + {{Comment}}. +
None. +
To determine the length of a node +node, switch on node: + +
Zero. + +
Its number of children. +
A node is considered empty if its +length is zero. + + +
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. + +
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. +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. + + +
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.
+ +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. + +
A shadow tree contains zero or more elements that are +slots.
+ +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 root. +
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.
+ +{{Element}} and {{Text}} nodes are +slotables.
+ +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.
+ +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 tree order in shadow's + descendants 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.
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 node +root, run assign slotables for each slot slot in +root's inclusive descendants, 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. +
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. + +
To +ensure pre-insertion validity +of a node into a parent before a child, run these steps: + +
To pre-insert a node into a +parent before a child, run these steps: + +
Specifications may define +insertion steps for all or some nodes. The +algorithm is passed insertedNode, 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: + +
If child is non-null, then: + +
For each live range whose start node is parent and + start offset is greater than child's index, increase + its start offset by count. + +
For each live range whose end node is parent and + end offset is greater than child's index, increase + its end offset by count. +
If node is a {{DocumentFragment}} node, then + queue a tree mutation record for node with « », nodes, null, and + null. + +
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 node in nodes, in tree order: + +
If child is null, then append node to + parent's children. + +
Otherwise, insert node into parent's + children before child's index. + +
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 root. + +
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, then queue a tree mutation record for + parent with nodes, « », previousSibling, and child. +
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: + + + +
The above statements differ from the + pre-insert algorithm. + +
Let previousSibling be child's previous sibling. + +
If child's parent is not null, then: + +
Set removedNodes to a list solely containing child. + +
Remove child from its parent with the + suppress observers flag set. +
The above can only be false if child is node. + +
Insert node into parent before reference child + with the suppress observers flag set. + +
Queue a tree mutation record for parent with nodes, + removedNodes, previousSibling, and reference child. + +
Return child. +
If node is not null, then insert node into + parent before null with the suppress observers flag set. + +
Queue a tree mutation record for parent with addedNodes, + removedNodes, null, and null. +
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: + +
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, run these steps: + +
For each live range whose start node is an + inclusive descendant of node, set its start to + (parent, index). + +
For each live range whose end node is an inclusive descendant + of node, set its end to (parent, index). + +
For each live range whose start node is parent and + start offset is greater than index, decrease its + start offset by 1. + +
For each live range whose end node is parent and + end offset is greater than index, decrease its + end offset by 1. + +
For each {{NodeIterator}} object iterator whose
+ root's node document is node's
+ node document, run the NodeIterator pre-removing steps given
+ node and iterator.
+
+
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 root. + +
Run assign slotables for a tree with node's root. +
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, then: + +
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 + parent, and then for each registered of + inclusiveAncestor's registered observer list, if registered's + options's {{MutationObserverInit/subtree}} is true, then + append a new transient registered observer whose + observer is registered's + observer, options is + registered's options, and + source is registered to node's + registered observer list. + +
If suppress observers flag is unset, then queue a tree mutation record for + parent with « », « node », oldPreviousSibling, and + oldNextSibling. + +
If node is a {{Text}} node, then run the child text content change steps + for parent. +
Web compatibility prevents the {{NonElementParentNode/getElementById()}} +method from being exposed on elements (and therefore on {{ParentNode}}). + +
+interface mixin NonElementParentNode {
+ Element? getElementById(DOMString elementId);
+};
+Document includes NonElementParentNode;
+DocumentFragment includes 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 the
+context object's descendants, whose ID is elementId, and
+null if there is no such element otherwise.
+
+
+
+interface mixin DocumentOrShadowRoot {
+};
+Document includes DocumentOrShadowRoot;
+ShadowRoot includes DocumentOrShadowRoot;
+
+
+The {{DocumentOrShadowRoot}} mixin is expected to be used by other +standards that want to define APIs shared between documents and +shadow roots. + + +
Let node be null. + +
Replace each string in nodes with a new {{Text}} node whose + data is the string and node document is + document. + +
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. +
+interface mixin ParentNode {
+ [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(DOMString selectors);
+ [NewObject] NodeList querySelectorAll(DOMString selectors);
+};
+Document includes ParentNode;
+DocumentFragment includes ParentNode;
+Element includes ParentNode;
+
+
+collection = node . {{ParentNode/children}}
+ element = node . {{ParentNode/firstElementChild}}
+ element = node . {{ParentNode/lastElementChild}}
+ node . prepend(nodes)
+ Inserts nodes before the first child of node, while + replacing strings in nodes with equivalent {{Text}} nodes. + +
Throws a "{{HierarchyRequestError!!exception}}" {{DOMException}} 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!!exception}}" {{DOMException}} if the constraints of + the node tree are violated. + + +
node . querySelector(selectors)
+ node . querySelectorAll(selectors)
+ The children attribute's getter must return an
+{{HTMLCollection}} collection rooted at 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 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 context object, if the result is not an empty list, and null
+otherwise.
+
+
The querySelectorAll(selectors)
+method, when invoked, must return the static result of running
+scope-match a selectors string selectors against context object.
+
+
+
Web compatibility prevents the {{previousElementSibling}} and +{{nextElementSibling}} attributes from being exposed on doctypes (and therefore on +{{ChildNode}}). + +
+interface mixin NonDocumentTypeChildNode {
+ readonly attribute Element? previousElementSibling;
+ readonly attribute Element? nextElementSibling;
+};
+Element includes NonDocumentTypeChildNode;
+CharacterData includes NonDocumentTypeChildNode;
+
+
+element = node . {{previousElementSibling}}
+ element = node . {{nextElementSibling}}
+ 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.
+
+
+
+interface mixin ChildNode {
+ [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 includes ChildNode;
+Element includes ChildNode;
+CharacterData includes ChildNode;
+
+
+node . {{before(...nodes)}}
+ Inserts nodes just before node, while replacing strings in + nodes with equivalent {{Text}} nodes. + +
Throws a "{{HierarchyRequestError!!exception}}" {{DOMException}} 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!!exception}}" {{DOMException}} 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!!exception}}" {{DOMException}} if the constraints of + the node tree are violated. + +
node . {{ChildNode/remove()}}
+ 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 context object's parent is null, then return. + +
Remove the context object from context object's + parent. +
+interface mixin Slotable {
+ readonly attribute HTMLSlotElement? assignedSlot;
+};
+Element includes Slotable;
+Text includes Slotable;
+
+
+The assignedSlot attribute's getter must return
+the result of find a slot given context object and with the open flag set.
A {{NodeList}} object is a collection of nodes. + +
+[Exposed=Window]
+interface NodeList {
+ getter Node? item(unsigned long index);
+ readonly attribute unsigned long length;
+ iterable<Node>;
+};
+
+
+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.
+
+
+[Exposed=Window, LegacyUnenumerableNamedProperties]
+interface HTMLCollection {
+ readonly attribute unsigned long length;
+ getter Element? item(unsigned long index);
+ getter Element? namedItem(DOMString name);
+};
+
+
+An {{HTMLCollection}} object is a collection of elements. + +
{{HTMLCollection}} is a 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).
+
+
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 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: + +
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's
+ name 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: + +
name attribute whose value is
+ key;
+ or null if there is no such element. +
Each unit of related similar-origin browsing contexts has a +mutation observer compound microtask queued flag, which is initially unset. +[[!HTML]] + +
Each unit of related similar-origin browsing contexts also has a +mutation observer list (a list of zero or more {{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, then return. + +
Queue a compound microtask to + notify mutation observers. +
To notify mutation observers, run these steps: + +
Let notifyList be a clone of + unit of related similar-origin browsing contexts' mutation observer list. + +
Let signalList be a clone of + unit of related similar-origin browsing contexts' signal slot list. + +
Empty unit of related similar-origin browsing contexts' + signal slot list. + +
For each mo of notifyList, + execute a compound microtask subtask to run these steps: [[!HTML]] + +
Let records be a clone of mo's + record queue. + +
Empty mo's record queue. + +
For each node of mo's + node list, remove all + transient registered observers whose observer is + mo from node's registered observer list. + +
If records is not empty, then invoke + mo's callback with « records, mo », + and mo. If this throws an exception, then report the exception. +
For each slot of signalList, fire an event
+ named slotchange, with its {{Event/bubbles}} attribute set to true, at
+ slot.
+
Each node has a registered observer list (a list of +zero or more registered observers), which is initially empty. + +
A registered observer consists of an +observer (a {{MutationObserver}} object) and +options (a {{MutationObserverInit}} dictionary). + +
A transient registered observer is a +registered observer that also consists of a +source (a registered observer). + +
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 {{MutationObserverInit/subtree}} is set to true on node's +parent. + + +
+[Constructor(MutationCallback callback),
+ Exposed=Window]
+interface MutationObserver {
+ void observe(Node target, optional MutationObserverInit options);
+ void disconnect();
+ sequence<MutationRecord> takeRecords();
+};
+
+callback MutationCallback = void (sequence<MutationRecord> mutations, MutationObserver observer);
+
+dictionary MutationObserverInit {
+ boolean childList = false;
+ boolean attributes;
+ boolean characterData;
+ boolean subtree = false;
+ boolean attributeOldValue;
+ boolean characterDataOldValue;
+ sequence<DOMString> attributeFilter;
+};
+
+
+A {{MutationObserver}} object can be used to observe mutations to the tree of +nodes. + +
Each {{MutationObserver}} object has these associated concepts: + +
observer = new {{MutationObserver(callback)}}
+ observer . {{observe(target, options)}}
+ observer . {{disconnect()}}
+ observer . {{takeRecords()}}
+ The
+MutationObserver(callback)
+constructor, when invoked, must run these steps:
+
+
Let mo be a new {{MutationObserver}} object whose + callback is callback. + +
Append mo to + unit of related similar-origin browsing contexts' mutation observer list. + +
Return mo. +
The
+observe(target, options)
+method, when invoked, must run these steps:
+
+
If either options's {{MutationObserverInit/attributeOldValue}} or + {{MutationObserverInit/attributeFilter}} is present and options's + {{MutationObserverInit/attributes}} is omitted, then set options's + {{MutationObserverInit/attributes}} to true. + +
If options's {{MutationObserverInit/characterDataOldValue}} is present and + options's {{MutationObserverInit/characterData}} is omitted, then set + options's {{MutationObserverInit/characterData}} to true. + +
If none of options's {{MutationObserverInit/childList}},
+ {{MutationObserverInit/attributes}}, and {{MutationObserverInit/characterData}} is true, then
+ throw a TypeError.
+
+
If options's {{MutationObserverInit/attributeOldValue}} is true and
+ options's {{MutationObserverInit/attributes}} is false, then throw a
+ TypeError.
+
+
If options's {{MutationObserverInit/attributeFilter}} is present and
+ options's {{MutationObserverInit/attributes}} is false, then throw a
+ TypeError.
+
+
If options's {{MutationObserverInit/characterDataOldValue}} is true and
+ options's {{MutationObserverInit/characterData}} is false, then throw a
+ TypeError.
+
+
For each registered of target's + registered observer list, if registered's + observer is the context object: + +
For each node of the context object's + node list, remove all + transient registered observers whose source is + registered from node's registered observer list. + +
Set registered's options to + options. +
Otherwise: + +
Append a new registered observer whose + observer is the context object and + options is options to target's + registered observer list. + +
Append target to the context object's + node list. +
The disconnect() method, when invoked, must
+run these steps:
+
+
For each node of the context object's + node list, remove any registered observer from + node's registered observer list for which the context object is the + observer. + +
Empty the context object's record queue. +
The takeRecords() method, when invoked, must
+run these steps:
+
+
Let records be a clone of the context object's + record queue. + +
Empty the context object's record queue. + +
Return records. +
To queue a mutation record of type for target with +name, namespace, oldValue, addedNodes, +removedNodes, previousSibling, and nextSibling, run these steps: + +
Let interestedObservers be an empty map. + +
Let nodes be the inclusive ancestors of target. + +
For each node in nodes, and then for each + registered of node's registered observer list: + +
Let options be registered's + options. + +
If none of the following are true + +
attributes" and options's
+ {{MutationObserverInit/attributes}} is not true
+
+
+ attributes", options's
+ {{MutationObserverInit/attributeFilter}} is present, and options's
+ {{MutationObserverInit/attributeFilter}} does not contain name or
+ namespace is non-null
+
+ characterData" and options's
+ {{MutationObserverInit/characterData}} is not true
+
+
+ childList" and options's
+ {{MutationObserverInit/childList}} is false
+ then: + +
Let mo be registered's observer. + +
If interestedObservers[mo] does not exist, then + set interestedObservers[mo] to null. + +
If either type is "attributes" and options's
+ {{MutationObserverInit/attributeOldValue}} is true, or type is
+ "characterData" and options's
+ {{MutationObserverInit/characterDataOldValue}} is true, then set
+ interestedObservers[mo] to oldValue.
+
For each observer → mappedOldValue of + interestedObservers: + +
Let record be a new {{MutationRecord}} object with its {{MutationRecord/type}} + set to type, {{MutationRecord/target}} set to target, + {{MutationRecord/attributeName}} set to name, {{MutationRecord/attributeNamespace}} + set to namespace, {{MutationRecord/oldValue}} set to mappedOldValue, + {{MutationRecord/addedNodes}} set to addedNodes, + {{MutationRecord/removedNodes}} set to removedNodes, + {{MutationRecord/previousSibling}} set to previousSibling, and + {{MutationRecord/nextSibling}} set to nextSibling. + +
Enqueue record to observer's + record queue. +
To queue a tree mutation record for target with
+addedNodes, removedNodes, previousSibling, and
+nextSibling, queue a mutation record of "childList" for
+target with null, null, null, addedNodes, removedNodes,
+previousSibling, and nextSibling.
+
+
To queue an attribute mutation record for target with
+name, namespace, and oldValue, queue a mutation record of
+"attributes" for target with name, namespace,
+oldValue, « », « », null, and null.
+
+
+
+[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 . {{MutationRecord/type}}
+ attributes" if it was an
+ attribute mutation.
+ "characterData" if it was a mutation to a
+ {{CharacterData}} node. And
+ "childList" if it was a mutation to the
+ tree of
+ nodes.
+
+ record . {{MutationRecord/target}}
+ attributes", it is the
+ element whose
+ attribute changed. For
+ "characterData", it is the {{CharacterData}}
+ node. For "childList",
+ it is the node whose
+ children changed.
+
+ record . {{MutationRecord/addedNodes}}
+ record . {{MutationRecord/removedNodes}}
+ record . {{MutationRecord/previousSibling}}
+ record . {{MutationRecord/nextSibling}}
+ record . {{MutationRecord/attributeName}}
+ record . {{MutationRecord/attributeNamespace}}
+ record . {{MutationRecord/oldValue}}
+ 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, target, +addedNodes, +removedNodes, +previousSibling, +nextSibling, +attributeName, +attributeNamespace, and +oldValue attributes must return the values they were +initialized to. + + +
Nodes have a strong reference to registered observers in their +registered observer list. + +
Registered observers in a node's registered observer list have a weak +reference to the node. + + +
+[Exposed=Window]
+interface Node : EventTarget {
+ const unsigned short ELEMENT_NODE = 1;
+ const unsigned short ATTRIBUTE_NODE = 2;
+ const unsigned short TEXT_NODE = 3;
+ const unsigned short CDATA_SECTION_NODE = 4;
+ const unsigned short ENTITY_REFERENCE_NODE = 5; // historical
+ const unsigned short ENTITY_NODE = 6; // historical
+ const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
+ const unsigned short COMMENT_NODE = 8;
+ const unsigned short DOCUMENT_NODE = 9;
+ const unsigned short DOCUMENT_TYPE_NODE = 10;
+ const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
+ const unsigned short NOTATION_NODE = 12; // historical
+ readonly attribute unsigned short nodeType;
+ readonly attribute DOMString nodeName;
+
+ readonly attribute USVString baseURI;
+
+ readonly attribute boolean isConnected;
+ readonly attribute Document? ownerDocument;
+ Node getRootNode(optional GetRootNodeOptions options);
+ 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 boolean deep = false);
+ boolean isEqualNode(Node? otherNode);
+ boolean isSameNode(Node? otherNode); // historical alias of ===
+
+ const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
+ const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
+ const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
+ const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
+ const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
+ const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
+ unsigned short compareDocumentPosition(Node other);
+ boolean contains(Node? other);
+
+ DOMString? lookupPrefix(DOMString? namespace);
+ DOMString? lookupNamespaceURI(DOMString? prefix);
+ boolean isDefaultNamespace(DOMString? namespace);
+
+ [CEReactions] Node insertBefore(Node node, Node? child);
+ [CEReactions] Node appendChild(Node node);
+ [CEReactions] Node replaceChild(Node node, Node child);
+ [CEReactions] Node removeChild(Node child);
+};
+
+dictionary GetRootNodeOptions {
+ boolean composed = false;
+};
+
+
+{{Node}} is an abstract interface and does not exist as node. It +is used by all nodes ({{Document}}, {{DocumentType}}, {{DocumentFragment}}, {{Element}}, +{{Text}}, {{ProcessingInstruction}}, and {{Comment}}). + +
Each node has an associated +node document, set upon creation, that is a +document. + +
A node's node document can be changed by the +adopt algorithm. + +
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. + +
Each node also has a registered observer list. + +
node . {{Node/nodeType}}
+ {{Node}} . {{Node/ELEMENT_NODE}} (1)
+ {{Node}} . {{Node/TEXT_NODE}} (3)
+ {{Node}} . {{Node/CDATA_SECTION_NODE}} (4)
+ {{Node}} . {{Node/PROCESSING_INSTRUCTION_NODE}} (7)
+ {{Node}} . {{Node/COMMENT_NODE}} (8)
+ {{Node}} . {{Node/DOCUMENT_NODE}} (9)
+ {{Node}} . {{Node/DOCUMENT_TYPE_NODE}} (10)
+ {{Node}} . {{Node/DOCUMENT_FRAGMENT_NODE}} (11)
+ node . {{Node/nodeName}}
+ #text".
+
+ #cdata-section".
+
+ #comment".
+
+ #document".
+
+ #document-fragment".
+ The nodeName attribute's getter, when invoked, must return the +first matching statement, switching on the context object: + +
#text".
+
+ #cdata-section".
+
+ #comment".
+
+ #document".
+
+ #document-fragment".
+node . {{Node/baseURI}}
+ baseURI attribute's getter must return
+node document's document base URL, serialized.
+
+node . {{Node/isConnected}}
+ Returns true if node is connected and false otherwise. + +
node . {{Node/ownerDocument}}
+ node . {{Node/getRootNode()}}
+ node . getRootNode({ composed:true })
+ node . {{Node/parentNode}}
+ node . {{Node/parentElement}}
+ node . {{Node/hasChildNodes()}}
+ node . {{Node/childNodes}}
+ node . {{Node/firstChild}}
+ node . {{Node/lastChild}}
+ node . {{Node/previousSibling}}
+ node . {{Node/nextSibling}}
+ The isConnected attribute's getter must return true,
+if context object is connected, and false otherwise.
The ownerDocument attribute's getter must return null,
+if the context object is a document, and the context object's
+node document otherwise.
+
+
The node document of a document is that document itself. All +nodes have a node document at all times. + +
The getRootNode(options) method, when invoked,
+must return context object's shadow-including root if options's
+{{GetRootNodeOptions/composed}} is true, and context object's root otherwise.
+
+
The parentNode attribute's getter must return the
+context object's parent.
+
+
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.
+
+
An {{Attr}} node has no siblings. + +
The nextSibling attribute's getter must return the
+context object's next sibling.
+
+
Set an existing attribute value with context object and new value. + +
Replace data with node context object, offset 0, count context object's + length, and data new value. + +
Do nothing. +
The textContent attribute's getter must return the
+following, switching on context object:
+
+
The {{Node/textContent}} attribute's setter must, if the given value is null, act as if it was +the empty string instead, and then do as described below, switching on context object: + +
Let node be null. + +
If the given value is not the empty string, set node to a new {{Text}} + node whose data is the given value and + node document is context object's node document. + +
Replace all with node within the context object. +
Set an existing attribute value with context object and new value. + +
Replace data with node context object, offset 0, count context object's + length, and data the given value. + +
Do nothing. +
node . {{Node/normalize()}}
+ Text nodes and concatenates the
+ data of remaining contiguous exclusive Text 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:
+
+
Text node, if any.
+
+ Text nodes (excluding itself), in
+ tree order.
+
+ While currentNode is an exclusive Text node:
+
+
For each live range whose start node is currentNode, + add length to its start offset and set its + start node to node. + +
For each live range whose end node is currentNode, add + length to its end offset and set its end node to + node. + +
For each live 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 live 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. +
Text nodes
+ (excluding itself), in tree order.
+{{Node/normalize()}} does not need to run any +child text content change steps, since although it messes with {{Text}} nodes extensively, it +does so specifically in a way that preserves the child text content. + +
node . cloneNode([deep = false])
+ node . {{Node/isEqualNode(otherNode)}}
+ 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 the result of creating an element, given
+ document, node's local name, node's
+ namespace, node's namespace prefix, and
+ node's is value, with the synchronous custom elements
+ flag unset.
+
+
For each attribute in node's + attribute list: + +
+Otherwise, let copy be a node that implements the same interfaces as + node, and fulfills these additional requirements, switching on + node: + +
Set copy's encoding, content type, + URL, origin, type, and + mode, to those of node. + +
Set copy's name, public ID, and + system ID, to those of node. + +
Set copy's namespace, namespace prefix, + local name, and value, to those of node. + +
Set copy's node document and document to + copy, if copy is a document, and set copy's + node document to document otherwise. + +
The cloneNode(deep) method, when
+invoked, must run these steps:
+
+
If context object is a shadow root, then throw a + "{{NotSupportedError!!exception}}" {{DOMException}}. + +
Return a clone of the context object, with the + clone children flag set if deep is true. +
The isEqualNode(otherNode) method, when
+invoked, must return true if otherNode is non-null and context object
+equals otherNode, and false otherwise.
+
+
The isSameNode(otherNode) method, when
+invoked, must return true if otherNode is context object, and false otherwise.
+
+
node . {{compareDocumentPosition(other)}}
+ {{Node}} . {{Node/DOCUMENT_POSITION_DISCONNECTED}} (1)
+ {{Node}} . {{Node/DOCUMENT_POSITION_PRECEDING}} (2)
+ {{Node}} . {{Node/DOCUMENT_POSITION_FOLLOWING}} (4)
+ {{Node}} . {{Node/DOCUMENT_POSITION_CONTAINS}} (8)
+ {{Node}} . {{Node/DOCUMENT_POSITION_CONTAINED_BY}} (16, 10 in hexadecimal)
+ node . {{Node/contains(other)}}
+ 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 attr in node2's + attribute list: + +
If attr equals attr1, then return the result of + adding {{Node/DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC}} and + {{Node/DOCUMENT_POSITION_PRECEDING}}. + +
If attr equals attr2, then return the result of + adding {{Node/DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC}} and + {{Node/DOCUMENT_POSITION_FOLLOWING}}. +
If node1 or node2 is null, or node1's root is + not node2's root, then return the result of adding + {{Node/DOCUMENT_POSITION_DISCONNECTED}}, {{Node/DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC}}, and + either {{Node/DOCUMENT_POSITION_PRECEDING}} or {{Node/DOCUMENT_POSITION_FOLLOWING}}, with the + constraint that this is to be consistent, together. + +
Whether to return {{Node/DOCUMENT_POSITION_PRECEDING}} or
+ {{Node/DOCUMENT_POSITION_FOLLOWING}} is typically implemented via pointer comparison. In
+ JavaScript implementations a cached Math.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 {{Node/DOCUMENT_POSITION_CONTAINS}} to {{Node/DOCUMENT_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 {{Node/DOCUMENT_POSITION_CONTAINED_BY}} to {{Node/DOCUMENT_POSITION_FOLLOWING}}. + +
If node1 is preceding node2, then return + {{Node/DOCUMENT_POSITION_PRECEDING}}. + +
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 {{Node/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: + +
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. +
If its document element is null, then return null. + +
Return the result of running locate a namespace on its document element + using prefix. +
Return null. + +
If its element is null, then return null. + +
Return the result of running locate a namespace on its element + using prefix. +
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: + +
Return the result of locating a namespace prefix for it using namespace. + +
Return the result of locating a namespace prefix for its document element, + if its document element is non-null, and null otherwise. + +
Return null. + +
Return the result of locating a namespace prefix for its element, + if its element is non-null, and null otherwise. + +
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 qualified name qualifiedName +for a node root is the {{HTMLCollection}} returned by the following algorithm: + +
If qualifiedName is "*" (U+002A), return a {{HTMLCollection}} rooted
+ at root, whose filter matches only descendant 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 + qualified name is qualifiedName, in ASCII lowercase. + +
Whose namespace is not the HTML namespace and whose + qualified name is qualifiedName. +
Otherwise, return a {{HTMLCollection}} rooted at root, whose filter matches + descendant elements whose qualified name is + qualifiedName. +
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: + +
*" (U+002A), return a {{HTMLCollection}} rooted at
+ root, whose filter matches
+ descendant
+ elements.
+
+ *"
+ (U+002A), return a {{HTMLCollection}} rooted at
+ root, whose filter matches
+ descendant
+ elements whose
+ local name is
+ localName.
+
+ *"
+ (U+002A), return a {{HTMLCollection}} rooted at
+ root, whose filter matches
+ descendant
+ elements whose
+ namespace is
+ namespace.
+
+ 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.
+
+[Constructor,
+ Exposed=Window]
+interface Document : 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 DOMString charset; // historical alias of .characterSet
+ readonly attribute DOMString inputEncoding; // historical alias of .characterSet
+ readonly attribute DOMString contentType;
+
+ readonly attribute DocumentType? doctype;
+ readonly attribute Element? documentElement;
+ HTMLCollection getElementsByTagName(DOMString qualifiedName);
+ HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
+ HTMLCollection getElementsByClassName(DOMString classNames);
+
+ [CEReactions, NewObject] Element createElement(DOMString localName, optional (DOMString or ElementCreationOptions) options);
+ [CEReactions, NewObject] Element createElementNS(DOMString? namespace, DOMString qualifiedName, optional (DOMString or ElementCreationOptions) options);
+ [NewObject] DocumentFragment createDocumentFragment();
+ [NewObject] Text createTextNode(DOMString data);
+ [NewObject] CDATASection createCDATASection(DOMString data);
+ [NewObject] Comment createComment(DOMString data);
+ [NewObject] ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
+
+ [CEReactions, NewObject] Node importNode(Node node, optional boolean deep = false);
+ [CEReactions] Node adoptNode(Node node);
+
+ [NewObject] Attr createAttribute(DOMString localName);
+ [NewObject] Attr createAttributeNS(DOMString? namespace, DOMString qualifiedName);
+
+ [NewObject] Event createEvent(DOMString interface);
+
+ [NewObject] Range createRange();
+
+ // NodeFilter.SHOW_ALL = 0xFFFFFFFF
+ [NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
+ [NewObject] TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
+};
+
+[Exposed=Window]
+interface XMLDocument : Document {};
+
+dictionary ElementCreationOptions {
+ DOMString is;
+};
+
+
+{{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]]
+[[!HTML]]
+
+Unless stated otherwise, a document's encoding is the utf-8
+encoding, content type is
+"application/xml", 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"). [[!HTML]]
+
+
No-quirks mode was originally known as "standards mode" and limited-quirks mode + was once known as "almost standards mode". They have been renamed because their details are now + defined by standards. (And because Ian Hickson vetoed their original names on the basis that they + are nonsensical.) +
A document's get the parent algorithm, given an event, returns
+null if event's {{Event/type}} attribute value is "load" or
+document does not have a browsing context, and the document's
+relevant global object otherwise.
+
+
document = new {{Document()}}
+ document . {{Document/implementation}}
+ document . {{Document/URL}}
+ document . {{Document/documentURI}}
+ document . {{Document/origin}}
+ document . {{Document/compatMode}}
+ BackCompat" if document's
+ mode is "quirks", and "CSS1Compat"
+ otherwise.
+
+ document . {{Document/characterSet}}
+ document . {{Document/contentType}}
+ The Document() constructor, when invoked, must
+return a new document whose origin is the origin of
+current global object's associated Document. [[!HTML]]
+
+
Unlike {{DOMImplementation/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 attribute's getter and
+documentURI attribute's getter must return the
+URL, serialized.
+
+The origin attribute's getter must return the
+serialization of context object's
+origin.
+
+The compatMode attribute's getter must
+return "BackCompat" if 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.
+
+
If qualifiedName is "*" returns a {{HTMLCollection}} of all
+ descendant elements.
+
+
Otherwise, returns a {{HTMLCollection}} of all descendant elements whose + qualified name is qualifiedName. (Matches case-insensitively against + elements in the HTML namespace within an HTML document.) + +
*" returns a {{HTMLCollection}} of all
+ descendant
+ elements.
+
+ If only namespace is "*" returns a
+ {{HTMLCollection}} of all
+ descendant
+ elements whose
+ local name is
+ localName.
+
+ If only localName is "*" returns a
+ {{HTMLCollection}} of all
+ descendant
+ elements whose
+ namespace is
+ namespace.
+
+ Otherwise, returns a {{HTMLCollection}} of all
+ descendant
+ elements whose
+ namespace is
+ namespace and
+ local name is
+ localName.
+
+ 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(qualifiedName)
+method, when invoked, must return the
+list of elements with qualified name qualifiedName for the context object.
+
+Thus, in an HTML document,
+document.getElementsByTagName("FOO") will match
+<FOO> elements that are not in the
+HTML namespace, and <foo> elements that are in
+the HTML namespace, but not <FOO> elements
+that are in the HTML namespace.
+
+The
+getElementsByTagNameNS(namespace, localName)
+method, 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.
+
+
+ <div id="example">
+ <p id="p1" class="aaa bbb"/>
+ <p id="p2" class="aaa ccc"/>
+ <p id="p3" class="bbb ccc"/>
+ </div>
+ 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.
+
+
If localName does not match the Name production an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}} will be thrown.
+
+
When supplied, options's {{ElementCreationOptions/is}} 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 an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}} will be thrown.
+
+
If one of the following conditions is true a "{{NamespaceError!!exception}}" {{DOMException}} + will be thrown: + +
QName production.
+ xml" and namespace is not the
+ XML namespace.
+ xmlns" and namespace is not the
+ XMLNS namespace.
+ xmlns".
+ When supplied, options's {{ElementCreationOptions/is}} can be used to create a + customized built-in element. + +
documentFragment = document . {{createDocumentFragment()}}
+ text = document . {{createTextNode(data)}}
+ text = document . {{createCDATASection(data)}}
+ comment = document . {{createComment(data)}}
+ processingInstruction = document . {{createProcessingInstruction(target, data)}}
+ Name production an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}} will be thrown.
+ If data contains "?>" an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}} will be thrown.
+The HTML Standard will e.g. define that for html
+and the HTML namespace, the {{HTMLHtmlElement}} interface is used.
+[[!HTML]]
+
+The createElement(localName, options) method, when
+invoked, must run these steps:
+
+
If localName does not match the Name production, then
+ throw an "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+
If the context object is an HTML document, then set localName to + localName in ASCII lowercase. + +
Let is be null. + +
If options is a dictionary and options's + {{ElementCreationOptions/is}} is present, then set is to it. + +
Let namespace be the HTML namespace, if the context object is an
+ HTML document or context object's content type is
+ "application/xhtml+xml", and null otherwise.
+
+
Return the result of creating an element given the context object, + localName, namespace, null, is, and with the + synchronous custom elements flag set. +
The internal createElementNS steps, given document,
+namespace, qualifiedName, and options, are as follows:
+
+
Let namespace, prefix, and localName be the result of + passing namespace and qualifiedName to validate and extract. + +
Let is be null. + +
If options is a dictionary and options's + {{ElementCreationOptions/is}} is present, then set is to it. + +
Return the result of creating an element given document, + localName, namespace, prefix, is, and with the + synchronous custom elements flag set. +
The
+createElementNS(namespace, qualifiedName, options)
+method, when invoked, must return the result of running the
+internal createElementNS steps, given context object,
+namespace, qualifiedName, and options.
+
+
{{Document/createElement()}} and {{Document/createElementNS()}}'s options
+parameter is allowed to be a string for web compatibility.
+
+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.
+
+
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!!exception}}" {{DOMException}}. + +
If data contains the string "]]>", then throw an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+
Return a new {{CDATASection}} node with its data set to data and + node document set to the context object. +
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.
+
+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:
+
+
Name production,
+ then throw an "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+ ?>", then throw an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+ No check is performed that target contains
+"xml" or ":", or that
+data contains characters that match the
+Char production.
+
+
importNode(node, deep) method,
+when invoked, must run these steps:
+
+If node is a document or shadow root, then throw a + "{{NotSupportedError!!exception}}" {{DOMException}}. + +
Return a clone of node, with context object and + the clone children flag set if deep is true. +
Let oldDocument be node's node document. + +
If node's parent is not null, remove node + from its parent. + +
If document is not oldDocument, then: + +
For each inclusiveDescendant in node's + shadow-including inclusive descendants: + +
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 custom,
+ enqueue a custom element callback reaction with inclusiveDescendant, callback
+ name "adoptedCallback", and an argument list containing oldDocument and
+ document.
+
+
For each inclusiveDescendant in node's + shadow-including inclusive descendants, in shadow-including tree order, run the + adopting steps with inclusiveDescendant and oldDocument. +
adoptNode(node) method, when invoked,
+must run these steps:
+
+createAttribute(localName) method, when
+invoked, must run these steps:
+
+If localName does not match the Name production in XML,
+ then throw an "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+
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 + |
|---|---|---|
"beforeunloadevent" | {{BeforeUnloadEvent}} | [[!HTML]] + |
"compositionevent" | {{CompositionEvent}} | [[!UIEVENTS]] + + |
"customevent" | {{CustomEvent}} | + |
"devicemotionevent" | {{DeviceMotionEvent}} | [[!DEVICE-ORIENTATION]] + |
"deviceorientationevent" | {{DeviceOrientationEvent}} + | |
"dragevent" | {{DragEvent}} | [[!HTML]] + |
"event" | {{Event}} | + |
"events"
+
+ | ||
"focusevent" | {{FocusEvent}} | [[!UIEVENTS]] + |
"hashchangeevent" | {{HashChangeEvent}} | [[!HTML]] + |
"htmlevents" | {{Event}} | + |
"keyboardevent" | {{KeyboardEvent}} | [[!UIEVENTS]] + |
"messageevent" | {{MessageEvent}} | [[!HTML]] + |
"mouseevent" | {{MouseEvent}} | [[!UIEVENTS]] + |
"mouseevents"
+ | ||
"storageevent" | {{StorageEvent}} | [[!HTML]] + |
"svgevents" | {{Event}} | + |
"textevent" | {{CompositionEvent}} | [[!UIEVENTS]] + |
"touchevent" | {{TouchEvent}} | [[!TOUCH-EVENTS]] + |
"uievent" | {{UIEvent}} | [[!UIEVENTS]] + |
"uievents"
+ |
If constructor is null, then throw a "{{NotSupportedError!!exception}}" + {{DOMException}}. + +
If the interface indicated by constructor is not exposed on the relevant global + object of the context object, then throw a "{{NotSupportedError!!exception}}" + {{DOMException}}. + +
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 {{Event/type}} attribute to the empty string. + +
Initialize event's {{Event/timeStamp}} attribute to a {{DOMHighResTimeStamp}} + representing the high resolution time from the time origin to now. + +
Initialize event's {{Event/isTrusted}} attribute to false. + +
Unset event's initialized flag. + +
Return event. +
Event constructors ought to be used instead. + +
The createRange() method, when invoked, must return a
+new live range with (context object, 0) as its start and
+end.
+
+
The {{Range/Range()}} constructor can be used instead. + +
The
+createNodeIterator(root, whatToShow, filter)
+method, when invoked, must run these steps:
+
+
Let iterator be a new {{NodeIterator}} object. + +
Set iterator's pointer before reference to true. + +
Set iterator's whatToShow to whatToShow. + +
Set iterator's filter to filter. + +
Return iterator. +
The
+createTreeWalker(root, whatToShow, filter)
+method, when invoked, must run these steps:
+
+
Let walker be a new {{TreeWalker}} object. + +
Set walker's whatToShow to whatToShow. + +
Set walker's filter to filter. + +
+[Exposed=Window]
+interface DOMImplementation {
+ [NewObject] DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
+ [NewObject] XMLDocument createDocument(DOMString? namespace, [TreatNullAs=EmptyString] DOMString qualifiedName, optional DocumentType? doctype = null);
+ [NewObject] Document createHTMLDocument(optional DOMString title);
+
+ boolean hasFeature(); // useless; always returns true
+};
+
+
+doctype = document . {{Document/implementation}} . {{createDocumentType(qualifiedName, publicId, systemId)}}
+
+ Name production, an
+ "{{InvalidCharacterError!!exception}}" {{DOMException}} is thrown, and if it does not match the
+ QName production, a
+ "{{NamespaceError!!exception}}" {{DOMException}} is thrown.
+
+ doc = document . {{Document/implementation}} . createDocument(namespace, qualifiedName [, doctype = null])
+
+ doc = document . {{Document/implementation}} . createHTMLDocument([title])
+
+ 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. +
No check is performed that publicId code points match the
+PubidChar production or that systemId does not contain both a
+'"' and a "'".
+
+
The
+createDocument(namespace, qualifiedName, doctype)
+method, when invoked, must run these steps:
+
+
Let document be a new {{XMLDocument}}. + +
Let element be null. + +
If qualifiedName is not the empty string, then set element to the
+ result of running the internal createElementNS steps, given
+ document, namespace, qualifiedName, and an empty dictionary.
+
+
If doctype is non-null, append doctype to document. + +
If element is non-null, append element to document. + +
document's origin is context object's associated + document's origin. + +
document's content type is determined by namespace: + +
application/xhtml+xml
+
+ image/svg+xml
+
+ application/xml
+ Return document. +
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".
+
+
Append a new doctype, with "html" as its
+ name and with its node document set to doc, to
+ doc.
+
+
Append the result of creating an element given doc, <{html}>, and + the HTML namespace, to doc. + +
Append the result of creating an element given doc, <{head}>, and + the HTML namespace, to the <{html}> element created earlier. + +
If title is given: + +
Append the result of creating an element given doc, <{title}>, + and the HTML namespace, to the <{head}> element created earlier. + +
Append a new {{Text}} node, with its data set to + title (which could be the empty string) and its node document set to + doc, to the <{title}> element created earlier. +
Append the result of creating an element given doc, <{body}>, and + the HTML namespace, to the <{html}> element created earlier.
doc's origin is context object's associated + document's origin. + +
Return doc. +
hasFeature() method, when
+invoked, must return true.
+
+{{hasFeature()}} originally would report whether the user agent +claimed to support a given DOM feature, but experience proved it was not nearly as +reliable or granular as simply checking whether the desired objects, attributes, or +methods existed. As such, it is no longer to be used, but continues to exist (and simply +returns true) so that old pages don't stop working. + +
+[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.
+
+
+
+[Constructor,
+ Exposed=Window]
+interface DocumentFragment : Node {
+};
+
+
+A {{DocumentFragment}} node has an associated +host (null or an +element in a different node tree). It is null unless otherwise stated. + +
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 a non-null host and +A is a host-including inclusive ancestor of B's root's +host. + +
The {{DocumentFragment}} node's host +concept is useful for HTML's <{template}> element and for shadow roots, and impacts the +pre-insert and replace algorithms. + +
tree = new {{DocumentFragment()}}
+ The DocumentFragment() constructor, when
+invoked, must return a new {{DocumentFragment}} node whose node document is
+current global object's associated Document.
+
+
+
+[Exposed=Window]
+interface ShadowRoot : DocumentFragment {
+ readonly attribute ShadowRootMode mode;
+ readonly attribute Element host;
+};
+
+enum ShadowRootMode { "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 closed-shadow-hidden from B.
+
To retarget an object A against an object +B, repeat these steps until they return an object:
+ +If one of the following is true + +
then return A. + +
The retargeting algorithm is used by event dispatch as well +as other specifications, such as Fullscreen. [[FULLSCREEN]] + + +
+[Exposed=Window]
+interface Element : 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, PutForwards=value] readonly attribute DOMTokenList classList;
+ [CEReactions, Unscopable] attribute DOMString slot;
+
+ boolean hasAttributes();
+ [SameObject] readonly attribute NamedNodeMap attributes;
+ sequence<DOMString> getAttributeNames();
+ DOMString? getAttribute(DOMString qualifiedName);
+ DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
+ [CEReactions] void setAttribute(DOMString qualifiedName, DOMString value);
+ [CEReactions] void setAttributeNS(DOMString? namespace, DOMString qualifiedName, DOMString value);
+ [CEReactions] void removeAttribute(DOMString qualifiedName);
+ [CEReactions] void removeAttributeNS(DOMString? namespace, DOMString localName);
+ [CEReactions] boolean toggleAttribute(DOMString qualifiedName, optional boolean force);
+ boolean hasAttribute(DOMString qualifiedName);
+ boolean hasAttributeNS(DOMString? namespace, DOMString localName);
+
+ Attr? getAttributeNode(DOMString qualifiedName);
+ Attr? getAttributeNodeNS(DOMString? namespace, DOMString localName);
+ [CEReactions] Attr? setAttributeNode(Attr attr);
+ [CEReactions] Attr? setAttributeNodeNS(Attr attr);
+ [CEReactions] Attr removeAttributeNode(Attr attr);
+
+ ShadowRoot attachShadow(ShadowRootInit init);
+ readonly attribute ShadowRoot? shadowRoot;
+
+ Element? closest(DOMString selectors);
+ boolean matches(DOMString selectors);
+ boolean webkitMatchesSelector(DOMString selectors); // historical alias of .matches
+
+ HTMLCollection getElementsByTagName(DOMString qualifiedName);
+ HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
+ HTMLCollection getElementsByClassName(DOMString classNames);
+
+ [CEReactions] Element? insertAdjacentElement(DOMString where, Element element); // historical
+ void insertAdjacentText(DOMString where, DOMString data); // historical
+};
+
+dictionary ShadowRootInit {
+ required ShadowRootMode mode;
+};
+
+
+{{Element}} nodes are simply known as +elements. + +
Elements have an associated
+namespace,
+namespace prefix,
+local name,
+custom element state,
+custom element definition,
+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). It is null unless otherwise stated. An element is a +shadow host if its shadow root is non-null. + +
An element'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.
+
+
An element's HTML-uppercased qualified name is the return +value of 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, then set qualifiedName to + qualifiedName in ASCII uppercase. + +
User agents could optimize qualified name and +HTML-uppercased qualified name by storing them in internal slots. + +
To +create an element, +given a document, localName, namespace, and optional +prefix, is, and synchronous custom elements flag, run these steps: + +
If prefix was not given, let prefix be null. + +
If is was not given, let is be null. + +
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 steps while + catching any exceptions: + +
Let C be definition's + constructor. + +
Set result to the result of constructing C, with no + arguments. + +
If result does not implement the {{HTMLElement}} interface, then throw a
+ TypeError.
+
+
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, + then throw a "{{NotSupportedError!!exception}}" {{DOMException}}. + +
If result has children, then throw a + "{{NotSupportedError!!exception}}" {{DOMException}}. + +
If result's parent is not null, then throw a + "{{NotSupportedError!!exception}}" {{DOMException}}. + +
If result's node document is not document, then + throw a "{{NotSupportedError!!exception}}" {{DOMException}}. + +
If result's namespace is not the HTML namespace, + then throw a "{{NotSupportedError!!exception}}" {{DOMException}}. + +
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, then throw a "{{NotSupportedError!!exception}}" {{DOMException}}. + +
Set result's namespace prefix to prefix. + +
Set result's is value to null.
+
If any of these steps threw an exception, then:
+ +Report the exception. + +
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 non-null, then set result's
+ custom element state to "undefined".
+
Return result. +
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 its attribute list contains A. + +This and other specifications may define +attribute change steps for +elements. The algorithm is passed element, localName, +oldValue, value, and namespace. + +To change an +attribute attribute +from an element element +to value, run these steps: + +
Queue an attribute mutation record for element with attribute's + local name, attribute's namespace, and + attribute's value. + +
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. + +
Queue an attribute mutation record for element with attribute's + local name, attribute's namespace, and null. + +
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, null, attribute's value, and + attribute's namespace. + +
Queue an attribute mutation record for element with attribute's + local name, attribute's namespace, and + attribute's value. + +
attributeChangedCallback", and an argument list containing attribute's
+ local name, attribute's value, null, and
+ attribute's namespace.
+
+ Run the attribute change steps with element, attribute's + local name, attribute's value, null, and + attribute's namespace. + +
Queue an attribute mutation record for element with oldAttr's + local name, oldAttr's namespace, and + oldAttr's value. + +
attributeChangedCallback", and an argument list containing oldAttr's
+ local name, oldAttr's value, newAttr's
+ value, and oldAttr's namespace.
+
+ Run the attribute change steps with element, oldAttr's + local name, oldAttr's value, newAttr's + value, and oldAttr's namespace. + +
Replace oldAttr by newAttr in element's + attribute list. + +
Set oldAttr's element to null. + +
Set newAttr's element to element. +
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 value given an +element element, localName, and optionally a 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.
If attr's element is neither null nor element, + throw an "{{InUseAttributeError!!exception}}" {{DOMException}}. + +
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. +
Let attr be the result of + getting an attribute given + qualifiedName and element. + +
If attr is non-null, remove it from + element. + +
Return attr. +
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 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.
+
While this specification defines requirements for class,
+id, and slot attributes on any element, it makes no
+claims as to whether using them is conforming or not.
+
+
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 return the
+context object's HTML-uppercased qualified name.
+
+
element . id [ = value ]
+ Returns the value of element's id content attribute. Can be set to
+ change it.
+
+
element . className [ = value ]
+ Returns the value of element's class content attribute. Can be set
+ to change it.
+
+
element . classList
+ Allows for manipulation of element's class content attribute as a
+ set of whitespace-separated tokens through a {{DOMTokenList}} object.
+
+
element . slot [ = value ]
+ Returns the value of element's slot content attribute. Can be set to
+ change it.
+
IDL attributes that are defined to reflect a +content attribute of a given name, must have a getter and setter that follow these +steps:
+ +Return the result of running get an attribute value given context object and + name.
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 a
+{{DOMTokenList}} object whose associated element is the context object and whose
+associated attribute's local name is class. The token set
+of this particular {{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.
element . hasAttributes()
+ Returns true if element has attributes, and false otherwise. + +
element . getAttributeNames()
+ Returns the qualified names of all element's attributes. + Can contain duplicates. + +
element . getAttribute(qualifiedName)
+ Returns element's first attribute whose qualified name is + qualifiedName, and null if there is no such attribute otherwise. + +
element . getAttributeNS(namespace, localName)
+ Returns element's attribute whose namespace is + namespace and local name is localName, and null if there is + no such attribute otherwise. + +
element . setAttribute(qualifiedName, value)
+ Sets the value of element's first attribute whose + qualified name is qualifiedName to value. + +
element . setAttributeNS(namespace, localName, value)
+ Sets the value of element's attribute whose + namespace is namespace and local name is + localName to value. + +
element . removeAttribute(qualifiedName)
+ Removes element's first attribute whose qualified name is + qualifiedName. + +
element . removeAttributeNS(namespace, localName)
+ Removes element's attribute whose namespace is + namespace and local name is localName. + +
element . toggleAttribute(qualifiedName [, force])
+ If force is not given, "toggles" qualifiedName, removing it if it is + present and adding it if it is not present. If force is true, adds + qualifiedName. If force is false, removes qualifiedName. + +
Returns true if qualifiedName is now present, and false otherwise. + +
element . hasAttribute(qualifiedName)
+ Returns true if element has an attribute whose + qualified name is qualifiedName, and false otherwise. + +
element . hasAttributeNS(namespace, localName)
+ Returns true if element has an attribute whose namespace + is namespace and local name is localName. +
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 the
+associated {{NamedNodeMap}}.
+
+
The getAttributeNames() method, when invoked, must
+return the qualified names of the attributes in context object's
+attribute list, in order, and a new list otherwise.
+
+
These are not guaranteed to be unique. + +
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 these steps:
+
+
Let attr be the result of + getting an attribute given + namespace, localName, and the context object. + +
If attr is null, return null. + +
Return attr's value. +
The
+setAttribute(qualifiedName, value)
+method, when invoked, must run these steps:
+
+
If qualifiedName does not match the Name production in
+ XML, then throw an "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+
If the context object is in the HTML namespace and its + node document is an HTML document, then set qualifiedName to + qualifiedName in ASCII lowercase. + +
Let attribute be the first attribute in context object's + attribute list whose qualified name is qualifiedName, + and null otherwise. + + +
If attribute is null, create an attribute whose + local name is qualifiedName, value is + value, and node document is context object's + node document, then append this attribute to + context object, and then return. + +
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. + +
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(qualifiedName) method,
+when invoked, must run these steps:
+
+
If the context object is in the HTML namespace and its + node document is an HTML document, then set qualifiedName to + qualifiedName in ASCII lowercase. + +
Return true if the context object has an + attribute whose qualified name is qualifiedName, and false + otherwise. +
The toggleAttribute(qualifiedName, force)
+method, when invoked, must run these steps:
+
+
If qualifiedName does not match the Name production in
+ XML, then throw an "{{InvalidCharacterError!!exception}}" {{DOMException}}.
+
+
If the context object is in the HTML namespace and its + node document is an HTML document, then set qualifiedName to + qualifiedName in ASCII lowercase. + +
Let attribute be the first attribute in the context object's + attribute list whose qualified name is qualifiedName, + and null otherwise. + + +
If attribute is null, then: + +
If force is not given or is true, create an attribute whose + local name is qualifiedName, value is the empty + string, and node document is the context object's + node document, then append this attribute + to the context object, and then return true. + +
Return false. +
Otherwise, if force is not given or is false, + remove an attribute given qualifiedName and the + context object, and then return false. + +
Return true. +
The
+hasAttributeNS(namespace, localName)
+method, when invoked, must run these steps:
+
+
The getAttributeNode(qualifiedName)
+method, when invoked, must return the result of
+getting an attribute given qualifiedName and
+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
+setAttributeNodeNS(attr) methods, 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 does not + contain attr, then throw a "{{NotFoundError!!exception}}" + {{DOMException}}. + +
Remove attr from context object. + +
Return attr. +
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!!exception}}" {{DOMException}}. + +
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 a "{{NotSupportedError!!exception}}" {{DOMException}}.
+
+
If context object is a shadow host, then throw an + "{{InvalidStateError!!exception}}" {{DOMException}}. + +
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 {{ShadowRootInit/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)}}
+ element . {{matches(selectors)}}
+ closest(selectors)
+method, when invoked, must run these steps:
+
+matches(selectors) and
+webkitMatchesSelector(selectors) methods, when
+invoked, must run these steps:
+
+The getElementsByTagName(qualifiedName)
+method, when invoked, must return the
+list of elements with qualified name qualifiedName for context object.
+
+
The
+getElementsByTagNameNS(namespace, localName)
+method, when invoked, must return the
+list of elements with namespace namespace and local name localName for
+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. + +
afterbegin"
+ Return the result of pre-inserting node into element before + element's first child. + +
beforeend"
+ Return the result of pre-inserting node into element before + null. + +
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. + +
Throw a "{{SyntaxError!!exception}}" {{DOMException}}. +
The
+insertAdjacentElement(where, element)
+method, when invoked, must return the result of running insert adjacent, given
+context object, where, and element.
+
+
The
+insertAdjacentText(where, data)
+method, when invoked, must run these steps:
+
+
Let text be a new {{Text}} node whose data is + data and node document is context object's + node document. + +
Run insert adjacent, given context object, where, and + text. +
This method returns nothing because it existed before we had a chance to design it. + + +
+[Exposed=Window,
+ LegacyUnenumerableNamedProperties]
+interface NamedNodeMap {
+ readonly attribute unsigned long length;
+ getter Attr? item(unsigned long index);
+ getter Attr? getNamedItem(DOMString qualifiedName);
+ Attr? getNamedItemNS(DOMString? namespace, DOMString localName);
+ [CEReactions] Attr? setNamedItem(Attr attr);
+ [CEReactions] Attr? setNamedItemNS(Attr attr);
+ [CEReactions] Attr removeNamedItem(DOMString qualifiedName);
+ [CEReactions] Attr removeNamedItemNS(DOMString? namespace, DOMString localName);
+};
+
+
+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 its attribute list's size 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 attribute list's size.
+
+
The item(index) method, when
+invoked, must run these steps:
+
+
If index is equal to or greater than context object's + attribute list's size, then return null. + +
Otherwise, return context object's + attribute list[index]. +
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: + +
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.
+
+
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!!exception}}" + {{DOMException}}. + +
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!!exception}}" + {{DOMException}}. + +
Return attr. +
+[Exposed=Window]
+interface Attr : Node {
+ readonly attribute DOMString? namespaceURI;
+ readonly attribute DOMString? prefix;
+ readonly attribute DOMString localName;
+ readonly attribute DOMString 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), +value (a string), and +element (null or an +element). + +
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.
+
+
User agents could have this as an internal slot as an optimization.
+
+When an attribute is created, its
+local name is given. Unless explicitly
+given when an attribute is created, its
+namespace,
+namespace prefix, and
+element are set to null, and its
+value is set to the empty string.
+
+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 must return the
+qualified name.
+
+
The value attribute's getter must return the
+value.
+
+
To set an existing attribute value, given an attribute attribute and +string value, run these steps: + +
The {{Attr/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.
+
+
+
+[Exposed=Window]
+interface CharacterData : Node {
+ attribute [TreatNullAs=EmptyString] DOMString data;
+ readonly attribute unsigned long length;
+ DOMString substringData(unsigned long offset, unsigned long count);
+ void appendData(DOMString data);
+ void insertData(unsigned long offset, DOMString data);
+ void deleteData(unsigned long offset, unsigned long count);
+ void replaceData(unsigned long offset, unsigned long count, DOMString data);
+};
+
+
+{{CharacterData}} is an abstract interface and does not exist as +node. It is used by {{Text}}, {{ProcessingInstruction}}, and {{Comment}} 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: + +
Queue a mutation record of "characterData" for node with
+ null, null, node's data, « », « », null, and null.
+
+
For each live 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 live 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 live range whose start node is node and + start offset is greater than offset plus count, increase its + start offset by data's length and + decrease it by count. + +
For each live range whose end node is node and + end offset is greater than offset plus count, increase its + end offset by data's length and decrease + it by count. + +
The data attribute's getter must return
+context object's data. Its setter 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 return the result of running 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.
+
+
+
+[Constructor(optional DOMString data = ""),
+ Exposed=Window]
+interface Text : CharacterData {
+ [NewObject] Text splitText(unsigned long offset);
+ readonly attribute DOMString wholeText;
+};
+
+text = new Text([data = ""])
+ text . {{Text/splitText(offset)}}
+ text . {{Text/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.
+
+
The child text content of a node +node is the concatenation of the data of all +the {{Text}} node children of node, in tree order. + +
This and other specifications may define +child text content change steps for nodes. + +
The Text(data) constructor, when invoked,
+must return a new {{Text}} node whose data is data and
+node document is current global object's
+associated Document.
+
+To split a {{Text}}
+node node with offset
+offset, run these steps:
+
+
If parent is not null, then: + +
Insert new node into parent before node's + next sibling. + + +
For each live 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 live 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 live range whose start node is parent and + start offset is equal to the index of node plus 1, + increase its start offset by 1. + +
For each live range whose end node is parent and + end offset is equal to the index of node plus 1, + increase its end offset by 1. +
The splitText(offset) method, when invoked,
+must split context object with offset offset.
+
+
The wholeText attribute's getter must return the
+concatenation of the data of the
+contiguous Text nodes of the context object, in tree order.
+
+
+
+[Exposed=Window]
+interface CDATASection : Text {
+};
+
+
+
+[Exposed=Window]
+interface ProcessingInstruction : CharacterData {
+ readonly attribute DOMString target;
+};
+
+
+{{ProcessingInstruction}} nodes
+have an associated target.
+
+The target
+attribute must return the target.
+
+
+
+[Constructor(optional DOMString data = ""),
+ Exposed=Window]
+interface Comment : CharacterData {
+};
+
+
+comment = new Comment([data = ""])
+ 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.
+
+
+
+
+
{{StaticRange}} and {{Range}} objects (ranges) represent 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 an offset. So in other words, a +range represents a piece of content within a node tree between two +boundary points. + +
Ranges are frequently used in editing for selecting and copying content. + +
p
+ <img src="insanity-wolf" alt="Little-endian BOM; decode as big-endian!">
+ <em>
+ 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
+Attributes such as src and alt in the
+node tree above cannot be represented by a range. Ranges are only useful for
+nodes.
+
+
{{Range}} objects, unlike {{StaticRange}} objects, are affected by mutations to the +node tree. Therefore they are also known as live ranges. Such mutations will not +invalidate them and will try to ensure that it still represents the same piece of content. +Necessarily, a live range might itself be modified as part of the mutation to the +node tree when, e.g., part of the content it represents is mutated. + +
See the insert and remove algorithms, the +{{Node/normalize()}} method, and the replace data and split +algorithms for the hairy details. + + +
A boundary point is a tuple consisting of a +node (a node) and an +offset (a non-negative integer). + +
A correct boundary point's offset will +be between 0 and the boundary point's node's +length, inclusive. + +
The position of a +boundary point (nodeA, offsetA) relative to a boundary point +(nodeB, offsetB) is +before, +equal, or +after, as returned by these steps: + +
Assert: nodeA and nodeB have the same root. + +
If nodeA is following nodeB, then if the + position of (nodeB, offsetB) relative to + (nodeA, offsetA) is before, return + after, and if it is after, return + before. + +
If nodeA is an ancestor of nodeB: + +
+ +Return before. +
+[Exposed=Window]
+interface AbstractRange {
+ readonly attribute Node startContainer;
+ readonly attribute unsigned long startOffset;
+ readonly attribute Node endContainer;
+ readonly attribute unsigned long endOffset;
+ readonly attribute boolean collapsed;
+};
+
+
+Objects implementing the {{AbstractRange}} interface are known as +ranges. + +
A range has two associated boundary points — a +start and +end. + +
For convenience, a range's +start node is its start's +node, its +start offset is its +start's offset, its +end node is its end's +node, and its +end offset is its end's +offset. + +
A range is collapsed if its start node is its +end node and its start offset is its end offset. + +
node = range . startContainer
+ offset = range . startOffset
+ node = range . endContainer
+ offset = range . endOffset
+ collapsed = range . collapsed
+ The
+startContainer
+attribute's getter must return the context object's start node.
+
+
The startOffset
+attribute's getter must return the context object's start offset.
+
+
The endContainer
+attribute's getter must return the context object's end node.
+
+
The endOffset
+attribute's getter must return the context object's end offset.
+
+
The collapsed
+attribute's getter must return true if the context object is collapsed, and
+false otherwise.
+
+
+
+[Exposed=Window]
+interface StaticRange : AbstractRange {
+};
+
+
+A future version of the {{StaticRange}} interface will provide a non-throwing +constructor. + + +
+[Constructor,
+ Exposed=Window]
+interface Range : AbstractRange {
+ readonly attribute Node commonAncestorContainer;
+
+ void setStart(Node node, unsigned long offset);
+ void setEnd(Node node, unsigned long offset);
+ void setStartBefore(Node node);
+ void setStartAfter(Node node);
+ void setEndBefore(Node node);
+ void setEndAfter(Node node);
+ void collapse(optional boolean toStart = false);
+ void selectNode(Node node);
+ void selectNodeContents(Node node);
+
+ const unsigned short START_TO_START = 0;
+ const unsigned short START_TO_END = 1;
+ const unsigned short END_TO_END = 2;
+ const unsigned short END_TO_START = 3;
+ short compareBoundaryPoints(unsigned short how, Range sourceRange);
+
+ [CEReactions] void deleteContents();
+ [CEReactions, NewObject] DocumentFragment extractContents();
+ [CEReactions, NewObject] DocumentFragment cloneContents();
+ [CEReactions] void insertNode(Node node);
+ [CEReactions] void surroundContents(Node newParent);
+
+ [NewObject] Range cloneRange();
+ void detach();
+
+ boolean isPointInRange(Node node, unsigned long offset);
+ short comparePoint(Node node, unsigned long offset);
+
+ boolean intersectsNode(Node node);
+
+ stringifier;
+};
+
+
+Objects implementing the {{Range}} interface are known as +live ranges. + +
Algorithms that modify a tree (in particular the insert, +remove, replace data, and split algorithms) modify +live ranges associated with that tree. + +
The root of a live range is the +root of its start node. + + +
A node node is contained +in a live range range if node's root is +range's root, and (node, 0) is +after range's start, and +(node, node's length) is before +range's end. + +
A node is +partially contained in a live range +if it's an inclusive ancestor of the live 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 live range consists of all + contained nodes, plus possibly some of the contents of the + start node and end node if those are {{Text}}, + {{ProcessingInstruction}}, or {{Comment}} nodes. + +
The nodes that are contained in a live 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 start node and end node of a live range are + never contained within it. + +
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. + +
There exists a partially contained node if and only if + the start node and end node are different. + +
The {{Range/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()
+ The Range() constructor, when invoked, must return
+a new live range with
+(current global object's associated Document, 0) as its
+start and end.
+
+
The commonAncestorContainer attribute's getter must
+run these steps:
+
+
To +set the start or end +of a range to a boundary point (node, offset), run these +steps: + +
The setStart(node, offset) method,
+when invoked, must set the start of context object to boundary point
+(node, offset).
+
+
The setEnd(node, offset) method,
+when invoked, must set the end of context object to boundary point
+(node, offset).
+
+
The setStartBefore(node) method, when
+invoked, must run these steps:
+
+
The setStartAfter(node) method, when invoked,
+must run these steps:
+
+
Let parent be node's parent. + +
If parent is null, then throw an "{{InvalidNodeTypeError!!exception}}" + {{DOMException}}. + +
Set the start of the context object to boundary point + (parent, node's index plus 1). +
The setEndBefore(node), when invoked, method
+must run these steps:
+
+
The setEndAfter(node) method, when invoked,
+must run these steps:
+
+
Let parent be node's parent. + +
If parent is null, then throw an "{{InvalidNodeTypeError!!exception}}" + {{DOMException}}. + +
Set the end of the context object to boundary point + (parent, node's index plus 1). +
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, then throw an "{{InvalidNodeTypeError!!exception}}" + {{DOMException}}. + +
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 1). +
The selectNode(node) method, when invoked,
+must select node within context object.
+
+
The selectNodeContents(node) method, when
+invoked, must run these steps:
+
+
The
+compareBoundaryPoints(how, sourceRange)
+method, when invoked, must run these steps:
+
+
If how is not one of + +
then throw a "{{NotSupportedError!!exception}}" {{DOMException}}. + + +
If the position of this point relative to + other point is + +
+The deleteContents() method, when invoked, must
+run these steps:
+
+
If the context object is collapsed, then return. + + +
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. +
To extract a live range +range, run these steps: + +
Let fragment be a new {{DocumentFragment}} node whose + node document is range's start node's + node document. + +
If range is collapsed, then return fragment. + + +
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. + +
If any member of contained children is a doctype, then throw a + "{{HierarchyRequestError!!exception}}" {{DOMException}}. + + +
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 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. +
In this case, first partially contained child is + original start node. + +
Let subfragment be the result of extracting + subrange. + +
In this case, last partially contained child is + original end node. + +
Let subfragment be the result of extracting + subrange. + +
The extractContents() method, when invoked, must return
+the result of extracting the context object.
+
+
To +clone the contents +of a live range range, run these steps: + +
Let fragment be a new {{DocumentFragment}} node whose + node document is range's start node's + node document. + +
If range is collapsed, then return fragment. + + +
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. + +
If any member of contained children is a doctype, then throw a + "{{HierarchyRequestError!!exception}}" {{DOMException}}. + +
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. + +
In this case, first partially contained child is + original start node. + +
Let subfragment be the result of cloning the contents + of subrange. + +
In this case, last partially contained child is + original end node. + +
Let subfragment be the result of cloning the contents + of subrange. + +
The cloneContents() method, when invoked, must return
+the result of cloning the contents of the context object.
+
+
To insert a node +node into a live range range, run these steps: + +
If range is collapsed, then set range's + end to (parent, newOffset). +
The insertNode(node) method, when invoked,
+must insert node into the context object.
+
+
The surroundContents(newParent) method, when
+invoked, must run these steps:
+
+
+
+
If a non-{{Text}} node is partially contained in the + context object, then throw an "{{InvalidStateError!!exception}}" {{DOMException}}. + + +
If newParent is a {{Document}}, {{DocumentType}}, or {{DocumentFragment}} + node, then throw an "{{InvalidNodeTypeError!!exception}}" {{DOMException}}. + +
For historical reasons {{Text}}, {{ProcessingInstruction}}, and {{Comment}} + nodes are not checked here and end up throwing later on as a side effect. + +
Let fragment be the result of extracting the + context object. + + +
If newParent has children, then replace all with null + within newParent. + +
Insert newParent into the context object. + +
Append fragment to newParent. + +
Select newParent within the context object. + +
The cloneRange() method, when invoked, must return a new
+live range with the same start and end as the
+context object.
+
+
The detach() method, when invoked, must do nothing.
+Its functionality (disabling a {{Range}} object) was removed, but the method itself
+is preserved for compatibility.
+
+
The isPointInRange(node, offset)
+method, when invoked, must run these steps:
+
+
+
The comparePoint(node, offset)
+method, when invoked, must run these steps:
+
+
+
The intersectsNode(node) method, when
+invoked, must run these steps:
+
+
+
The stringification behavior must run +these steps: + +
Let s be the empty string. + +
If the context object's start node is the context object's + end node and it is a {{Text}} node, then return the substring of that + {{Text}} node's data beginning at the context object's + start offset and ending at the context object's + end offset. + +
If the context object's start node is a {{Text}} node, then + append the substring of that node's data from the + context object's start offset until the end to s. + +
Append the concatenation of the data of all + {{Text}} nodes that are contained in the + context object, in tree order, to s. + +
If the context object's end node is a {{Text}} node, then + append the substring of that node's data from its start until the + context object's end offset to s. + +
Return s. +
The {{createContextualFragment()}}, {{Range/getClientRects()}}, +and {{Range/getBoundingClientRect()}} methods are defined in other specifications. +[[DOM-Parsing]] +[[CSSOM-VIEW]] + + + +
{{NodeIterator}} and {{TreeWalker}} objects can be used to filter and traverse node +trees. + +
Each {{NodeIterator}} and {{TreeWalker}} object has an associated +active flag to avoid recursive +invocations. It is initially unset. + +
Each {{NodeIterator}} and {{TreeWalker}} object also has an associated +root (a node), a +whatToShow (a bitmask), and a +filter (a callback). + +
To filter a node node within +a {{NodeIterator}} or {{TreeWalker}} object traverser, run these steps: + +
If traverser's active flag is set, then throw an + "{{InvalidStateError!!exception}}" {{DOMException}}. + +
Let n be node's {{Node/nodeType}} attribute value − 1. + +
If the nth bit (where 0 is the least significant bit) of + traverser's whatToShow is not set, then return + {{NodeFilter/FILTER_SKIP}}. + + +
If traverser's filter is null, then return + {{NodeFilter/FILTER_ACCEPT}}. + +
Set traverser's active flag. + +
Let result be the return value of call a user object's operation with
+ traverser's filter, "acceptNode", and
+ « node ». If this throws an exception, then unset traverser's
+ active flag and rethrow the exception.
+
+
Unset traverser's active flag. + +
Return result. +
+[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();
+};
+
+
+{{NodeIterator}} objects can be created using the +{{createNodeIterator()}} method on {{Document}} objects. + +
Each {{NodeIterator}} object has an associated +iterator collection, which is a +collection rooted at the {{NodeIterator}} object's root, whose +filter matches any node. + +
Each {{NodeIterator}} object also has an associated reference (a +node) and pointer before reference (a boolean). + +
As mentioned earlier, {{NodeIterator}} objects have an associated +active flag, root, whatToShow, and +filter as well. + +
The NodeIterator pre-removing steps given a nodeIterator and
+toBeRemovedNode, are as follows:
+
+
If toBeRemovedNode is not an inclusive ancestor of + nodeIterator's reference, or toBeRemovedNode is + nodeIterator's root, then return. + +
If nodeIterator's pointer before reference 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 + reference to next and return. + +
Otherwise, set nodeIterator's pointer before reference to + false. + +
Steps are not terminated here. +
Set nodeIterator's reference 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, when invoked,
+must return the context object's root.
+
+
The referenceNode attribute's getter, when
+invoked, must return the context object's reference.
+
+
The pointerBeforeReferenceNode attribute's
+getter, when invoked, must return the context object's
+pointer before reference.
+
+
The whatToShow attribute's getter, when
+invoked, must return the context object's whatToShow.
+
+
The filter attribute's getter, when invoked,
+must return the context object's filter.
+
+
To traverse, given a +{{NodeIterator}} object iterator and a direction direction, run these steps: + +
Let node be iterator's reference. + +
Let beforeNode be iterator's + pointer before reference. + +
While true: + +
Branch on direction: + +
If beforeNode is false, then set node to the first node + following node in iterator's + iterator collection. If there is no such node, then + return null. + +
If beforeNode is true, then set it to false. + +
If beforeNode is true, then set node to the first node + preceding node in iterator's + iterator collection. If there is no such node, then + return null. + +
If beforeNode is false, then set it to true. +
Let result be the result of filtering node within + iterator. + +
If result is {{NodeFilter/FILTER_ACCEPT}}, then break. +
Set iterator's reference to node. + +
Set iterator's pointer before reference to + beforeNode. + +
Return node. +
The nextNode() method, when invoked, must return
+the result of traversing with the context object and next.
+
+
The previousNode() method, when invoked, must
+return the result of traversing with the context object and previous.
+
+
The detach() method, when invoked, must do
+nothing. Its functionality (disabling a {{NodeIterator}} object) was removed, but
+the method itself is preserved for compatibility.
+
+
+
+[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();
+};
+
+{{TreeWalker}} objects can be created using the {{createTreeWalker()}} +method on {{Document}} objects. + +
Each {{TreeWalker}} object has an associated current (a +node). + +
As mentioned earlier {{TreeWalker}} objects have an associated +root, whatToShow, and filter as well. + +
The root attribute's getter, when invoked, must
+return the context object's root.
+
+
The whatToShow attribute's getter, when invoked,
+must return the context object's whatToShow.
+
+
The filter attribute's getter, when invoked,
+must return the context object's filter.
+
+
The currentNode attribute's getter, when
+invoked, must return the context object's current.
+
+
The {{TreeWalker/currentNode}} attribute's setter, when invoked, must set the +context object's current to the given value. + +
The parentNode() method, when invoked, must run
+these steps:
+
+
Let node be the context object's current. + +
While node is non-null and is not the context object's + root: + +
Set node to node's parent. + +
If node is non-null and filtering node within the + context object returns {{NodeFilter/FILTER_ACCEPT}}, then set the context object's + current to node and return node. +
Return null. +
To traverse children, given a +walker and type, run these steps: + +
Let node be walker's current. + +
Set node to node's first child if type is + first, and node's last child if type is last. + +
While node is non-null: + +
Let result be the result of filtering node within + walker. + +
If result is {{NodeFilter/FILTER_ACCEPT}}, then set walker's + current to node and return node. + +
If result is {{NodeFilter/FILTER_SKIP}}, then: + +
Let child be node's first child if type + is first, and node's last child if type is last. + +
If child is non-null, then set node to child and + continue. +
While node is non-null: + +
Let sibling be node's next sibling if + type is first, and node's previous sibling if + type is last. + +
If sibling is non-null, then set node to sibling and + break. + +
Let parent be node's parent. + +
If parent is null, walker's root, or + walker's current, then return null. + +
Set node to parent. +
Return null. +
The firstChild() method, when invoked, must
+traverse children with the context object and first.
+
+
The lastChild() method, when invoked, must
+traverse children with the context object and last.
+
+
To traverse siblings, given a walker +and type, run these steps: + +
Let node be walker's current. + +
If node is root, then return null. + +
While true: + +
Let sibling be node's next sibling if + type is next, and node's previous sibling if + type is previous. + +
While sibling is non-null: + +
Set node to sibling. + +
Let result be the result of filtering node within + walker. + +
If result is {{NodeFilter/FILTER_ACCEPT}}, then set walker's + current 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 {{NodeFilter/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 node's parent. + +
If node is null or walker's root, then return + null. + +
If the return value of filtering node within walker + is {{NodeFilter/FILTER_ACCEPT}}, then return null. +
The nextSibling() method, when invoked, must
+traverse siblings with the context object and next.
+
+
The previousSibling() method, when invoked, must
+traverse siblings with the context object and previous.
+
+
The previousNode() method, when invoked, must run
+these steps:
+
+
Let node be the context object's current. + +
While node is not the context object's root: + +
Let sibling be node's previous sibling. + +
While sibling is non-null: + +
Set node to sibling. + +
Let result be the result of filtering node within + the context object. + +
While result is not {{NodeFilter/FILTER_REJECT}} and node has a + child: + +
Set node to node's last child. + +
Set result to the result of filtering node + within the context object. +
If result is {{NodeFilter/FILTER_ACCEPT}}, then set the + context object's current to node and return + node. + +
Set sibling to node's previous sibling. +
If node is the context object's root or + node's parent is null, then return null. + +
Set node to node's parent. + +
If the return value of filtering node within the + context object is {{NodeFilter/FILTER_ACCEPT}}, then set the context object's + current to node and return node. +
Return null. +
The nextNode() method, when invoked, must run these
+steps:
+
+
Let node be the context object's current. + +
Let result be {{NodeFilter/FILTER_ACCEPT}}. + +
While true: + +
While result is not {{NodeFilter/FILTER_REJECT}} and node has a + child: + +
Set node to its first child. + +
Set result to the result of filtering node within + the context object. + +
If result is {{NodeFilter/FILTER_ACCEPT}}, then set the + context object's current to node and return + node. +
Let sibling be null. + +
Let temporary be node. + +
While temporary is non-null: + +
If temporary is the context object's root, then + return null. + +
Set sibling to temporary's next sibling. + +
If sibling is non-null, then break. + +
Set temporary to temporary's parent. +
Set result to the result of filtering node within + the context object. + +
If result is {{NodeFilter/FILTER_ACCEPT}}, then set the context object's + current to node and return node. +
+[Exposed=Window]
+callback interface NodeFilter {
+ // Constants for acceptNode()
+ const unsigned short FILTER_ACCEPT = 1;
+ const unsigned short FILTER_REJECT = 2;
+ const unsigned short FILTER_SKIP = 3;
+
+ // Constants for whatToShow
+ const unsigned long SHOW_ALL = 0xFFFFFFFF;
+ const unsigned long SHOW_ELEMENT = 0x1;
+ const unsigned long SHOW_ATTRIBUTE = 0x2;
+ const unsigned long SHOW_TEXT = 0x4;
+ const unsigned long SHOW_CDATA_SECTION = 0x8;
+ const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // historical
+ const unsigned long SHOW_ENTITY = 0x20; // historical
+ const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40;
+ const unsigned long SHOW_COMMENT = 0x80;
+ const unsigned long SHOW_DOCUMENT = 0x100;
+ const unsigned long SHOW_DOCUMENT_TYPE = 0x200;
+ const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400;
+ const unsigned long SHOW_NOTATION = 0x800; // historical
+
+ unsigned short acceptNode(Node node);
+};
+
+
+{{NodeFilter}} objects can be used as filter for +{{NodeIterator}} and {{TreeWalker}} objects and also provide constants for their +whatToShow bitmask. A {{NodeFilter}} object is typically implemented as a +JavaScript function. + +
These constants can be used as filter return value: + +
FILTER_ACCEPT (1);
+ FILTER_REJECT (2);
+ FILTER_SKIP (3).
+These constants can be used for whatToShow: + +
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).
+Yes, the name {{DOMTokenList}} is an unfortunate legacy mishap. + +
+[Exposed=Window]
+interface DOMTokenList {
+ readonly attribute unsigned long length;
+ getter DOMString? item(unsigned long index);
+ boolean contains(DOMString token);
+ [CEReactions] void add(DOMString... tokens);
+ [CEReactions] void remove(DOMString... tokens);
+ [CEReactions] boolean toggle(DOMString token, optional boolean force);
+ [CEReactions] boolean replace(DOMString token, DOMString newToken);
+ boolean supports(DOMString token);
+ [CEReactions] stringifier attribute DOMString value;
+ iterable<DOMString>;
+};
+
+
+A {{DOMTokenList}} object has an associated +token set (a 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, 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 {{DOMTokenList}} object's update steps are: + +
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.
+ +A {{DOMTokenList}} object has these attribute change steps for its associated +element: + +
If localName is associated attribute's local name, + namespace is null, and value is null, then empty + token set. + +
Otherwise, if localName is associated attribute's local name, + namespace is null, then set token set to value, + parsed. +
When a {{DOMTokenList}} object is created, then: + +
Let element be associated element. + +
Let localName be associated attribute's local name. + +
Let value be the result of + getting an attribute given null, + localName, and element. + +
Run the attribute change steps for element, localName, + value, value, and null. +
tokenlist . {{DOMTokenList/length}}
+ Returns the number of tokens. + +
tokenlist . {{DOMTokenList/item(index)}}
+ tokenlist[index]
+ Returns the token with index index. + +
tokenlist . {{DOMTokenList/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!!exception}}" {{DOMException}} if one of the arguments is the empty + string. +
Throws an "{{InvalidCharacterError!!exception}}" {{DOMException}} if one of the arguments + contains any ASCII whitespace. + +
tokenlist . remove(tokens…)
+ Removes arguments passed, if they are present. +
Throws a "{{SyntaxError!!exception}}" {{DOMException}} if one of the arguments is the empty + string. +
Throws an "{{InvalidCharacterError!!exception}}" {{DOMException}} 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 present. If force is true, adds token + (same as {{add()}}). If force is false, removes token (same + as {{DOMTokenList/remove()}}). +
Returns true if token is now present, and false otherwise. +
Throws a "{{SyntaxError!!exception}}" {{DOMException}} if token is empty. +
Throws an "{{InvalidCharacterError!!exception}}" {{DOMException}} if token contains + any spaces. + +
tokenlist . replace(token, newToken)
+ Replaces token with newToken. +
Returns true if token was replaced with newToken, and false otherwise. +
Throws a "{{SyntaxError!!exception}}" {{DOMException}} if one of the arguments is the empty + string. +
Throws an "{{InvalidCharacterError!!exception}}" {{DOMException}} 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 . {{DOMTokenList/value}}
+ Returns the associated set as string. +
Can be set, to change the associated attribute. +
The length attribute' getter must return
+context object's token set's size.
+
+
The object's supported property indices are the numbers in the range zero to object's +token set's size 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 context object's token set's + size, then return null. + +
Return context object's token set[index]. +
The contains(token) method, when
+invoked, must return true if context object's token set[token]
+exists, 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!!exception}}" + {{DOMException}}. + +
If token contains any ASCII whitespace, then throw an + "{{InvalidCharacterError!!exception}}" {{DOMException}}. +
For each token in tokens, append + token to context object's 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!!exception}}" + {{DOMException}}. + +
If token contains any ASCII whitespace, then throw an + "{{InvalidCharacterError!!exception}}" {{DOMException}}. +
For each token in tokens, remove token from + context object's 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!!exception}}" + {{DOMException}}. + +
If token contains any ASCII whitespace, then throw an + "{{InvalidCharacterError!!exception}}" {{DOMException}}. + +
If context object's token set[token] exists, then: + +
If force is either not given or is false, then remove + token from context object's token set, run the update steps and + return false. + +
Return true. +
Otherwise, if force not given or is true, append token + to context object's token set, run the update steps, and return true. + +
Return false. +
The update steps are not always run for {{DOMTokenList/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!!exception}}" {{DOMException}}. + +
If either token or newToken contains any ASCII whitespace, then + throw an "{{InvalidCharacterError!!exception}}" {{DOMException}}. + +
If context object's token set does not contain + token, then return false.
+ +Replace token in context object's token set with + newToken. + +
Run the update steps. + +
Return true. +
The update steps are not always run for {{DOMTokenList/replace()}} +for web compatibility. + +
The
+supports(token)
+method, when invoked, must run these steps:
+
+
Let result be the return value of validation steps called with + token. + +
Return result. +
The value attribute must return the
+result of running context object's serialize steps.
+
+
Setting the {{DOMTokenList/value}} attribute must set an attribute value for the +associated element using associated attribute's local name and +the given value. + + + +
As explained in goals this standard is a significant revision of various +obsolete DOM specifications. This section enumerates the incompatible changes. + + +
These are the changes made to the features described in the "DOM Event Architecture", +"Basic Event Interfaces", "Mutation Events", and "Mutation Name Event Types" chapters of +DOM Level 3 Events. The other chapters are defined by the UI Events +specification. [[!UIEVENTS]] + +
These are the changes made to the features described in DOM Level 3 Core. + +
{{DOMString}}, {{DOMException}}, and {{DOMTimeStamp}} are now defined in Web IDL. + +
{{DOMStringList}} is now defined in HTML. + +
hasAttributes() and
+attributes moved from {{Node}} to {{Element}}.
+
+
namespaceURI,
+prefix, and
+localName moved from {{Node}} to {{Element}} and
+{{Attr}}.
+
+
The remainder of interfaces and interface members listed in this section were removed to simplify +the web platform. Implementations conforming to this specification will not support them. + +
Interfaces: + +
DOMConfiguration
+ DOMError
+ DOMErrorHandler
+ DOMImplementationList
+ DOMImplementationSource
+ DOMLocator
+ DOMObject
+ DOMUserData
+ Entity
+ EntityReference
+ NameList
+ Notation
+ TypeInfo
+ UserDataHandler
+Interface members: + +
isSupported
+ getFeature()
+ getUserData()
+ setUserData()
+ createEntityReference()
+ xmlEncoding
+ xmlStandalone
+ xmlVersion
+ strictErrorChecking
+ domConfig
+ normalizeDocument()
+ renameNode()
+ getFeature()
+ schemaTypeInfo
+ isId
+ schemaTypeInfo
+ setIdAttribute()
+ setIdAttributeNS()
+ setIdAttributeNode()
+ entities
+ notations
+ internalSubset
+ isElementContentWhitespace
+ replaceWholeText()
+ These are the changes made to the features described in the "Document Object Model Range" chapter +of DOM Level 2 Traversal and Range. + +
These are the changes made to the features described in the "Document Object Model Traversal" +chapter of DOM Level 2 Traversal and Range. + +
There have been a lot of people that have helped make DOM more interoperable over the years and +thereby furthered the goals of this standard. Likewise many people have helped making this standard +what it is today. + +
With that, many thanks to +Adam Klein, +Adrian Bateman, +Aleksey Shvayka, +Alex Komoroske, +Alex Russell, +Anthony Ramine, +Arkadiusz Michalski, +Arnaud Le Hors, +Arun Ranganathan, +Björn Höhrmann, +Boris Zbarsky, +Brandon Payton, +Brandon Slade, +Brandon Wallace, +Brian Kardell, +Cameron McCormack, +Chris Dumez, +Chris Paris, +Chris Rebert, +Cyrille Tuzi, +Daniel Glazman, +Darin Fisher, +David Bruant, +David Flanagan, +David Håsäther, +David Hyatt, +Deepak Sherveghar, +Dethe Elza, +Dimitri Glazkov, +Domenic Denicola, +Dominic Cooney, +Dominique Hazaël-Massieux, +Don Jordan, +Doug Schepers, +Edgar Chen, +Elisée Maurer, +Elliott Sprehn, +Eric Bidelman, +Erik Arvidsson, +Gary Kacmarcik, +Gavin Nicol, +Geoffrey Sneddon, +Giorgio Liscio, +Glen Huang, +Glenn Adams, +Glenn Maynard, +Hajime Morrita, +Harald Alvestrand, +Hayato Ito, +Henri Sivonen, +Hongchan Choi, +Hunan Rostomyan, +Ian Hickson, +Igor Bukanov, +Jacob Rossi, +Jake Archibald, +Jake Verbaten, +James Graham, +James Greene, +James Robinson, +Jeffrey Yasskin, +Jens Lindström, +Jesse McCarthy, +Jinho Bang, +João Eiras, +Joe Kesselman, +John Atkins, +John Dai, +Jonas Sicking, +Jonathan Kingston, +Jonathan Robie, +Joris van der Wel, +Joshua Bell, +Jungkee Song, +Justin Summerlin, +呂康豪 (Kang-Hao Lu), +Kevin Sweeney, +Kirill Topolyan, +Koji Ishii, +Lachlan Hunt, +Lauren Wood, +Magne Andersson, +Majid Valipour, +Malte Ubl, +Manish Goregaokar, +Manish Tripathi, +Marcos Caceres, +Mark Miller, +Martijn van der Ven, +Mats Palmgren, +Mounir Lamouri, +Michael™ Smith, +Mike Champion, +Mike Taylor, +Mike West, +Ojan Vafai, +Oliver Nightingale, +Olli Pettay, +Ondřej Žára, +Peter Sharpe, +Philip Jägenstedt, +Philippe Le Hégaret, +Ra'Shaun Stovall (Snuggs), +Rafael Weinstein, +Richard Bradshaw, +Rick Byers, +Rick Waldron, +Robbert Broersma, +Robin Berjon, +Roland Steiner, +Rune F. Halvorsen, +Russell Bicknell, +Ruud Steltenpool, +Ryosuke Niwa, +Sam Dutton, +Samuel Giles, +Sebastian Mayr, +Seo Sanghyeon, +Sergey G. Grekhov, +Shiki Okasaka, +Shinya Kawanaka, +Simon Pieters, +Stef Busking, +Steve Byrne, +Stig Halvorsen, +Tab Atkins, +Takashi Sakamoto, +Takayoshi Kochi, +Theresa O'Connor, +Theodore Dubois, +timeless, +Timo Tijhof, +Tobie Langel, +Tom Pixley, +Travis Leithead, +triple-underscore, +Veli Şenol, +Vidur Apparao, +Warren He, +Xidorn Quan, +Yehuda Katz, +Yoav Weiss, +Yoichi Osato, +Yoshinori Sano, and +Zack Weinberg +for being awesome! + +
This standard is written by Anne van Kesteren +(Mozilla, annevk@annevk.nl) +with substantial contributions from Aryeh Gregor (ayg@aryeh.name) +and Ms2ger (ms2ger@gmail.com). + +
Part of the revision history of the integration points related to custom +elements can be found in +the w3c/webcomponents repository, which is +available under the +W3C Permissive Document License. + +