Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
DOM4 defines the event and document model the Web platform uses. The DOM is a language- and platform neutral interface that allows programs and scripts to dynamically access and update the content and structure of documents.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the 5 January 2012 W3C Working Draft of DOM4. Please send comments to www-dom@w3.org (archived) with [DOM] at the start of the subject line, or file a bug.
This document is produced by the Web Applications (WebApps) Working Group. The WebApps Working Group is part of the Rich Web Clients Activity in the W3C Interaction Domain.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This specification standardizes the DOM. It does so as follows:
By consolidating DOM Level 3 Core [DOM3CORE], Element Traversal [ELEMENTTRAVERSAL], the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events [DOM3EVENTS] (specific type of events do not belong in the base specification), and DOM Level 2 Traversal and Range [DOM2TR], and:
By moving features from HTML5 that ought to be part of the DOM platform here, while preventing a dependency on HTML5. [HTML]
By defining a replacement for the "Mutation Events" "Mutation Name Event Types" chapters of DOM Level 3 Events [DOM3EVENTS] as the old model was problematic.
The old model is expected to be removed from implementations in due course.
By defining new features that simplify common DOM operations.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
Unless otherwise stated, string comparisons are done in a case-sensitive manner.
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
Some of the terms used in this specification are defined in Web IDL, XML and Namespaces in XML. [WEBIDL] [XML] [XMLNS]
Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.
If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.
When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognize the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.
The term context object means the object on which the method or attribute being discussed was called. When the context object is unambiguous, the term can be omitted.
The preferred MIME name of a character encoding is the name or alias labeled as "preferred MIME name" in the IANA Character Sets registry, if there is one, or the encoding's name, if none of the aliases are so labeled. [IANACHARSET]
Just like most programming paradigms the Web platform has finite hierarchical tree structures, simply named trees. The tree order is preorder, depth-first traversal.
An object that participates in a tree has a parent, which is either another object or null, and an ordered list of zero or more child objects.
The root of an object is itself, if it has no parent, or else it is the root of its parent.
An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.
An inclusive descendant is an object or one of its descendants.
An object A is called an ancestor of an object B if and only if B is a descendant of A.
An inclusive ancestor is an object or one of its ancestors.
An object A is called a sibling of an object B, if and only if B and A share the same non-null parent.
An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order.
An object A is following an object B if A and B are in the same tree and A comes after B in tree order.
The first child of an object is its first child or null if it has no child.
The last child of an object is its last child or null if it has no child.
The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling.
The next sibling of an object is its first following sibling or null if it has no following sibling.
The index of an object is its number of preceding siblings.
Comparing two strings in a case-sensitive manner means comparing them exactly, code point for code point.
Comparing two strings in a ASCII case-insensitive manner means comparing them exactly, code point for code point, except that the characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are considered to also match.
Converting a string to ASCII uppercase means replacing all characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).
Converting a string to ASCII lowercase means replacing all characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) with the corresponding characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).
A string pattern is a prefix match for a string s when pattern is not longer than s and truncating s to pattern's length leaves the two strings as matches of each other.
The space characters, for the purposes of this specification, are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).
Some of the micro-parsers described below follow the pattern of having an input variable that holds the string being parsed, and having a position variable pointing at the next character to parse in input.
For parsers based on this pattern, a step that requires the user agent to collect a sequence of characters means that the following algorithm must be run, with characters being the set of characters that can be collected:
Let input and position be the same variables as those of the same name in the algorithm that invoked these steps.
Let result be the empty string.
While position does not point past the end of input and the character at position is one of the characters, append that character to the end of result and advance position to the next character in input.
Return result.
The step skip whitespace means that the user agent must collect a sequence of characters that are space characters. The collected characters are not used.
A set of space-separated tokens is a string containing zero or more words (known as tokens) separated by one or more space characters, where words consist of any string of one or more characters, none of which are space characters.
A string containing a set of space-separated tokens may have leading or trailing space characters.
An unordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated.
An ordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated but where the order of the tokens is meaningful.
Sets of space-separated tokens sometimes have a defined set of allowed values. When a set of allowed values is defined, the tokens must all be from that list of allowed values; other values are non-conforming. If no such set of allowed values is provided, then all values are conforming.
How tokens in a set of space-separated tokens are to be compared (e.g. case-sensitively or not) is defined on a per-set basis.
When a user agent has to split a string on spaces, it must use the following algorithm:
Let input be the string being parsed.
Let position be a pointer into input, initially pointing at the start of the string.
Let tokens be a list of tokens, initially empty.
While position is not past the end of input:
Collect a sequence of characters that are not space characters.
Add the string collected in the previous step to tokens.
Return tokens.
When a user agent has to remove a token from a string, it must use the following algorithm:
Let input be the string being modified.
Let token be the token being removed. It will not contain any space characters.
Let output be the output string, initially empty.
Let position be a pointer into input, initially pointing at the start of the string.
Loop: If position is beyond the end of input, terminate these steps.
If the character at position is a space character:
Append the character at position to the end of output.
Advance position so it points at the next character in input.
Return to the step labeled loop.
Otherwise, the character at position is the first character of a token. Collect a sequence of characters that are not space characters, and let that be s.
If s is exactly equal to token, then:
Skip whitespace (in input).
Remove any space characters currently at the end of output.
If position is not past the end of input, and output is not the empty string, append a single U+0020 SPACE character at the end of output.
Otherwise, append s to the end of output.
Return to the step labeled loop.
This causes any occurrences of the token to be removed from the string, and any spaces that were surrounding the token to be collapsed to a single space, except at the start and end of the string, where such spaces are removed.
The HTML namespace is http://www.w3.org/1999/xhtml
.
The XML namespace is http://www.w3.org/XML/1998/namespace
.
The XMLNS namespace is http://www.w3.org/2000/xmlns/
.
DOMException
exception DOMException { const unsigned short INDEX_SIZE_ERR = 1; const unsigned short DOMSTRING_SIZE_ERR = 2; // historical const unsigned short HIERARCHY_REQUEST_ERR = 3; const unsigned short WRONG_DOCUMENT_ERR = 4; const unsigned short INVALID_CHARACTER_ERR = 5; const unsigned short NO_DATA_ALLOWED_ERR = 6; // historical const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7; const unsigned short NOT_FOUND_ERR = 8; const unsigned short NOT_SUPPORTED_ERR = 9; const unsigned short INUSE_ATTRIBUTE_ERR = 10; // historical const unsigned short INVALID_STATE_ERR = 11; const unsigned short SYNTAX_ERR = 12; const unsigned short INVALID_MODIFICATION_ERR = 13; const unsigned short NAMESPACE_ERR = 14; const unsigned short INVALID_ACCESS_ERR = 15; const unsigned short VALIDATION_ERR = 16; // historical const unsigned short TYPE_MISMATCH_ERR = 17; const unsigned short SECURITY_ERR = 18; const unsigned short NETWORK_ERR = 19; const unsigned short ABORT_ERR = 20; const unsigned short URL_MISMATCH_ERR = 21; const unsigned short QUOTA_EXCEEDED_ERR = 22; const unsigned short TIMEOUT_ERR = 23; const unsigned short INVALID_NODE_TYPE_ERR = 24; const unsigned short DATA_CLONE_ERR = 25; unsigned short code; };
The code
exception
field must return the value it was initialized to. When an exception is
created it must be initialized to zero.
To throw a type exception these steps must be run:
Create a new DOMException
exception whose
type is type.
Set its message to a user agent-defined value.
If its type is in the first column of the table below and has a corresponding legacy
code
exception field value in the
third column, set its code
exception field to that value.
Throw the exception.
To
throw a "TimeoutError
" exception, a
user agent would construct a DOMException
exception whose
type is
"TimeoutError
" and
code
exception field value is 23,
and actually throw that object as an exception.
Type | Description | Legacy code exception field value (if any)
|
---|---|---|
"IndexSizeError "
| The index is not in the allowed range. | INDEX_SIZE_ERR (1)
|
"HierarchyRequestError "
| The operation would yield an incorrect node tree. | HIERARCHY_REQUEST_ERR (3)
|
"WrongDocumentError "
| The object is in the wrong document. | WRONG_DOCUMENT_ERR (4)
|
"InvalidCharacterError "
| The string contains invalid characters. | INVALID_CHARACTER_ERR (5)
|
"NoModificationAllowedError "
| The object can not be modified. | NO_MODIFICATION_ALLOWED_ERR (7)
|
"NotFoundError "
| The object can not be found here. | NOT_FOUND_ERR (8)
|
"NotSupportedError "
| The operation is not supported. | NOT_SUPPORTED_ERR (9)
|
"InvalidStateError "
| The object is in an invalid state. | INVALID_STATE_ERR (11)
|
"SyntaxError "
| The string did not match the expected pattern. | SYNTAX_ERR (12)
|
"InvalidModificationError "
| The object can not be modified in this way. | INVALID_MODIFICATION_ERR (13)
|
"NamespaceError "
| The operation is not allowed by Namespaces in XML. [XMLNS] | NAMESPACE_ERR (14)
|
"InvalidAccessError "
| The object does not support the operation or argument. | INVALID_ACCESS_ERR (15)
|
"TypeMismatchError "
| The type of the object does not match the expected type. | TYPE_MISMATCH_ERR (17)
|
"SecurityError "
| The operation is insecure. | SECURITY_ERR (18)
|
"NetworkError "
| A network error occurred. | NETWORK_ERR (19)
|
"AbortError "
| The operation was aborted. | ABORT_ERR (20)
|
"URLMismatchError "
| The given URL does not match another URL. | URL_MISMATCH_ERR (21)
|
"QuotaExceededError "
| The quota has been exceeded. | QUOTA_EXCEEDED_ERR (22)
|
"TimeoutError "
| The operation timed out. | TIMEOUT_ERR (23)
|
"InvalidNodeTypeError "
| The supplied node is incorrect or has an incorrect ancestor for this operation. | INVALID_NODE_TYPE_ERR (24)
|
"DataCloneError "
| The object can not be cloned. | DATA_CLONE_ERR (25)
|
DOMError
This interface is intended for other specifications that want to introduce error handling through other means than exceptions. It is expected that the exception types are reused.
interface DOMError { readonly attribute DOMString name; };
The name
attribute must
return the value it was initialized to.
A
type DOMError
means a DOMError
object whose
name
attribute is initialized to
type.
A specification could say that an error
attribute must return a
"SyntaxError
" DOMError
.
Event
[Constructor(DOMString type, optional EventInit eventInitDict)] interface Event { readonly attribute DOMString type; readonly attribute EventTarget? target; readonly attribute EventTarget? currentTarget; const unsigned short CAPTURING_PHASE = 1; const unsigned short AT_TARGET = 2; const unsigned short BUBBLING_PHASE = 3; readonly attribute unsigned short eventPhase; void stopPropagation(); void stopImmediatePropagation(); readonly attribute boolean bubbles; readonly attribute boolean cancelable; void preventDefault(); readonly attribute boolean defaultPrevented; readonly attribute boolean isTrusted; readonly attribute DOMTimeStamp timeStamp; void initEvent(DOMString type, boolean bubbles, boolean cancelable); }; dictionary EventInit { boolean bubbles; boolean cancelable; };
An event allows for signaling that
something has occurred. E.g. that an image has completed downloading. It is
represented by the Event
interface or an interface that
inherits from the Event
interface.
The type
attribute must
return the value it was initialized to. When an
event is created the attribute must be
initialized to the empty string.
The target
and
currentTarget
attributes must return the values they were initialized to. When an
event is created the attributes must be
initialized to null.
The target
and
currentTarget
attributes are
initialized to different values while
dispatching the
event.
The eventPhase
attribute must return the value it was initialized to, which must be one of
the following:
CAPTURING_PHASE
(numeric value 1)When an event is
dispatched on an object that
participates in a
tree it will be in this phase before it
reaches its target
attribute value.
AT_TARGET
(numeric value 2)
When an event is
dispatched it will be in this
phase on its target
attribute value.
BUBBLING_PHASE
(numeric value 3)
When an event is
dispatched on an object that
participates in a
tree it will be in this phase after it
reaches its target
attribute value.
Initially the attribute must be initialized to
AT_TARGET
.
Each event has the following associated flags that are all initially unset:
When the
stopPropagation()
method is invoked the stop propagation flag must be set.
When the
stopImmediatePropagation()
method is invoked both the stop propagation flag and
stop immediate propagation flag must be set.
The bubbles
and
cancelable
attributes
must return the values they were initialized to. When an
event is created the attributes must be
initialized to false.
When the
preventDefault()
method is invoked and the cancelable
attribute is true, the canceled flag must be set.
The defaultPrevented
attribute must return true if the canceled flag is set and
false otherwise.
The isTrusted
attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to false.
The timeStamp
attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to the number of milliseconds that has passed since
00:00:00 UTC on 1 January 1970.
When the initEvent(type, bubbles, cancelable)
method is invoked these steps must be run:
Set the initialized flag.
If the dispatch flag is set, terminate these steps.
Unset the stop propagation flag, stop immediate propagation flag, and canceled flag.
Set the isTrusted
attribute
to false.
Set the target
attribute to
null.
Set the type
attribute to the
type argument.
Set the bubbles
attribute to
the bubbles argument.
Set the cancelable
attribute
to the cancelable argument.
As events have constructors
initEvent()
is superfluous. However,
it has to be supported for legacy content.
CustomEvent
[Constructor(DOMString type, optional CustomEventInit eventInitDict)]
interface CustomEvent : Event {
readonly attribute any detail;
};
dictionary CustomEventInit : EventInit {
any detail;
};
Events using the
CustomEvent
interface can be used for synthetic events that
need to carry data.
The detail
attribute
must return the value it was initialized to. When an
event is created the attribute must be
initialized to null.
When a constructor of the Event
interface, or of an
interface that inherits from the Event
interface, is invoked,
these steps must be run:
Create an event that uses the interface the constructor was invoked upon.
Set its initialized flag.
Initialize the type
attribute to
the type argument.
If there is an eventInitDict argument then for each dictionary member defined therein find the attribute on event whose identifier matches the key of the dictionary member and then set the attribute to the value of that dictionary member.
Return the event.
EventTarget
interface EventTarget {
void addEventListener(DOMString type, EventListener? listener, optional boolean capture);
void removeEventListener(DOMString type, EventListener? listener, optional boolean capture);
boolean dispatchEvent(Event event);
};
callback interface EventListener {
void handleEvent(Event event);
};
EventTarget
is an object upon which an
event is
dispatched when something has
occurred. Each EventTarget
has an associated list of
event listeners.
An event listener is a handler for a specific event. Each event listener consists of a type (of the event), listener, and capture variable.
When the
addEventListener(type, listener, capture)
method is invoked these steps must be run:
If listener is null terminate these steps.
If capture is omitted let capture be false.
Append an event listener to the associated list of event listeners with type set to type, listener set to listener, and capture set to capture, unless there already is an event listener in that list with the same type, listener, and capture.
When the removeEventListener(type, listener, capture)
method is invoked these steps must be run:
If capture is omitted let capture be false.
Remove an event listener from the associated list of event listeners, whose type is name, listener is listener, and capture is capture.
When the
dispatchEvent(event)
method is invoked these steps must be run:
If event's dispatch flag is set, or if
its initialized flag is not set,
throw an
"InvalidStateError
" exception and terminate these steps.
Initialize event's
isTrusted
attribute to false.
Dispatch the event and return the value that returns.
To dispatch an event on a given object run these steps:
Let event be the event that is dispatched.
Set event's dispatch flag.
Initialize event's
target
attribute to the object on which
event is dispatched.
target
attribute value is
participating in a
tree
Let event path be a static ordered list of all
ancestors of
event's target
attribute value in tree order.
Initialize event's
eventPhase
attribute to
CAPTURING_PHASE
.
For each object in the event path invoke its event listeners with event event, as long as event's stop propagation flag is unset.
Initialize event's
eventPhase
attribute to
AT_TARGET
.
Invoke the
event listeners of
event's
target
attribute value with
event, if event's
stop propagation flag is unset.
If event's
bubbles
attribute is true run
these substeps:
Reverse the order of event path.
Initialize event's
eventPhase
attribute to
BUBBLING_PHASE
.
For each object in the event path invoke its event listeners, with event event as long as event's stop propagation flag is unset.
Invoke the
event listeners of
event's target
attribute value, with event event.
Unset event's dispatch flag.
Initialize event's
eventPhase
attribute to
AT_TARGET
.
Initialize event's
currentTarget
to null.
Return false if event's canceled flag is set and true otherwise.
To invoke the event listeners for an object with an event run these steps:
Let event be the event for which the event listeners are invoked.
Let listeners be a static list of the event listeners associated with the object for which these steps are run.
Initialize event's
currentTarget
to the object for
which these steps are run.
Then run these substeps for each event listener in listeners:
If event's stop immediate propagation flag is set, terminate the invoke algorithm.
Let listener be the event listener.
If event's type
attribute value is not listener's type, terminate
these substeps (and run them for the next
event listener).
If event's
eventPhase
attribute value is
CAPTURING_PHASE
and
listener's capture is false, terminate these
substeps (and run them for the next
event listener).
If event's
eventPhase
attribute value is
BUBBLING_PHASE
and
listener's capture is true, terminate these
substeps (and run them for the next
event listener).
If listener's listener is a
Function object, its
callback this value is the
event's
currentTarget
attribute value.
Call listener's listener, with the event passed to this algorithm as the first argument.
To
fire an event named e
means that an event using the
Event
interface, with its
type
attribute initialized to
e, and its isTrusted
attribute initialized to true, is to be
dispatched at the given
object.
Fire is short for initializing and dispatching an event.
Fire an event is a
concept to make initializing and
dispatching an
event easier to write down. If the
event needs its bubbles
or
cancelable
attribute initialized, one could write
"fire an event named
submit
with its cancelable
attribute
initialized to true".
Objects implementing the Document
,
DocumentFragment
, DocumentType
,
Element
, Text
, ProcessingInstruction
,
or Comment
interface (simply called
nodes)
participate in a
tree.
A tree of nodes is constrained as follows, expressed as a relationship between the type of node and its allowed children:
Document
In tree order:
Zero or more nodes each of which is either
ProcessingInstruction
or Comment
.
Optionally one DocumentType
node.
Zero or more nodes each of which is either
ProcessingInstruction
or Comment
.
Optionally one Element
node.
Zero or more nodes each of which is either
ProcessingInstruction
or Comment
.
DocumentFragment
Element
Zero or more nodes each of which is one of Element
,
ProcessingInstruction
, Comment
, or
Text
.
DocumentType
Text
ProcessingInstruction
Comment
None.
To pre-insert a node into a parent before a child, run these steps:
If parent is not a Document
,
DocumentFragment
, or Element
node,
throw a
"HierarchyRequestError
" and terminate these steps.
If node is an
inclusive ancestor of
parent, throw a
"HierarchyRequestError
" and terminate these steps.
If child is not null and its
parent is not
parent, throw a
"NotFoundError
" exception and terminate these steps.
If parent is a document, run these substeps:
If node is not a DocumentFragment
,
DocumentType
, Element
,
ProcessingInstruction
, or Comment
node,
throw a
"HierarchyRequestError
" and terminate these steps.
If node is a DocumentFragment
node, run these inner substeps:
If node has more than one
element
child or has a Text
node
child,
throw a
"HierarchyRequestError
" and terminate these steps.
If node has one
element
child and either
parent has an
element
child or child
is not null and a doctype is
following
child, throw a
"HierarchyRequestError
" and terminate these steps.
If node is an
element and either
parent has an element
child or child
is not null and a doctype is
following
child, throw a
"HierarchyRequestError
" and terminate these steps.
If node is a
doctype and either
parent has a doctype
child, an
element is
preceding
child, or child is null and
parent has an element
child,
throw a
"HierarchyRequestError
" and terminate these steps.
Otherwise if parent is a
DocumentFragment
or Element
node and node is not a
DocumentFragment
, Element
, Text
,
ProcessingInstruction
, or Comment
node,
throw a
"HierarchyRequestError
" and terminate these steps.
Adopt node with parent's node document.
Insert node into parent before child.
Return child.
To insert a node into a parent before a child, run these steps:
Let count be the number of
children of node if
it is a DocumentFragment
node,
or one otherwise.
For each range whose start node is parent and start offset is greater than child's index, increase its start offset by count.
For each range whose end node is parent and end offset is greater than child's index, increase its end offset by count.
If node is a DocumentFragment
node, insert its
children (preserving
tree order), before
child or at the end of parent if
child is null.
Otherwise insert node before child or at the end of parent if child is null.
To append a node to a parent, pre-insert node into parent before null.
To replace a child with node within a parent, run these steps:
If child's
parent is not
parent, throw a
"NotFoundError
" exception and terminate these steps.
If node is an
inclusive ancestor of
parent, throw a
"HierarchyRequestError
" and terminate these steps.
If parent is not a Document
,
DocumentFragment
, or Element
node,
throw a
"HierarchyRequestError
" and terminate these steps.
If parent is a document, run these substeps:
If node is not a DocumentFragment
,
DocumentType
, Element
,
ProcessingInstruction
, or Comment
node,
throw a
"HierarchyRequestError
" and terminate these steps.
If node is a DocumentFragment
node, run these inner substeps:
If node has more than one
element
child or has a Text
node
child,
throw a
"HierarchyRequestError
" and terminate these steps.
If node has one
element
child and either
parent has an
element
child that is not
child or a doctype
is following
child, throw a
"HierarchyRequestError
" and terminate these steps.
If node is an
element and either
parent has an element
child that is not
child or a doctype is
following
child, throw a
"HierarchyRequestError
" and terminate these steps.
If node is a
doctype and either
parent has a doctype
child that is not
child, or an element
is preceding
child, throw a
"HierarchyRequestError
" and terminate these steps.
Otherwise if parent is a
DocumentFragment
or Element
node and node is not a
DocumentFragment
, Element
, Text
,
ProcessingInstruction
, or Comment
node,
throw a
"HierarchyRequestError
" and terminate these steps.
Adopt node with parent's node document.
Let reference child be child's next sibling.
Remove child from its parent.
Insert node into parent before reference child.
Return child.
To replace all with a node within a parent, run these steps:
Adopt node with parent's node document.
Remove all parent's children, in tree order.
If node is not null, append node to parent.
This algorithm does not make any checks with regards to the node tree. Use it wisely.
To pre-remove a node from a parent, run these steps:
If child's
parent is not
parent, throw a
"NotFoundError
" exception and terminate these steps.
Remove child from parent.
Return child.
To remove a node from a parent, run these steps:
Let index be node's index.
For each range whose start node is a descendant of parent, set its start to (parent, index).
For each range whose end node is a descendant of parent, set its end to (parent, index).
For each range whose start node is parent and start offset is greater than index, decrease its start offset by one.
For each range whose end node is parent and end offset is greater than index, decrease its end offset by one.
Remove node from its parent.
The mutation method macro:
Let node be null.
Replace each string in nodes with a
Text
node whose
data is the string value.
If nodes contains more than one
node, set node to a new
DocumentFragment
and
append each
node in nodes to it. If
this throws an exception, re-throw the exception and terminate these
steps.
Otherwise, set node to the single node nodes contains.
The
prepend(nodes)
method must run these steps:
Pre-insert node into the context object before the context object's first child.
The
append(nodes)
method must run these steps:
Append node to the context object.
The
before(nodes)
method must run these steps:
If the context object does not have a parent, terminate these steps.
Pre-insert node into the context object's parent before the context object.
The
after(nodes)
method must run these steps:
If the context object does not have a parent, terminate these steps.
Pre-insert node into the context object's parent before the context object's next sibling.
The
replace(nodes)
method must run these steps:
If the context object does not have a parent, terminate these steps.
Replace the context object with node within the context object's parent.
The
remove()
method must run these steps:
If the context object does not have a parent, terminate these steps.
Remove the context object from the context object's parent.
The
insertBefore(node, child)
method must return the result of
pre-inserting
node into the context object before
child.
The
appendChild(node)
method must return the result of
appending node to
the context object.
The
replaceChild(node, child)
method must return the result of
replacing child
with node within the context object.
The
removeChild(child)
method must return the result of
pre-removing
child from the context object.
This section will define the replacement for the "Mutation Events" feature of the platform. For now it contains the interface being implemented by vendors.
[Constructor(MutationCallback callback)] interface MutationObserver { void observe(Node target, MutationObserverInit options); void disconnect(); }; callback MutationCallback = void (MutationRecord[] mutations, MutationObserver observer); dictionary MutationObserverInit { // Mutation types boolean childList; // If true, mutations affecting node’s childNodes are included. boolean attributes; // If true, mutations affecting element’s attributes are included. boolean characterData; // If true, mutations affecting the value of CharacterData nodes are included. // [Note: If none of the known mutation types is specified, an Error is thrown] // Subtree observation boolean subtree; // If true, the observed set of nodes for this registration should include // descendants of MutationTarget (behavior described below). // Old values boolean attributeOldValue; // If true, MutationRecords describing changes to attributes should // contain the value of the attribute before the change. If true // without attribute: true specified, an Error is thrown. boolean characterDataOldValue; // If true, MutationRecords describing changes to // CharacterData nodes should contain the value // of the node before the change. If true without // characterData: true, an Error is thrown. // Filtering DOMString[] attributeFilter; // If provided, only changes to attributes with localName equaling // one of the provided strings will be delivered. If provided without // attribute: true, an Error is thrown. }; interface MutationRecord { // Mutation type: one of 'childList', 'attributes', or 'characterData' readonly attribute DOMString type; // For childList and attributes, target is the owner node affected. // For CharacterData, target is the node affected. readonly attribute Node target; // For type == 'childList', Sequence of added and removed nodes in this operation. readonly attribute NodeList addedNodes; readonly attribute NodeList removedNodes; // For type == 'childList', The siblings in childNodes immediately preceding following the first // and last nodes added and/or removed. readonly attribute Node previousSibling; readonly attribute Node nextSibling; // For type == 'attribute', the name and namespaceURI of the attribute affected readonly attribute DOMString attributeName; readonly attribute DOMString attributeNamespace; // For type == 'attribute' or 'characterData', if requested, the value immediately // preceding the mutation. readonly attribute DOMString oldValue; };
Node
interface Node : EventTarget { const unsigned short ELEMENT_NODE = 1; const unsigned short ATTRIBUTE_NODE = 2; // historical const unsigned short TEXT_NODE = 3; const unsigned short CDATA_SECTION_NODE = 4; // historical const unsigned short ENTITY_REFERENCE_NODE = 5; // historical const unsigned short ENTITY_NODE = 6; // historical const unsigned short PROCESSING_INSTRUCTION_NODE = 7; const unsigned short COMMENT_NODE = 8; const unsigned short DOCUMENT_NODE = 9; const unsigned short DOCUMENT_TYPE_NODE = 10; const unsigned short DOCUMENT_FRAGMENT_NODE = 11; const unsigned short NOTATION_NODE = 12; // historical readonly attribute unsigned short nodeType; readonly attribute DOMString nodeName; readonly attribute DOMString? baseURI; readonly attribute Document? ownerDocument; readonly attribute Node? parentNode; readonly attribute Element? parentElement; boolean hasChildNodes(); readonly attribute NodeList childNodes; readonly attribute Node? firstChild; readonly attribute Node? lastChild; readonly attribute Node? previousSibling; readonly attribute Node? nextSibling; const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01; const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02; const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04; const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08; const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10; const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20; // historical unsigned short compareDocumentPosition(Node other); boolean contains(Node? other); attribute DOMString? nodeValue; attribute DOMString? textContent; Node insertBefore(Node node, Node? child); Node appendChild(Node node); Node replaceChild(Node node, Node child); Node removeChild(Node child); void normalize(); Node cloneNode(optional boolean deep); boolean isEqualNode(Node? node); DOMString lookupPrefix(DOMString? namespace); DOMString lookupNamespaceURI(DOMString? prefix); boolean isDefaultNamespace(DOMString? namespace); };
Node
is an abstract interface and does not exist
as node. It is used by all
nodes (Document
,
DocumentFragment
, DocumentType
,
Element
, Text
, ProcessingInstruction
,
and Comment
).
Each node has an associated node document, set upon creation, that is a document.
A node's node document can be changed by the "adopt" algorithm.
Each node also has an associated base URL.
Other specifications define the value of the
base URL and its observable
behavior. This specification solely defines the concept and the
baseURI
attribute.
nodeType
Returns the type of node, represented by a number from the following list:
Node
. ELEMENT_NODE
(1)
Node
. TEXT_NODE
(3)
Text
node.
Node
. PROCESSING_INSTRUCTION_NODE
(7)
ProcessingInstruction
node.
Node
. COMMENT_NODE
(8)
Comment
node.
Node
. DOCUMENT_NODE
(9)
Node
. DOCUMENT_TYPE_NODE
(10)
Node
. DOCUMENT_FRAGMENT_NODE
(11)
DocumentFragment
node.
nodeName
Returns a string appropriate for the type of node, as follows:
Element
tagName
attribute value.
Text
#text
".
ProcessingInstruction
Comment
#comment
".
Document
#document
".
DocumentType
DocumentFragment
#document-fragment
".
The nodeType
attribute
must return the type of the node, which must be one of the following:
ELEMENT_NODE
(1);
TEXT_NODE
(3);
PROCESSING_INSTRUCTION_NODE
(7);
COMMENT_NODE
(8);
DOCUMENT_NODE
(9);
DOCUMENT_TYPE_NODE
(10);
DOCUMENT_FRAGMENT_NODE
(11).
The nodeName
attribute
must return the following, depending on the context object:
Element
Its tagName
attribute value.
Text
"#text
".
ProcessingInstruction
Its target.
Comment
"#comment
".
Document
"#document
".
DocumentType
Its name.
DocumentFragment
"#document-fragment
".
baseURI
Returns the base URL.
The baseURI
attribute must return the associated base URL.
ownerDocument
Returns the node document.
Returns null for documents.
parentNode
Returns the parent.
parentElement
Returns the parent element.
hasChildNodes
Returns whether node has children.
childNodes
Returns the children.
firstChild
Returns the first child.
lastChild
Returns the last child.
previousSibling
Returns the previous sibling.
nextSibling
Returns the next sibling.
The ownerDocument
attribute must run these steps:
The node document of a document is that document itself.
The parentNode
attribute must return the parent.
The parentElement
attribute must return the parent element.
The hasChildNodes()
method must return true if the context object has
children, or false otherwise.
The childNodes
attribute must return a NodeList
rooted at the
context object matching only
children.
The firstChild
attribute must return the
first child.
The lastChild
attribute must return the last child.
The
previousSibling
attribute must return the
previous sibling.
The nextSibling
attribute must return the
next sibling.
compareDocumentPosition(other)
Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:
Node
. DOCUMENT_POSITION_DISCONNECTED
(1)
DOCUMENT_POSITION_PRECEDING
(2)
DOCUMENT_POSITION_FOLLOWING
(4)
DOCUMENT_POSITION_CONTAINS
(8)
DOCUMENT_POSITION_CONTAINED_BY
(16, 10 in hexadecimal)
contains(other)
Returns true if other is an inclusive descendant of node, or false otherwise.
These are the constants
compareDocumentPosition()
returns as mask:
DOCUMENT_POSITION_DISCONNECTED
(1);
DOCUMENT_POSITION_PRECEDING
(2);
DOCUMENT_POSITION_FOLLOWING
(4);
DOCUMENT_POSITION_CONTAINS
(8);
DOCUMENT_POSITION_CONTAINED_BY
(16, 10 in hexadecimal).
The compareDocumentPosition(other)
method must run these steps:
Let reference be the context object.
If other and reference are the same object, return zero and terminate these steps.
If other and reference are not
in the same tree, return
DOCUMENT_POSITION_DISCONNECTED
and terminate these steps.
If other is an
ancestor of
reference, return the result of adding
DOCUMENT_POSITION_CONTAINS
to
DOCUMENT_POSITION_PRECEDING
and terminate these steps.
If other is a
descendant of
reference, return the result of adding
DOCUMENT_POSITION_CONTAINED_BY
to
DOCUMENT_POSITION_FOLLOWING
and terminate these steps.
If other is
preceding
reference return
DOCUMENT_POSITION_PRECEDING
and terminate these steps.
Return
DOCUMENT_POSITION_FOLLOWING
.
The
contains(other)
method must return true if other is an
inclusive descendant of
the context object, or false otherwise.
The nodeValue
attribute
must return the following, depending on the context object:
Text
Comment
ProcessingInstruction
The context object's data.
Null.
Setting the nodeValue
attribute
must do as described below, depending on the context object:
Text
Comment
ProcessingInstruction
Replace data with node
context object, offset 0, count
length
attribute value, and
data new value.
Do nothing.
The textContent
attribute must return the following, depending on the
context object:
DocumentFragment
Element
The concatenation of data of all
the Text
node
descendants of the
context object, in
tree order.
Text
ProcessingInstruction
Comment
The context object's data.
Null.
The textContent
attribute must,
on setting, if the new value is null, act as if it was the empty string
instead, and then do as described below, depending on the context object:
DocumentFragment
Element
Let node be null.
If new value is not the empty string, set node to
a new Text
node whose
data is new value.
Replace all with node within the context object.
Text
ProcessingInstruction
Comment
Replace data with node
context object, offset 0, count
length
attribute value, and
data new value.
Do nothing.
normalize()
Concatenates contiguous Text
nodes into a
single Text
node.
The normalize()
method
must run these steps:
For each Text
node
descendant of the
context object:
Let node be the Text
node
descendant.
Let data be the concatenation of the
data of node's
contiguous Text
nodes (excluding itself), in
tree order.
Replace data with node
node, offset node's
length
attribute value,
count 0, and data data.
Remove
node's
contiguous Text
nodes (excluding itself), in
tree order.
cloneNode
([deep])
Returns a copy of node. If deep is true or omitted, the copy also includes the node children.
isEqualNode
(other)
Returns whether node and other have the same properties.
Specifications may define cloning steps for all or some nodes.
To clone a node, optionally with a document ownerDocument and a clone children flag, run these steps:
If document is not given let ownerDocument be node's node document.
Let copy be a node that implements the same interfaces as node.
If copy is a document set its node document to null and set ownerDocument to copy.
Otherwise, set copy's node document to ownerDocument.
Copy the following, depending on the type of node:
Element
Its namespace, namespace prefix, local name, and its attribute list.
DocumentType
ProcessingInstruction
Text
Comment
Its data.
—
Run any cloning steps defined for node in other applicable specifications.
If the clone children flag is set, clone all the children of node and append them to copy, with ownerDocument as specified and the clone children flag being set.
Return copy.
The
cloneNode(deep)
method must return a clone of the
context object, with the clone children flag set
if deep is true or omitted.
The
isEqualNode(node)
method must return true if all of the following conditions are true, and
false otherwise:
node is not null.
node's
nodeType
attribute value is the same
as the context object's
nodeType
attribute value.
The following are also equal, depending on node:
DocumentType
Element
Its namespace, namespace prefix, local name, and its number of attributes in its attribute list.
ProcessingInstruction
Text
Comment
Its data.
—
If node is an Element
, each
attribute in its
attribute list has an
attribute with the same
namespace,
local name, and
value in the
context object's
attribute list.
node has the same number of children as the context object.
Calling isEqualNode()
on
each child of the
context object, with the
child of the same index in
node as argument returns true for every
child.
To locate a namespace prefix for an element using namespace run these steps:
If element's namespace is namespace and its namespace prefix is not null return its namespace prefix and terminate these steps.
If, element
has an
attribute whose
namespace prefix is
"xmlns
" and value
is namespace, then return that
attribute's
local name and terminate these
steps.
If element's parent element is not null, return the result of running locate a namespace prefix on that element using namespace. Otherwise, return null.
To locate a namespace for a node using prefix depends on the node:
Element
If its namespace is not null and its namespace prefix is prefix return namespace and terminate these steps.
If it has an
attribute whose
namespace prefix
is "xmlns
" and
local name is
prefix, or whose
namespace prefix is
null and local name is
"xmlns
":
Let value be its value if it is not the empty string, or null otherwise.
Return value and terminate these steps.
If its parent element is null, return null and terminate these steps.
Return the result of running locate a namespace on its parent element using prefix.
Document
If its document element is null, return null and terminate these steps.
Return the result of running locate a namespace on its document element using prefix.
DocumentType
DocumentFragment
Return null.
If its parent element is null, return null and terminate these steps.
Return the result of running locate a namespace on its parent element using prefix.
The
lookupPrefix(namespace)
method must run these steps:
If namespace is null or the empty string, return null.
Otherwise it depends on the context object:
Element
Return the result of locating a namespace prefix for the node using namespace.
Document
Return the result of locating a namespace prefix for its document element, if that is not null, or null otherwise.
DocumentType
DocumentFragment
Return null.
Return the result of locating a namespace prefix for its parent element, or if that is null, null.
The
lookupNamespaceURI(prefix)
method must run these steps:
If prefix is the empty string, set it to null.
Return the result of running locate a namespace for the context object using prefix.
The
isDefaultNamespace(namespace)
method must run these steps:
If namespace is the empty string, set it to null.
Let defaultNamespace be the result of running locate a namespace for the context object using null.
Return true if defaultNamespace is the same as namespace, or false otherwise.
The
list of elements with local name localName
for a node root is the
NodeList
returned by the following algorithm:
If localName is "*
" (U+002A),
return a NodeList
rooted at root,
whose filter matches only elements.
Otherwise, if root's
node document is an
HTML document, return a NodeList
rooted at
root, whose filter matches only the following nodes:
Otherwise, return a NodeList
rooted at
root, whose filter matches only
elements whose
local name is
localName.
When invoked with the same argument, the same NodeList
object may be returned as returned by an earlier call.
The
list of elements with namespace namespace and local name localName
for a node root is the
NodeList
returned by the following algorithm:
If namespace is the empty string, set it to null.
If both namespace and localName
are "*
" (U+002A) return a NodeList
rooted at
root, whose filter matches only
elements.
Otherwise, if just namespace is "*
"
(U+002A), return a NodeList
rooted at
root, whose filter matches only
elements whose
local name is
localName.
Otherwise, if just localName is "*
"
(U+002A), return a NodeList
rooted at
root, whose filter matches only
elements whose
namespace is
namespace.
Otherwise, return a NodeList
rooted at
root, whose filter matches only
elements whose
namespace is
namespace and
local name is
localName.
When invoked with the same arguments, the same NodeList
object may be returned as returned by an earlier call.
The
list of elements with class names classNames
for a node root is the
NodeList
returned by the following algorithm:
Let classes be the set of tokens found by splitting classNames on spaces. (Duplicates are ignored.)
If classes is the empty set, return an empty
NodeList
and terminate these steps.
Return a NodeList
rooted at root,
whose filter matches only
elements that have all the
classes in classes.
If root's node document is in quirks mode, then the comparisons for the classes must be done in an ASCII case-insensitive manner, otherwise, the comparisons must be done in a case-sensitive manner.
When invoked with the same argument, the same NodeList
object may be returned as returned by an earlier call.
Document
interface Document : Node { readonly attribute DOMImplementation implementation; readonly attribute DOMString URL; readonly attribute DOMString documentURI; readonly attribute DOMString compatMode; readonly attribute DOMString characterSet; readonly attribute DOMString contentType; readonly attribute DocumentType? doctype; readonly attribute Element? documentElement; NodeList getElementsByTagName(DOMString qualifiedName); NodeList getElementsByTagNameNS(DOMString? namespace, DOMString localName); NodeList getElementsByClassName(DOMString classNames); Element? getElementById(DOMString elementId); Element createElement(DOMString localName); Element createElementNS(DOMString? namespace, DOMString qualifiedName); DocumentFragment createDocumentFragment(); Text createTextNode(DOMString data); Comment createComment(DOMString data); ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data); Node importNode(Node node, optional boolean deep); Node adoptNode(Node node); Event createEvent(DOMString eventInterfaceName); Range createRange(); NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow, optional NodeFilter? filter); TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow, optional NodeFilter? filter); // NEW void prepend((Node or DOMString)... nodes); void append((Node or DOMString)... nodes); }; interface XMLDocument : Document {};
Document
nodes are simply
known as documents.
Each document has an associated encoding, content type, and URL.
Unless explicitly given when a
document is created its
encoding is
utf-8
, its
content type is
"application/xml
", and its
URL is
"about:blank
".
A document is assumed to be an XML document unless it is flagged as being an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.
A document is always set to one of three modes: no-quirks mode, the default; quirks mode, used typically for legacy documents; and limited-quirks mode, also known as "almost standards" mode. Unless other applicable specifications define otherwise, a document must be in no-quirks mode.
The mode is only ever changed from the default if the document is created by the HTML parser, based on the presence, absence, or value of the DOCTYPE string. [HTML]
implementation
Returns the associated DOMImplementation
object.
URL
documentURI
Returns the URL.
compatMode
Returns the string "CSS1Compat
" if
document is in
no-quirks mode or
limited-quirks mode, and
"BackCompat
", if document is in
quirks mode.
characterSet
Returns the encoding.
contentType
Returns the content type.
The
implementation
attribute must return the DOMImplementation
object that is
associated with the document.
The URL
and
documentURI
attributes must return the URL.
The compatMode
IDL
attribute must return the literal string "CSS1Compat
"
unless the context object is in
quirks mode, in which case it must
instead return the literal string "BackCompat
".
The characterSet
attribute must return the preferred MIME name of the
encoding.
The contentType
attribute must return the
content type.
doctype
Returns the doctype or null if there is none.
documentElement
Returns the document element.
getElementsByTagName(localName)
If localName is "*
" returns a
NodeList
of all
descendant
elements.
Otherwise, returns a NodeList
of all
descendant
elements whose
local name is
localName. (Matches case-insensitively against
elements in the
HTML namespace within an HTML document.)
getElementsByTagNameNS(namespace, localName)
If namespace and localName are
"*
" returns a NodeList
of all
descendant
elements.
If only namespace is "*
" returns a
NodeList
of all
descendant
elements whose
local name is
localName.
If only localName is "*
" returns a
NodeList
of all
descendant
elements whose
namespace is
namespace.
Otherwise, returns a NodeList
of all
descendant
elements whose
namespace is
namespace and
local name is
localName.
getElementsByClassName(classes)
getElementsByClassName(classes)
Returns a NodeList
of the
elements in the object on which
the method was invoked (a document or
an element) that have all the classes
given by classes.
The classes argument is interpreted as a space-separated list of classes.
getElementById(elementId)
The doctype
attribute
must return the child of the
document that is a
doctype, or null otherwise.
The
documentElement
attribute must return the document element.
The
getElementsByTagName(localName)
method must return the
list of elements with local name localName
for the context object.
Thus, in an HTML document,
document.getElementsByTagName("FOO")
will match
FOO
elements that are not in the
HTML namespace, and foo
elements that are in
the HTML namespace, but not FOO
elements
that are in the HTML namespace.
The
getElementsByTagNameNS(namespace, localName)
method must return the
list of elements with namespace namespace and local name localName
for the context object.
The
getElementsByClassName(classNames)
method must return the
list of elements with class names classNames
for the context object.
Given the following XHTML fragment:
<div id="example"> <p id="p1" class="aaa bbb"/> <p id="p2" class="aaa ccc"/> <p id="p3" class="bbb ccc"/> </div>
A call to
document.getElementById('example').getElementsByClassName('aaa')
would return a NodeList
with the two paragraphs
p1
and p2
in it.
A call to
getElementsByClassName('ccc bbb')
would only return one node, however, namely p3
. A call to
document.getElementById('example').getElementsByClassName('bbb ccc ')
would return the same thing.
A call to
getElementsByClassName('aaa,bbb')
would return no nodes; none of the elements above are in the
aaa,bbb
class.
The
getElementById(elementId)
method must return the first element, in
tree order, within the
context object's tree, whose
ID is elementId, or null if
there is none.
createElement(localName)
Returns an element in the HTML namespace with localName as local name. (In an HTML document localName is lowercased.)
If localName does not match the
Name
production an
"InvalidCharacterError
"
exception will be thrown.
createElementNS(namespace, qualifiedName)
Returns an element with
namespace
namespace. Its
namespace prefix will
be everything before ":
" (U+003E) in
qualifiedName or null. Its
local name will be
everything after ":
" (U+003E) in
qualifiedName or qualifiedName.
If localName does not match the
Name
production an
"InvalidCharacterError
"
exception will be thrown.
If one of the following conditions is true a
"NamespaceError
" exception
will be thrown:
QName
production.
xml
" and namespace is not the
XML namespace.
xmlns
" and namespace is not the
XMLNS namespace.
xmlns
".
createDocumentFragment()
Returns a DocumentFragment
node.
createTextNode(data)
createComment(data)
createProcessingInstruction(target, data)
Returns a ProcessingInstruction
node whose
target is target and
data is data.
If target does not match the
Name
production an
"InvalidCharacterError
"
exception will be thrown.
If data contains "?>
" an
"InvalidCharacterError
"
exception will be thrown.
The createElement(localName)
method must run the these steps:
If localName does not match the
Name
production,
throw an
"InvalidCharacterError
" exception and terminate these
steps.
If the context object is an HTML document, let localName be converted to ASCII lowercase.
Return a new element with no attributes, namespace set to the HTML namespace, local name set to localName, and node document set to the context object.
The
createElementNS(namespace, qualifiedName)
method must run these steps:
If namespace is the empty string, set it to null.
If qualifiedName does not match the
Name
production,
throw an
"InvalidCharacterError
" exception and terminate these
steps.
If qualifiedName does not match the
QName
production,
throw a
"NamespaceError
" exception and terminate these steps.
If qualifiedName contains a ":
"
(U+003E), then split the string on it and let prefix be
the part before and localName the part after. Otherwise,
let prefix be null and localName be
qualifiedName.
If prefix is not null and
namespace is null, throw
a "NamespaceError
" exception and terminate these steps.
If prefix is "xml
" and
namespace is not the XML namespace,
throw a
"NamespaceError
" exception and terminate these steps.
If qualifiedName or prefix is
"xmlns
" and namespace is not the
XMLNS namespace, throw a
"NamespaceError
" exception and terminate these steps.
If namespace is the XMLNS namespace
and neither qualifiedName nor prefix is
"xmlns
", throw a
"NamespaceError
" exception and terminate these steps.
Return a new element with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, and node document set to the context object.
The
createDocumentFragment()
method must return a new DocumentFragment
node with its
node document set to the
context object.
The
createTextNode(data)
method must return a new Text
node with its
data set to data and
node document set to the
context object.
No check is performed that data consists of
characters that match the Char
production.
The
createComment(data)
method must return a new Comment
node with its
data set to data and
node document set to the
context object.
No check is performed that data consists of
characters that match the Char
production
or that it contains two adjacent hyphens or ends with a hyphen.
The createProcessingInstruction(target, data)
method must run these steps:
If target does not match the
Name
production,
throw an
"InvalidCharacterError
" exception and terminate these
steps.
If data contains the string
"?>
", throw an
"InvalidCharacterError
" exception and terminate these
steps.
Return a new ProcessingInstruction
node, with
target set to target,
data set to data, and
node document set to the
context object.
No check is performed that target contains
"xml
" or ":
", or that
data contains characters that match the
Char
production.
importNode(node [, deep])
Returns a copy of node. If deep is true or omitted, the copy also includes the node children.
If node is a
document throws a
"NotSupportedError
"
exception.
adoptNode(node)
Moves node from another document and returns it.
If node is a
document throws a
"NotSupportedError
"
exception.
The
importNode(node, deep)
method must run these steps:
If node is a
document,
throw a
"NotSupportedError
" exception and terminate these steps.
Return a clone of node, with document context object and the clone children flag set if deep is true or omitted.
To adopt a node, with an ownerDocument, run these steps:
If node is an element, it is affected by a base URL change.
Set node document for node and all its descendants to ownerDocument.
The
adoptNode(node)
method must run these steps:
If node is a
document,
throw a
"NotSupportedError
" exception and terminate these steps.
Adopt node with the context object and return it.
createEvent(eventInterfaceName)
Returns an event using an interface for which the interface name is a case-insensitive match for eventInterfaceName.
When the createEvent(eventInterfaceName)
methed is invoked these steps must be run:
If eventInterfaceName is an ASCII case-insensitive match for any of the strings in the first column in the following table, let eventInterfaceName be the string in the second column on the same row as the matching string:
Input interface | Replacement interface |
---|---|
"htmlevents " | "event "
|
"mouseevents " | "mouseevent "
|
"mutationevents " | "mutationevent "
|
"uievents " | "uievent "
|
If eventInterfaceName is not an
ASCII case-insensitive match for "event
" or
for the name of an interface that inherits from the Event
interface and is supported by the user agent,
throw a
"NotSupportedError
" and terminate these steps.
Create an event implementing the interface whose name eventInterfaceName is an ASCII case-insensitive match for and return it.
This method is pretty much obsolete as events have constructors these days, but needs to be supported for legacy content. Tough.
createRange()
Returns a new range.
The createRange()
method must return a new range with
(context object, 0) as its
start and
end.
When the
createNodeIterator(root, whatToShow, filter)
method is invoked these steps must be run:
Create a NodeIterator
object.
Set root and initialize
the referenceNode
attribute to the root argument.
Set whatToShow to
the whatToShow argument, or to
SHOW_ALL
if omitted.
Set filter to filter, or to null if omitted.
Return the newly created NodeIterator
object.
When the
createTreeWalker(root, whatToShow, filter)
method is invoked these steps must be run:
Create a TreeWalker
object.
Set root and initialize
the currentNode
attribute to
the root argument.
Set whatToShow to
the whatToShow argument, or to
SHOW_ALL
if omitted.
Set filter to filter, or to null if omitted.
Return the newly created TreeWalker
object.
DOMImplementation
User agents must create a DOMImplementation
object whenever
a document is created and associate it
with that document.
interface DOMImplementation { boolean hasFeature(DOMString feature, [TreatNullAs=EmptyString] DOMString version); DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId); XMLDocument createDocument(DOMString? namespace, DOMString qualifiedName, DocumentType? doctype); Document createHTMLDocument(DOMString title); };
implementation
. hasFeature
(
feature, version )
Returns whether the user agent supports the version version of feature. The empty string means any version.
The hasFeature(feature, version)
method must return
true if the user agent supports
the (feature, version) tuple and false
otherwise.
implementation
. createDocumentType
(
qualifiedName, publicId, systemId )
Returns a doctype, with the given
qualifiedName, publicId, and
systemId. If qualifiedName does not
match the Name
production, an
"InvalidCharacterError
"
exception is thrown, and if it does not match the
QName
production, a
"NamespaceError
" exception
is thrown.
implementation
. createDocument
( namespace, qualifiedName, doctype )
Returns an XMLDocument
, with a
document element whose
local name is
qualifiedName and whose
namespace is
namespace (unless qualifiedName is the
empty string), and with doctype, if it is given, as its
doctype.
This method throws the same exceptions as the createElementNS
method, when
invoked with the same arguments.
implementation
. createHTMLDocument
(
title )
Returns a document, with a basic
tree already constructed including a
title
element.
The
createDocumentType(qualifiedName, publicId, systemId)
method must run these steps:
If qualifiedName does not match the
Name
production,
throw an
"InvalidCharacterError
" exception and terminate these
steps.
If qualifiedName does not match the QName
production in,
throw a
"NamespaceError
" exception and terminate these steps.
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 the publicId
matches the PublicChar
or that the
systemId does not contain both a '"
' and
"'
".
The
createDocument(namespace, qualifiedName, doctype)
method must run these steps:
Let document be a new XMLDocument
.
This method creates an XMLDocument
rather than
a normal document. They are identical
except for the addition of the
load()
method deployed content relies upon.
[HTML]
Let element be null.
If qualifiedName is not the empty string, set
element to the result of invoking the
createElementNS()
method
with the arguments namespace and
qualifiedName on document. If that threw
an exception, re-throw the exception and terminate these steps.
If doctype is not null, append doctype to document.
If element is not null, append element to document.
Return document.
The
createHTMLDocument(title)
method must run these steps:
Let doc be a newly created document.
Mark doc as being an HTML document.
Set doc's
content type to
"text/html
".
Create a doctype, with
"html
"
as its name and with its
node document set to
doc. Append
the newly created node to doc.
Create an html
element in the HTML
namespace, and append
it to doc.
Create a head
element in the HTML
namespace, and append
it to the html
element created in the previous step.
Create a title
element in the HTML
namespace, and append
it to the head
element created in the previous step.
Create a Text
node, set
its data to title
(which could be the empty string), and
append it to the
title
element created in the previous step.
Create a body
element in the
HTML namespace, and
append it to the
html
element created in the earlier step.
Return doc.
DocumentFragment
interface DocumentFragment : Node { // NEW void prepend((Node or DOMString)... nodes); void append((Node or DOMString)... nodes); };
DocumentType
interface DocumentType : Node { readonly attribute DOMString name; readonly attribute DOMString publicId; readonly attribute DOMString systemId; // NEW void before((Node or DOMString)... nodes); void after((Node or DOMString)... nodes); void replace((Node or DOMString)... nodes); void remove(); };
DocumentType
nodes are
simply known as doctypes.
Doctypes have an associated name, public ID, and system ID.
When a doctype is created, its name is always given. Unless explicitly given when a doctype is created, its public ID and system ID are the empty string.
The name
attribute
must return the name.
The publicId
attribute must return the
public ID.
The systemId
attribute must return the
system ID.
Element
interface Element : Node { readonly attribute DOMString? namespaceURI; readonly attribute DOMString? prefix; readonly attribute DOMString localName; readonly attribute DOMString tagName; attribute DOMString id; attribute DOMString className; readonly attribute DOMTokenList classList; readonly attribute Attr[] attributes; DOMString? getAttribute(DOMString name); DOMString? getAttributeNS(DOMString? namespace, DOMString localName); void setAttribute(DOMString name, DOMString value); void setAttributeNS(DOMString? namespace, DOMString name, DOMString value); void removeAttribute(DOMString name); void removeAttributeNS(DOMString? namespace, DOMString localName); boolean hasAttribute(DOMString name); boolean hasAttributeNS(DOMString? namespace, DOMString localName); NodeList getElementsByTagName(DOMString qualifiedName); NodeList getElementsByTagNameNS(DOMString? namespace, DOMString localName); NodeList getElementsByClassName(DOMString classNames); readonly attribute HTMLCollection children; readonly attribute Element? firstElementChild; readonly attribute Element? lastElementChild; readonly attribute Element? previousElementSibling; readonly attribute Element? nextElementSibling; readonly attribute unsigned long childElementCount; // NEW void prepend((Node or DOMString)... nodes); void append((Node or DOMString)... nodes); void before((Node or DOMString)... nodes); void after((Node or DOMString)... nodes); void replace((Node or DOMString)... nodes); void remove(); };
Element
nodes are simply
known as elements.
Elements have an associated namespace, namespace prefix, and local name. When an element is created, its local name is always given. Unless explicitly given when an element is created, its namespace and namespace prefix are null.
Elements also have an ordered attribute list. Unless explicitly given when an element is created, its attribute list is empty. An element has an attribute A if A is in its attribute list.
Elements can have a unique identifier (ID) and classes associated with them.
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.
An element has an
ID if it
has an
id
attribute whose
value is not the empty string.
The ID is that
attribute's
value.
An element has
classes if it
has a
class
attribute, and
splitting that
attribute's
value does not return an empty
list. The classes are that
attribute's
value
split on spaces.
While this specification defines user agent processing
requirements for id
and class
attributes on any
element, it makes no claims as to whether
using them is conforming or not.
A node's
parent of type
Element
is known as a parent element. If the
node has a
parent of a different type, its
parent element is null.
The document element of a document is the element whose parent is that document, if it exists, and null otherwise.
As explained in the node tree section, there can only be one such element.
When an element or one of its ancestors is the document element, it is in a document.
Specifications may define base URL change steps.
When an element is affected by a base URL change, the user agent must run the base URL change steps, as defined in other applicable specifications.
namespaceURI
Returns the namespace.
prefix
Returns the namespace prefix.
localName
Returns the local name.
tagName
If
namespace prefix is not
null returns the concatenation of
namespace prefix,
":
", and
local name. Otherwise it
returns the local name.
(The return value is uppercased in an HTML document.)
The namespaceURI
attribute must return the context object's
namespace.
The prefix
attribute must return the context object's
namespace prefix.
The localName
attribute must return the context object's
local name.
The tagName
attribute
must run these steps:
If context object's
namespace prefix is not
null, let qualified name be its
namespace prefix, followed
by a ":
" (U+003A), followed by its
local name. Otherwise, let
qualified name be its
local name.
If the context object is in the HTML namespace and its node document is an HTML document, let qualified name be converted to ASCII uppercase.
Return qualified name.
Some IDL attributes are defined to reflect a particular content attribute. This means that on getting, the following steps must be run:
getAttribute()
with the name
of the content attribute as its argument.
On setting, the user agent must invoke
setAttribute()
with the name of
the content attribute and the new value as its arguments.
The id
attribute must
reflect the "id
"
content attribute.
The className
attribute must reflect the
"class
" content attribute.
The classList
attribute must return a DOMTokenList
whose
underlying string is
the className
attribute value.
The attributes
attribute must return a read only array
of the context object's
attribute list.
The returned read only array must be
live. I.e. changes to the associated
attributes are reflected.
The getAttribute(name)
method must run these steps:
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
Return the value of the first attribute in the context object's attribute list whose name is name, or null otherwise.
The
getAttributeNS(namespace, localName)
method must return the following steps:
If namespace is the empty string, set it to null.
Return the value of the attribute in the context object's attribute list whose namespace is namespace and local name is localName, if it has one, or null otherwise.
The
setAttribute(name, value)
method must run these steps:
If name does not match the
Name
production in XML,
throw an
"InvalidCharacterError
" exception and terminate these
steps.
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
If "xmlns
" is a prefix match for
name, throw a
"NamespaceError
" and terminate these steps.
If the context object does not have an attribute whose name is name, create an attribute, whose name is name and value is value, and then append this attribute to the context object.
Otherwise, change the first attribute in the context object's attribute list whose name is name, to value.
The
setAttributeNS(namespace, name, value)
method must run these steps:
If namespace is the empty string, set it to null.
If name does not match the
Name
production in XML,
throw an
"InvalidCharacterError
" exception and terminate these
steps.
If name does not match the
QName
production in Namespaces in XML,
throw a
"NamespaceError
" exception and terminate these steps.
If name contains a ":
" (U+003E),
then split the string on it and let prefix be the part
before and localName the part after. Otherwise, let
prefix be null and localName be
name.
If prefix is not null and
namespace is null, throw
a "NamespaceError
" exception and terminate these steps.
If prefix is "xml
" and
namespace is not the XML namespace,
throw a
"NamespaceError
" exception and terminate these steps.
If name or prefix is
"xmlns
" and namespace is not the
XMLNS namespace, throw a
"NamespaceError
" exception and terminate these steps.
If namespace is the XMLNS namespace
and neither name nor prefix is
"xmlns
", throw a
"NamespaceError
" exception and terminate these steps.
If the context object does not have an attribute whose namespace is namespace and local name is localName, create an attribute, whose name is name, namespace is namespace, namespace prefix is prefix, local name is localName, and value is value, and then append this attribute to the context object.
The
removeAttribute(name)
method must run these steps:
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
Remove the first attribute from the context object whose name is name, if any.
The
removeAttributeNS(namespace, localName)
method must return the following steps:
If namespace is the empty string, set it to null.
Remove the attribute from the context object whose namespace is namespace and local name is localName, if any.
The
hasAttribute(name)
method must run these steps:
If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.
Return true if the context object has an attribute whose name is name, or false otherwise.
The
hasAttributeNS(namespace, localName)
method must return the following steps:
If namespace is the empty string, set it to null.
Return true if the context object has an attribute whose namespace is namespace and local name is localName, or false otherwise.
When the
getElementsByTagName(qualifiedName)
method must return the
list of elements with local name localName
for the context object.
When the
getElementsByTagNameNS(namespace, localName)
method must return the
list of elements with namespace namespace and local name localName
for the context object.
When the
getElementsByClassName(classNames)
method must return the
list of elements with class names classNames
for the context object.
children
firstElementChild
Returns the first child that is an element, or null otherwise.
lastElementChild
Returns the last child that is an element, or null otherwise.
previousElementSibling
Returns the first preceding sibling that is an element, or null otherwise.
nextElementSibling
Returns the first following sibling that is an element, or null otherwise.
The children
attribute
must return an HTMLCollection
collection rooted at the
context object matching only
element
children.
The
firstElementChild
attribute must return the first child
that is an element, or null otherwise.
The
lastElementChild
attribute must return the last child
that is an element, or null otherwise.
The
previousElementSibling
attribute must return the first
preceding
sibling that is an
element, or null otherwise.
The
nextElementSibling
attribute must return the first
following
sibling that is an
element, or null otherwise.
The
childElementCount
attribute must return the number of
children of the
context object that are
elements.
Attr
interface Attr { readonly attribute DOMString name; attribute DOMString value; readonly attribute DOMString? namespaceURI; readonly attribute DOMString? prefix; readonly attribute DOMString localName; };
Attr
objects are simply known as
attributes.
Attributes have a name and value.
For legacy reasons, attributes also have an associated namespace, namespace prefix, and local name.
When an attribute is created, its name and value are always given. Unless explicitly given when an attribute is created, its local name is identical to its name, and its namespace and namespace prefix are null.
An
A
attribute
is an attribute whose
name is
A
and whose
namespace and
namespace prefix are
null.
To change an attribute attribute to value, set the attribute's value to value.
To append an attribute attribute to an element element, append the attribute to the element's attribute list.
To remove an attribute attribute from an element element, remove the attribute from the element's attribute list.
These definitions will be expanded upon in due course for mutations.
The name
attribute must
return the name.
The value
attribute must
return the value.
Setting the value
attribute must set
value to the new value.
The namespaceURI
attribute must return the
namespace.
The prefix
attribute must
return the
namespace prefix.
The localName
attribute
must return the local name.
CharacterData
interface CharacterData : Node { [TreatNullAs=EmptyString] attribute DOMString data; readonly attribute unsigned long length; DOMString substringData(unsigned long offset, unsigned long count); void appendData(DOMString data); void insertData(unsigned long offset, DOMString data); void deleteData(unsigned long offset, unsigned long count); void replaceData(unsigned long offset, unsigned long count, DOMString data); // NEW void before((Node or DOMString)... nodes); void after((Node or DOMString)... nodes); void replace((Node or DOMString)... nodes); void remove(); };
CharacterData
is an abstract interface and does
not exist as node. It is used by
Text
, Comment
, and
ProcessingInstruction
nodes.
Each node inheriting from the
CharacterData
interface has an associated mutable string
called data.
To replace data of node node with offset offset, count count, and data data, run these steps:
Let length be the node's
length
attribute value.
If offset is greater than length,
throw an
"IndexSizeError
" exception and terminate these steps.
If offset plus count is greater than length let count be length minus offset.
Insert data into node's data after offset code units.
Let delete offset be offset plus the number of code units in data.
Starting from delete offset code units, remove count code units from node's data.
For each range whose start node is node and start offset is greater than offset but less than or equal to offset plus count, set its start offset to offset.
For each range whose end node is node and end offset is greater than offset but less than or equal to offset plus count, set its end offset to offset.
For each range whose start node is node and start offset is greater than offset plus count, increase its start offset by the number of code units in data, then decrease it by count.
For each range whose end node is node and end offset is greater than offset plus count, increase its end offset by the number of code units in data, then decrease it by count.
To substring data with node node, offset offset, and count count, run these steps:
Let length be node's
length
attribute value.
If offset is greater than length,
throw an
"IndexSizeError
" exception and terminate these steps.
If offset plus count is greater than length, return a string whose value is the code units from the offsetth code unit to the end of node's data, and then terminate these steps.
Return a string whose value is the code units from the offsetth code unit to the offset+countth code unit in node's data.
The data
attribute
must return data, and on setting, must
replace data with node
context object offset 0, count
length
attribute value, and data
new value.
The length
attribute must return the number of
code units in
data.
The
substringData(offset, count)
method must substring data with node
context object, offset offset, and count
count.
The
appendData(data)
method must replace data with node
context object, offset
length
attribute value, count 0,
and data data.
The
insertData(offset, data)
method must replace data with node
context object, offset offset, count 0, and
data data.
The
deleteData(offset, count)
method must replace data with node
context object, offset offset, count
count, and data the empty string.
The
replaceData(offset, count, data)
method must replace data with node
context object, offset offset, count
count, and data data.
Text
interface Text : CharacterData { Text splitText(unsigned long offset); readonly attribute DOMString wholeText; };
To split a Text
node node with offset
offset, run these steps:
Let length be the
length
attribute value.
If offset is greater than length,
throw an
"IndexSizeError
" exception and terminate these steps.
Let count be length minus offset.
Let new data be the result of substringing data with node node, offset offset, and count count.
Let new node be a new Text
node, with the same
node document as
node. Set new node's
data to new data.
Let parent be the node's parent.
If parent is not null, run these substeps:
Insert new node into parent before node's next sibling.
For each range whose start node is node and start offset is greater than offset, set its start node to new node and decrease its start offset by offset.
For each range whose end node is node and end offset is greater than offset, set its end node to new node and decrease its end offset by offset.
Replace data with node node, offset offset, count count, and data the empty string.
If parent is null, run these substeps:
For each range whose start node is node and start offset is greater than offset, set its start offset to offset.
For each range whose end node is node and end offset is greater than offset, set its end offset to offset.
Return new node.
The
splitText(offset)
method must split the
context object with offset offset.
The contiguous Text
nodes of a node are the node
itself, the
previous sibling
Text
node (if any) and its
contiguous Text
nodes, and the
next sibling Text
node (if any) and its contiguous Text
nodes,
avoiding any duplicates.
The wholeText
attribute must return a concatenation of the
data of the
contiguous Text
nodes of the
context object, in
tree order.
ProcessingInstruction
interface ProcessingInstruction : CharacterData { readonly attribute DOMString target; };
ProcessingInstruction
nodes
have an associated target.
The target
attribute must return the target.
Comment
interface Comment : CharacterData { };
The length of a node node depends on node:
DocumentType
0.
Text
ProcessingInstruction
Comment
Its length
attribute
value.
Its number of children.
Range
interface Range { readonly attribute Node startContainer; readonly attribute unsigned long startOffset; readonly attribute Node endContainer; readonly attribute unsigned long endOffset; readonly attribute boolean collapsed; readonly attribute Node commonAncestorContainer; void setStart(Node refNode, unsigned long offset); void setEnd(Node refNode, unsigned long offset); void setStartBefore(Node refNode); void setStartAfter(Node refNode); void setEndBefore(Node refNode); void setEndAfter(Node refNode); void collapse(boolean toStart); void selectNode(Node refNode); void selectNodeContents(Node refNode); const unsigned short START_TO_START = 0; const unsigned short START_TO_END = 1; const unsigned short END_TO_END = 2; const unsigned short END_TO_START = 3; short compareBoundaryPoints(unsigned short how, Range sourceRange); void deleteContents(); DocumentFragment extractContents(); DocumentFragment cloneContents(); void insertNode(Node node); void surroundContents(Node newParent); Range cloneRange(); void detach(); boolean isPointInRange(Node node, unsigned long offset); short comparePoint(Node node, unsigned long offset); boolean intersectsNode(Node node); stringifier; };
Range
objects are simply known as
ranges.
Ranges can be created using
the createRange()
method.
A boundary point is a (node, offset) tuple, where offset is a non-negative integer.
Generally speaking, a boundary point's offset will be between zero and the boundary point's node length, inclusive. Algorithms that modify a tree (in particular the insert, remove, replace data, and split algorithms) also modify ranges associated with that tree.
If the two nodes of boundary points (node A, offset A) and (node B, offset B) have the same root, the position of the first relative to the second is either before, equal, or after, as returned by the following algorithm:
If node A is the same as node B, return equal if offset A is the same as offset B, before if offset A is less than offset B, and after if offset A is greater than offset B.
If node A is following node B, compute the position of (node B, offset B) relative to (node A, offset A). If it is before, return after. If it is after, return before. In either case terminate these steps.
If node A is an ancestor of node B:
Return before.
Each range has two associated boundary points — a start and end — an associated detached flag, which is initially unset.
For convenience, start node is start's node, start offset is start's offset, end node is end's node, and end offset is end's offset.
The root of a range is the root of its start node, or null if its detached flag is set.
A node node is contained in a range range if node's root is the same as range's root, and (node, 0) is after range's start, and (node, length of node) is before range's end.
A node is partially contained in a range if it is an inclusive ancestor of the range's start node but not its end node, or vice versa.
Some facts to better understand these definitions:
The content that one would think of as being within the
range consists of all
contained nodes, plus
possibly some of the contents of the
start node and
end node if those are
Text
or Comment
nodes.
The nodes that are contained in a range will generally not be contiguous, because the parent of a contained node will not always be contained.
However, the descendants of a contained node are contained, and if two siblings are contained, so are any siblings that lie between them.
The first contained node (if there are any) will always be after the start node, and the last contained node will always be equal to or before the end node's last descendant.
The start node and end node of a range are never contained within it.
There exists some partially contained node if and only if the start node and end node are different.
The
commonAncestorContainer
attribute value is never contained or
partially contained.
If the start node is not an inclusive ancestor of the end node, nor vice versa, the common inclusive ancestor will be distinct from both of them. Exactly two of its children will be partially contained, and a child will be contained if and only if it lies between those two.
startContainer
Returns range's start node.
startOffset
Returns range's start offset.
endContainer
Returns range's end node.
endOffset
Returns range's end offset.
collapsed
Returns true if range's start and end are the same, or false otherwise.
commonAncestorContainer
Returns the node, furthest away from the document, that is an ancestor of both range's start node and end node.
The startContainer
attribute must throw an
"InvalidStateError
" exception if the
detached flag is set, or return
the start node otherwise.
The startOffset
attribute must throw an
"InvalidStateError
" exception if the
detached flag is set, or return
the start offset otherwise.
The endContainer
attribute must throw an
"InvalidStateError
" exception if the
detached flag is set, or return
the end node otherwise.
The endOffset
attribute must throw an
"InvalidStateError
" exception if the
detached flag is set, or return
the end offset otherwise.
The collapsed
attribute
must throw an
"InvalidStateError
" exception if the
detached flag is set, return true
if start is the same as
end, or return false otherwise.
The
commonAncestorContainer
attribute must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let container be start node.
While container is not an inclusive ancestor of end node, let container be container's parent.
Return container.
To set the start or end of a range to a boundary point (node, offset), run these steps:
If range's
detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If node is a
doctype,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
If offset is greater than
node's length,
throw an
"IndexSizeError
" exception and terminate these steps.
Let bp be the boundary point (node, offset).
The
setStart(node, offset)
method must set the start of the
context object to
boundary point
(node, offset).
The
setEnd(refNode, offset)
method must set the end of the
context object to
boundary point
(node, offset).
The
setStartBefore(node)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
Set the start of the context object to boundary point (parent, node's index).
The
setStartAfter(node)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
Set the start of the context object to boundary point (parent, node's index plus one).
The
setEndBefore(node)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
Set the end of the context object to boundary point (parent, node's index).
The
setEndAfter(node)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let parent be node's parent.
If parent is null,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
Set the end of the context object to boundary point (parent, node's index plus one).
The
collapse(toStart)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If toStart is true, set end to start. Otherwise, set start to end.
The
selectNode(refNode)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let parent be refNode's parent.
If parent is null,
throw an
"InvalidNodeTypeError
" and terminate these steps.
Let index be the index of refNode.
Set start to the boundary point (parent, index).
Set end to the boundary point (parent, index plus one).
The
selectNodeContents(refNode)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If refNode is a
doctype,
throw an
"InvalidNodeTypeError
" and terminate these steps.
Let length be the length of refNode.
Set start to the boundary point (refNode, 0).
Set end to the boundary point (refNode, length).
The
compareBoundaryPoints(how, sourceRange)
method must run these steps:
If context object's or sourceRange's
detached flag is set,
throw an
"InvalidStateError
" exception and terminate these steps.
If how is not one of
throw a
"NotSupportedError
" exception and terminate these steps.
If context object's
root is not the same as
sourceRange's root,
throw a
"WrongDocumentError
" exception and terminate these
steps.
If how is:
START_TO_START
:
Let this point be the context object's start.
Let other point be sourceRange's start.
START_TO_END
:
Let this point be the context object's end.
Let other point be sourceRange's start.
END_TO_END
:
Let this point be the context object's end.
Let other point be sourceRange's end.
END_TO_START
:
Let this point be the context object's start.
Let other point be sourceRange's end.
If the position of this point relative to other point is
The deleteContents()
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.
If original start node and
original end node are the same, and they are a
Text
or Comment
node,
replace data with node
original start node, offset
original start offset, count
original end offset minus
original start offset, and data the empty string, and then
terminate these steps.
Let nodes to remove be a list of all the nodes that are contained in the context object, in tree order, omitting any node whose parent is also contained in the context object.
If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
Otherwise:
Let reference node equal original start node.
While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
Set new node to the parent of reference node, and new offset to one plus the index of reference node.
If reference node's parent were null, it would be the root of the context object, so would be an inclusive ancestor of original end node, and we could not reach this point.
If original start node is a Text
or
Comment
node,
replace data with node
original start node, offset
original start offset, count
original start node's
length minus
original start offset, data the empty string.
For each node in nodes to remove, in tree order, remove node from its parent.
If original end node is a Text
or
Comment
node,
replace data with node
original end node, offset 0, count
original end offset), and data the empty string.
The extractContents()
method
must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let frag be a new DocumentFragment
whose node document is the same as
the node document of the
context object's
start node.
If start equals end, return frag, and terminate these steps.
Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.
If original start node equals
original end node, and they are a Text
or
Comment
node:
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
Append clone to frag.
Replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string.
Return frag and terminate these steps.
Let common ancestor be original start node.
While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
If original start node is an inclusive ancestor of original end node, let first partially contained child be null.
Otherwise, let first partially contained child be the first child of common ancestor that is partially contained in the context object.
If original end node is an inclusive ancestor of original start node, let last partially contained child be null.
Otherwise, let last partially contained child be the last child of common ancestor that is partially contained in the context object.
These variable assignments do actually always make sense. For instance, if the original start node is not an inclusive ancestor of the original end node, the original start node is itself partially contained in the range, and so are all its ancestors up until a child of the common ancestor. The common ancestor can't be original start node, because it must be an inclusive ancestor of the original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
Let contained children be a list of all children of common ancestor that are contained in the context object, in tree order.
If any member of contained children is a
DocumentType
, throw a
"HierarchyRequestError
" exception and terminate these
steps.
We do not have to worry about the first or last partially
contained node, because a DocumentType
can never be
partially contained. It cannot be a boundary point of a range, and it
cannot be the ancestor of anything.
If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
Otherwise:
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 couldn't reach this point.
If first partially contained child is a
Text
or Comment
node:
In this case, the first partially contained child is the original start node.
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.
Append clone to frag.
Replace data with node original start node, offset original start offset, count original start node's length minus original start offset, and data the empty string.
Otherwise, if first partially contained child is not null:
Let clone be a clone of first partially contained child.
Append clone to frag.
Range
whose start is (original start
node, original start offset) and whose end is (first partially contained
child, length of first partially contained child).
extractContents()
on subrange.
Is this method of recursing black-box detectable? E.g., would it fire extra DOM mutation events or something? What we really mean is to get a list of nodes to insert, then insert them directly into frag, without an intermediate document fragment.
For each contained child in contained children, append contained child to frag.
If last partially contained child is a
Text
or Comment
node:
In this case, the last partially contained child is the original end node.
Let clone be a clone of original end node.
Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
Append clone to frag.
Replace data with node original end node, offset 0, count original end offset, and data the empty string.
Otherwise, if last partially contained child is not null:
Let clone be a clone of last partially contained child.
Append clone to frag.
Range
whose start is (last partially
contained child, 0) and whose end is (original end node,
original end offset).
extractContents()
on subrange.
For each child of subfrag, in tree order, append that child to clone.
Return frag.
The cloneContents()
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let frag be a new DocumentFragment
whose node document is the same as
the node document of the
context object's
start node.
If start equals end, return frag, and terminate these steps.
Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.
If original start node equals
original end node, and they are a Text
or
Comment
node:
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
Append clone to frag.
Return frag and terminate these steps.
Let common ancestor be original start node.
While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
If original start node is an inclusive ancestor of original end node, let first partially contained child be null.
Otherwise, let first partially contained child be the first child of common ancestor that is partially contained in the context object.
If original end node is an inclusive ancestor of original start node, let last partially contained child be null.
These variable assignments do actually always make sense. For instance, if the original start node is not an inclusive ancestor of the original end node, the original start node is itself partially contained in the range, and so are all its ancestors up until a child of the common ancestor. The common ancestor can't be original start node, because it must be an inclusive ancestor of the original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
Let contained children be a list of all children of common ancestor that are contained in the context object, in tree order.
If any member of contained children is a
DocumentType
, throw a
"HierarchyRequestError
" exception and terminate these
steps.
We don't have to worry about the first or last partially
contained node, because a DocumentType
can never be partially
contained. It can't be a boundary point of a range, and it can't be the
ancestor of anything.
If first partially contained child is a
Text
or Comment
node:
In this case, the first partially contained child is the original start node.
Let clone be a clone of original start node.
Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.
Append clone to frag.
Otherwise, if first partially contained child is not null:
Let clone be a clone of first partially contained child.
Append clone to frag.
Range
whose start is (original start
node, original start offset) and whose end is (first partially contained
child, length of first partially contained child).
cloneContents()
on subrange.
Is this method of recursing black-box detectable? E.g., would it fire extra DOM mutation events or something? What we really mean is to get a list of nodes to insert, then insert them directly into frag, without an intermediate document fragment.
For each child of subfrag, in tree order, append that child to clone.
For each contained child in contained children:
If last partially contained child is a
Text
or Comment
node:
In this case, the last partially contained child is the original end node.
Let clone be a clone of original end node.
Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
Append clone to frag.
Otherwise, if last partially contained child is not null:
Let clone be a clone of last partially contained child.
Append clone to frag.
Range
whose start is (last partially
contained child, 0) and whose end is (original end node,
original end offset).
cloneContents()
on subrange.
For each child of subfrag, in tree order, append that child to clone.
Return frag.
The
insertNode(node)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If start node is a
Comment
node, or a Text
node whose parent is null, throw an "HierarchyRequestError
"
exception and terminate these steps.
If start node is a
Text
node,
split it with offset
context object's
start offset, and let
reference node be the result.
Otherwise, let reference node be the child of start node whose index is start offset, or null if there is no such child.
If reference node is null, let parent be start node.
Otherwise, let parent be the parent of reference node.
Let new offset be the index of reference node, or parent's length if reference node is null.
Add node's
length to
new offset, if node is a
DocumentFragment
. Otherwise add one to
new offset.
Pre-insert node into parent before reference node.
If start and end are the same, set end to (parent, new offset).
The
surroundContents(newParent)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If a non-Text
node is
partially contained in the context object,
throw a
"InvalidStateError
" exception and terminate these steps.
If newParent is a Document
,
DocumentType
, or DocumentFragment
node,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
extractContents()
on
the context object, and let fragment be the
result.
insertNode(newParent)
on the context object.
appendChild(fragment)
on
newParent.
selectNode(newParent)
on the context object.
The cloneRange()
method must throw an
"InvalidStateError
" exception if the
detached flag is set. Otherwise,
it must return a new range with the same
start and
end as the context object.
The detach()
method must
run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Set the detached flag.
comparePoint
( parent, offset )
Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range.
intersectsNode
( node )
Returns whether range intersects node.
The
isPointInRange(node, offset)
must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If node's root is different from the context object's root, return false and terminate these steps.
If node is a
doctype,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
If offset is greater than
node's length,
throw an
"IndexSizeError
" exception and terminate these steps.
If (node, offset) is before start or after end, return false and terminate these steps.
Return true.
The
comparePoint(node, offset)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If node's root is
different from the context object's
root,
throw a "WrongDocumentError
"
exception and terminate these steps.
If node is a
doctype,
throw an
"InvalidNodeTypeError
" exception and terminate these
steps.
If offset is greater than
node's length,
throw an
"IndexSizeError
" exception and terminate these steps.
If (node, offset) is before start, return −1 and terminate these steps.
If (node, offset) is after end, return 1 and terminate these steps.
Return 0.
The
intersectsNode(node)
method must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
If node's root is different from the context object's root, return false and terminate these steps.
Let parent be node's parent.
If parent is null, throw a "NotFoundError
" exception
and terminate these steps.
All implementations throw in this case, but would it make more sense to simply return true? This case can only occur when the roots are the same, so it means that node is the range's root, so the range is fully contained in node.
Let offset be node's index.
If (parent, offset) is before end and (parent, offset + 1) is after start, return true and terminate these steps.
Return false.
The stringifier must run these steps:
If the detached flag is
set, throw an
"InvalidStateError
" exception and terminate these steps.
Let s be the empty string.
If start node equals
end node, and it is a
Text
node, return the
substring of that Text
node's data beginning at
start offset and ending at
end offset, and terminate these
steps.
If start node is a
Text
node, append to
s the substring of that
node's
data from the
start offset until the end.
Append to s the concatenation, in
tree order, of the
data of all Text
nodes that are contained in
the context object.
If end node is a
Text
node, append to
s the substring of that
node's
data from its start until the
end offset.
Return s.
The following extensions to the Range
interface are defined
in various other specifications:
createContextualFragment()
method;
[DOMPS]
getClientRects()
method; and
getBoundingClientRect()
method.
[CSSOMVIEW]
NodeIterator
and TreeWalker
objects can be used
to filter and traverse node
trees.
Each NodeIterator
and TreeWalker
object has an
associated active flag to avoid
recursive invocations. It is initially unset.
Each NodeIterator
and TreeWalker
object also
has an associated root
node,
whatToShow bitmask, and
filter callback.
To filter node run these steps:
If active flag is set
throw an
"InvalidStateError
", terminate these steps, and
terminate the steps of the algorithm that invoked this algorithm.
Let n be node's
nodeType
attribute value minus 1.
If the nth bit (where 0 is the least
significant bit) of
whatToShow is not set,
return FILTER_SKIP
and
terminate these steps.
If filter is null return
FILTER_ACCEPT
and terminate
these steps.
Set the active flag.
Let result be the return value of invoking filter.
Unset the active flag.
If an exception was thrown, re-throw the exception, terminate these steps, and terminate the steps of the algorithm that invoked this algorithm.
Return result.
NodeIterator
interface NodeIterator { readonly attribute Node root; readonly attribute Node? referenceNode; readonly attribute boolean pointerBeforeReferenceNode; readonly attribute unsigned long whatToShow; readonly attribute NodeFilter? filter; Node? nextNode(); Node? previousNode(); void detach(); };
NodeIterator
objects can be created using the
createNodeIterator()
method.
Each NodeIterator
object has an associated
iterator collection, which is a
collection rooted at
root, whose filter matches any
node.
Before a node is removed from the iterator collection, these steps must be run:
If the node is not a
descendant of
root and is not an
ancestor of the
referenceNode
attribute
value or the
referenceNode
attribute
value itself, terminate these steps.
If the
pointerBeforeReferenceNode
attribute value is false, set the
referenceNode
attribute
to the first node
preceding the
node that is being removed, and terminate
these steps.
If the
pointerBeforeReferenceNode
attribute value is true and there is a node
following the
node that is being removed, set the
referenceNode
attribute
to the first such node, and terminate these
steps.
Set the
referenceNode
attribute
to the first node
preceding the
node that is being removed and set the
pointerBeforeReferenceNode
attribute to false.
Each NodeIterator
object also has an associated
detached flag which is initially unset.
As mentioned earlier NodeIterator
objects have an
associated active flag,
root
node,
whatToShow bitmask, and
filter callback as well.
The root
attribute
must return root.
The
referenceNode
attribute must return what it was initialized to.
The
pointerBeforeReferenceNode
attribute must return what it was initialized to. When a
NodeIterator
is created it must be initialized to true.
The whatToShow
attribute must return
whatToShow.
The filter
attribute must return filter.
To traverse in direction direction run these steps:
If the detached flag is set
throw an
"InvalidStateError
" exception and terminate these steps.
Let node be the value of the
referenceNode
attribute.
Let before node be the value of the
pointerBeforeReferenceNode
attribute.
Run these substeps:
If before node is false, let node be the first node following node in the iterator collection. If there is no such node return null and terminate these steps.
If before node is true, set it to false.
If before node is true, let node be the first node preceding node in the iterator collection. If there is no such node return null and terminate these steps.
If before node is false, set it to true.
Filter node and let result be the return value.
If the detached flag is set
throw an
"InvalidStateError
" exception and terminate these
steps.
If result is
FILTER_ACCEPT
, go to the
next step in the overall set of steps.
Otherwise, run these substeps again.
Set the
referenceNode
attribute
to node, set the
pointerBeforeReferenceNode
attribute to before node, and return
node.
The nextNode()
method must traverse in
direction next.
The
previousNode()
method must traverse in
direction previous.
When the detach()
method is invoked set the detached flag and set the
referenceNode
attribute to
null.
TreeWalker
interface TreeWalker { readonly attribute Node root; readonly attribute unsigned long whatToShow; readonly attribute NodeFilter? filter; attribute Node currentNode; Node? parentNode(); Node? firstChild(); Node? lastChild(); Node? previousSibling(); Node? nextSibling(); Node? previousNode(); Node? nextNode(); };
TreeWalker
objects can be created using the
createTreeWalker()
method.
As mentioned earlier TreeWalker
objects have an
associated active flag,
root
node,
whatToShow bitmask, and
filter callback.
The root
attribute must
return root.
The whatToShow
attribute must return
whatToShow.
The filter
attribute
must return filter.
The currentNode
attribute must return what it was initialized to.
Setting the currentNode
attribute must set it to the new value.
The parentNode()
method must run these steps:
Let node be the value of the
currentNode
attribute.
While node is not null and is not root, run these substeps:
Let node be node's parent.
If node is not null and
filtering node
returns FILTER_ACCEPT
,
then set the currentNode
attribute to node, return node, and
terminate these steps.
Return null.
To traverse children of type type run these steps:
Let node and current be the value
of the currentNode
attribute.
While node is not null, run these substeps:
Filter node and let result be the return value.
If result is
FILTER_ACCEPT
, then set
the currentNode
attribute to node, return node, and
terminate these steps.
If result is
FILTER_SKIP
and
node has a child,
then set node as follows and run these substeps again:
Set it to the first child
Set it to the last child
While node is not null, run these inner substeps:
Let sibling be the next sibling of node.
Let sibling be the previous sibling of node.
If sibling is not null, set node to it and terminate these inner substeps.
If node has a parent that is not root or current then set node to it.
Otherwise, return null and terminate these steps.
The firstChild()
method must traverse children
of type first.
The lastChild()
method must traverse children
of type last.
To traverse siblings of type type run these steps:
Let node be the value of the
currentNode
attribute.
If node is root return null and terminate these steps.
Run these substeps:
Let sibling be the next sibling of node.
Let sibling be the previous sibling of node.
While sibling is not null run these inner substeps:
Set node to sibling.
Filter node and let result be the return value.
If result is
FILTER_ACCEPT
, then set
the currentNode
attribute to node, return node, and
terminate these steps.
Let sibling be the first child of node.
Let sibling be the last child of node.
If result is
FILTER_REJECT
or
sibling is null, then set sibling as
follows:
Let sibling be the next sibling of node.
Let sibling be the previous sibling of node.
Set node to its parent.
If node is null or is root return null and terminate these steps.
Filter
node and if the return value is
FILTER_ACCEPT
, then
return null and terminate these steps.
Run these substeps again.
The
nextSibling()
method must traverse children
of type next.
The
previousSibling()
method must traverse children
of type previous.
The
previousNode()
method must run these steps:
Let node be the value of the
currentNode
attribute.
While node is not root run these substeps:
Let sibling be the previous sibling of node.
While sibling is not null run these inner substeps:
Set node to sibling.
Filter node and let result be the return value.
While result is not
FILTER_REJECT
and
node has a
child, run these innermost
substeps:
Set node to its last child.
Filter node and set result to the return value.
If result is
FILTER_ACCEPT
, then set
the currentNode
attribute to node, return node, and
terminate these steps.
If node is root or has no parent, return null and terminate these steps.
Set node to its parent.
Filter
node and if the return value is
FILTER_ACCEPT
, then set
the currentNode
attribute
to node, return node, and terminate
these steps.
The nextNode()
method must run these steps:
Let node be the value of the
currentNode
attribute.
Let result be
FILTER_ACCEPT
.
Run these substeps:
While result is not
FILTER_ACCEPT
and
node has a child,
run these inner substeps:
Set node to its first child
Filter node and let result be the return value.
If result is
FILTER_ACCEPT
, then set
the currentNode
attribute
to node, return node, and terminate
these steps.
If a node is following node and is not following root, set node to the first such node.
Otherwise, run these substeps again (skipping the next step).
Filter
node and if the return value is
FILTER_ACCEPT
, then set
the currentNode
attribute
to node, return node, and terminate
these steps.
NodeFilter
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; // historical const unsigned long SHOW_TEXT = 0x4; const unsigned long SHOW_CDATA_SECTION = 0x8; // historical const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // historical const unsigned long SHOW_ENTITY = 0x20; // historical const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40; const unsigned long SHOW_COMMENT = 0x80; const unsigned long SHOW_DOCUMENT = 0x100; const unsigned long SHOW_DOCUMENT_TYPE = 0x200; const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400; const unsigned long SHOW_NOTATION = 0x800; // historical unsigned short acceptNode(Node node); };
NodeFilter
objects can be used as
filter callback and provide
constants for the whatToShow
bitmask.
It is typically implemented as an ECMAScript function.
These constants can be used as callback return value:
FILTER_ACCEPT
(1);
FILTER_REJECT
(2);
FILTER_SKIP
(3).
These constants can be used for the whatToShow bitmask:
SHOW_ALL
(4294967295, FFFFFFFF in hexadecimal);
SHOW_ELEMENT
(1);
SHOW_TEXT
(4);
SHOW_PROCESSING_INSTRUCTION
(64, 40 in hexadecimal);
SHOW_COMMENT
(128, 80 in hexadecimal);
SHOW_DOCUMENT
(256, 100 in hexadecimal);
SHOW_DOCUMENT_TYPE
(512, 200 in hexadecimal);
SHOW_DOCUMENT_FRAGMENT
(1024, 400 in hexadecimal).
A collection is an object that represents a lists of DOM nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.
If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.
When a collection is created, a filter and a root are associated with it.
The collection then represents a view of the subtree rooted at the collection's root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.
An attribute that returns a live collection must return the same object every time it is retrieved.
NodeList
A NodeList
object is a kind of
collection.
interface NodeList { getter Node? item(unsigned long index); readonly attribute unsigned long length; };
length
Returns the number of elements in the collection.
item
(index)
Returns the item with index index from the collection. The items are sorted in tree order.
The object's supported property indices are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported property indices.
The length
attribute must
return the number of nodes represented by the collection.
The item(index)
method must return the indexth
node in the collection. If there is no
indexth node in the collection, then the method must return null.
HTMLCollection
The HTMLCollection
interface represents a generic collection of
elements.
This interface is called HTMLCollection
for
historical reasons. The
namedItem
method returns an
object
for interfaces that inherit from
this interface, which return other objects for historical reasons.
interface HTMLCollection {
readonly attribute unsigned long length;
getter Element? item(unsigned long index);
getter object? namedItem(DOMString name); // only returns Element
};
length
Returns the number of elements in the collection.
item
(index)
Returns the item with index index from the collection. The items are sorted in tree order.
namedItem
(name)
Returns the first item with ID or name name from the collection.
Only a
, applet
,
area
, embed
,
form
, frame
,
frameset
, iframe
,
img
, and object
elements in the
HTML namespace can have a name for the purpose of this
method; their name is given by the value of their
name
attribute.
The object's supported property indices are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported property indices.
The length
attribute
must return the number of nodes represented by the collection.
The item(index)
method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must
return null.
The supported property names consist
of the values of the name
attributes of each a
, applet
, area
, embed
, form
, frame
, frameset
, iframe
, img
, and
object
element in the HTML namespace,
represented by the collection with a name
attribute, plus the list of IDs that the elements
represented by the collection have.
The
namedItem(key)
method must return the first element in
the collection that falls into one of
the following categories:
a
, applet
, area
, embed
, form
, frame
, frameset
, iframe
,
img
, or object
element, in the
HTML namespace, with a name
attribute equal to
key, or,
If no such elements are found, then the method must return null.
DOMStringList
interface DOMStringList { readonly attribute unsigned long length; getter DOMString? item(unsigned long index); boolean contains(DOMString string); };
The DOMStringList
interface represents an interface to an
ordered list of strings.
length
Returns the number of tokens in the string.
item
(index)
Returns the string with index index.
contains
(string)
Returns true if the string is present; false otherwise.
The length
attribute must return the number of strings in the list.
The object's
supported property indices are the
numbers in the range zero to the context object's
length
attribute value minus 1,
unless the context object's
length
attribute value is zero,
in which case there are no
supported property indices.
The
item(index)
method must return the indexth string in the list. If
index is equal to or greater than the number of strings, then the
method must return null.
The
contains(string)
method must return true if the list of strings contains string,
or false otherwise.
DOMTokenList
The DOMTokenList
interface represents an interface to an
underlying string that
consists of a set of space-separated tokens.
DOMTokenList
objects are always
case-sensitive, even when the underlying string might
ordinarily be treated in a case-insensitive manner.
interface DOMTokenList { readonly attribute unsigned long length; getter DOMString? item(unsigned long index); boolean contains(DOMString token); void add(DOMString token); void remove(DOMString token); boolean toggle(DOMString token); stringifier DOMString (); };
length
Returns the number of tokens in the string.
item
(index)
Returns the token with index index. The tokens are returned in the order they are found in the underlying string.
contains
(token)
Returns true if the token is present; false otherwise.
Throws a "SyntaxError
" exception if token is empty.
Throws an "InvalidCharacterError
" exception if token contains any spaces.
add
(token)
Adds token, unless it is already present.
Throws a "SyntaxError
" exception if token is empty.
Throws an "InvalidCharacterError
" exception if token contains any spaces.
remove
(token)
Removes token if it is present.
Throws a "SyntaxError
" exception if token is empty.
Throws an "InvalidCharacterError
" exception if token contains any spaces.
toggle
(token)
Adds token if it is not present, or removes it if it is. Returns true if token is now present (it was added); returns false if it is not (it was removed).
Throws a "SyntaxError
" exception if token is empty.
Throws an "InvalidCharacterError
" exception if token contains any spaces.
The length
attribute must return the number of tokens that result from
splitting the
context object's
underlying string on
spaces.
The object's
supported property indices are the
numbers in the range zero to the context object's
length
attribute value minus 1,
unless the context object's
length
attribute value is zero,
in which case there are no
supported property indices.
The
item(index)
method must run these steps:
length
attribute value, then
return null and terminate these steps.
For example, if the string is "a b a c
"
then there are four tokens: the token with index 0 is "a
",
the token with index 1 is "b
", the token with index 2 is
"a
", and the token with index 3 is "c
".
The
contains(token)
method must run these steps:
SyntaxError
" exception and terminate these steps.
InvalidCharacterError
" exception and terminate these
steps.
The
add(token)
method must run these steps:
SyntaxError
" exception and terminate these steps.
InvalidCharacterError
" exception and terminate these
steps.
The
remove(token)
method must run these steps:
SyntaxError
" exception and terminate these steps.
InvalidCharacterError
" exception and terminate these
steps.
The
toggle(token)
method must run these steps:
SyntaxError
"
exception and terminate these steps.
InvalidCharacterError
" exception and terminate these
steps.
DOMTokenList
objects must
stringify to the
context object's
underlying string.
DOMSettableTokenList
The DOMSettableTokenList
interface is the same as the
DOMTokenList
interface, except that it allows the
underlying string to be directly changed.
interface DOMSettableTokenList : DOMTokenList { attribute DOMString value; };
value
Returns the underlying string.
Can be set, to change the underlying string.
An object implementing the DOMSettableTokenList
interface must act as defined for the DOMTokenList
interface, except for the value
attribute defined
here.
The value
attribute must return the underlying string and, on setting must replace the underlying string with the new value.
Authors are strongly discouraged from using DOM features, as they are notoriously unreliable and imprecise. Authors are encouraged to rely on explicit feature testing or graceful degradation.
A DOM feature is a unique, ASCII case-insensitive string that represents a certain feature of the user agent.
A DOM feature version is a (feature, version) tuple, where feature is DOM feature and version is a case-sensitive string representing a version number.
Specifications may define which DOM features a user agent is to support, as well as an associated list of one or more case-sensitive strings representing version numbers, and under which circumstances, when necessary for compatibility (i.e. because of historical use). Specifications must not introduce new DOM features or new versions for existing features.
A user agent must support a DOM feature version (feature, version) if it supports a DOM feature that is a ASCII case-insensitive match for feature and version is in the associated list of versions.
A user agent must support the (feature, "") tuple if it supports a DOM feature that is a ASCII case-insensitive match for feature.
For historical reasons, user agents must support the "XML" DOM feature with the versions "1.0" and "2.0" associated with it, and the "Core" DOM feature with the version "2.0" associated with it.
As explained in goals this specification is a significant revision of various DOM specifications. This section attempts to enumerate the changes.
These are the changes made to the features described in the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events. The other chapters are expected to move to a separate specification.
Event.type
.
preventDefault()
only
changes what defaultPrevented
and dispatchEvent()
return
if the event is cancelable.
EventException
.
initEvent()
rather than after
dispatch.
These are the changes made to the features described in DOM Level 3 Core.
DOMString
and
DOMTimeStamp
are now defined in Web IDL.
Node
now inherits from EventTarget
.
Nodes are implicitly adopted across document boundaries.
Doctypes now always have a node document and can be moved across document boundaries.
ProcessingInstruction
now inherits from
CharacterData
.
DOMError
is completely redesigned.
The remainder of interfaces and interface members listed in this section were removed to simplify the DOM platform. Implementations conforming to this specification will not support them.
Interfaces:
CDATASection
DOMConfiguration
DOMErrorHandler
DOMImplementationList
DOMImplementationSource
DOMLocator
DOMObject
DOMUserData
Entity
EntityReference
NamedNodeMap
NameList
Notation
TypeInfo
UserDataHandler
Interface members:
Node
hasAttributes()
attributes
namespaceURI
prefix
localName
isSupported
getFeature()
getUserData()
setUserData()
isSameNode()
Document
createCDATASection()
createAttribute()
createAttributeNS()
createEntityReference()
inputEncoding
xmlEncoding
xmlStandalone
xmlVersion
strictErrorChecking
domConfig
normalizeDocument()
renameNode()
DOMImplementation
getFeature()
Attr
No longer inherits from Node
and therefore completely
changed.
Element
getAttributeNode()
getAttributeNodeNS()
setAttributeNode()
removeAttributeNode()
schemaTypeInfo
setIdAttribute()
setIdAttributeNS()
setIdAttributeNode()
DocumentType
entities
notations
internalSubset
Text
isElementContentWhitespace
replaceWholeText()
These are the changes made to the features described in the "Document Object Model Range" chapter of DOM Level 2 Traversal and Range.
RangeException
has been removed.
Range
objects can now be moved between
documents and used on
nodes that are not
in a document.
Probably incomplete.
These are the changes made to the features described in the "Document Object Model Traversal" chapter of DOM Level 2 Traversal and Range.
Differences with respect to
createNodeIterator()
and
createTreeWalker()
:
In the previous edition of DOM Traversal both these methods accepted a fourth argument named entityReferenceExpansion that has been dropped as the DOM never actually exposed entity references in practice.
In the previous edition of DOM Traversal both these methods threw a
"NotSupportedError
" when the root was
null. Now this will throw a language-binding specific exception.
In the previous edition of DOM Traversal both these methods did not have optional arguments. That was changed for convenience.
acceptNode()
and its
constants have been changed to use unsigned short, rather than just short.
The expandEntityReferences
attribute has been removed
from the NodeIterator
and TreeWalker
objects.
The referenceNode
and
pointerBeforeReferenceNode
attributes have been added to NodeIterator
objects to align
with user agents.
nextNode()
and
previousNode()
node now
throw when invoked from a NodeFilter
to align with user agents.
Thanks to Adrian Bateman, Brandon Slade, Cameron McCormack, Dethe Elza, David Flanagan, Glenn Maynard, Henri Sivonen, Jacob Rossi, Jake Verbaten, James Graham, Jens Lindström, João Eiras, Jonas Sicking, 呂康豪 (Kang-Hao Lu), Ojan Vafai, Olli Pettay, Ryosuke Niwa, Shiki Okasaka, Stig Halvorsen, and Travis Leithead for their useful comments.
Special thanks to Sam Sneddon and Simon Pieters for first specifying the Nodes section of this specification and their useful comments.
Special thanks also to Ian Hickson for first specifying some parts of this specification in HTML and his useful comments. [HTML]
Finally, while this specification has been written from scratch, special thanks should also be extended to the editors of the various specifications that previously defined the features in this specification. In particular: