Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Web DOM Core defines the DOM Core part of the Web platform. 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 7 October 2010 W3C Working Draft of Web DOM Core. Please send comments to public-webapps@w3.org (archived) with [DOMCore] at the start of the subject line.
This document is produced by the Web Applications (WebApps) Working Group as First Public Working Draft. 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.
Obsoleting DOM Level 3 Core is not a goal. It is a fine specification for Java servers. Web DOM Core presents an alternative.
New features might be added, once everything else is sort of stable.
The term tree order means a
pre-order, depth-first traversal of DOM nodes involved (through the
parentNode
/childNodes
relationship).
The term context node means the
Node
on which the method or
attribute being discussed was called.
The term root element, when not explicitly qualified as referring to the document's root element, means the furthest ancestor element node of whatever node is being discussed, or the node itself if it has no ancestors. When the node is a part of the document, then the node's root element is indeed the document's root element; however, if the node is not currently part of the document tree, the root element will be an orphaned node.
When an element's root element is
the root element of a Document
, it is said to be in a Document
.
A node's home subtree is the
subtree rooted at that node's root
element. When a node is in a
Document
, its home
subtree is that Document
's
tree.
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).
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]
Except where otherwise specified, if an IDL
attribute that is a floating point number type (float
)
is assigned an Infinity or Not-a-Number (NaN) value, a NOT_SUPPORTED_ERR
exception must be raised.
Except where otherwise specified, if a method with an argument
that is a floating point number type (float
)
is passed an Infinity or Not-a-Number (NaN) value, a NOT_SUPPORTED_ERR
exception must be raised.
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 recognise the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.
This specification defines several comparison operators for strings.
Comparing two strings in a case-sensitive manner means comparing them exactly, codepoint for codepoint.
Comparing two strings in a ASCII case-insensitive manner means comparing them exactly, codepoint for codepoint, 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 uppercase means replacing all characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).
Converting a string to lowercase means replacing all characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) with the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).
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.
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.
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.
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.
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.
To clone a node, with a new ownerDocument and with a clone children flag, these steps must be run:
If node is a Document
or DocumentType
node, raise a DATA_CLONE_ERR
exception and terminate these steps.
Let copy be a new Node
that implements the same interfaces as
node, with ownerDocument
set to
new ownerDocument. Also copy the following,
depending on the node:
Element
Its namespace, namespace prefix, local name, and its associated
collection of Attr
objects.
Text
Comment
Its data
.
ProcessingInstruction
—
If the clone children flag is set, clone all the children of node and append them to copy, with the same new ownerDocument and the clone children flag being set.
Return copy.
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; // historical 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 NOT_READABLE_ERR = 24; const unsigned short DATA_CLONE_ERR = 25; const unsigned short ENCODING_ERR = 26; unsigned short code; DOMString name; };
The code
exception field
must return the code for the exception, which must be one of the
following:
INDEX_SIZE_ERR
:
the index is not in the allowed range;DOMSTRING_SIZE_ERR
:
the text does not fit in a DOMString
(historical);HIERARCHY_REQUEST_ERR
:
the operation would yield an incorrect nodes model;
WRONG_DOCUMENT_ERR
:
the object is in the wrong Document
, a call to importNode
is required;INVALID_CHARACTER_ERR
:
the string contains invalid characters;NO_DATA_ALLOWED_ERR
:
data is specified for an object that does not support it
(historical);NO_MODIFICATION_ALLOWED_ERR
:
the object can not be modified;NOT_FOUND_ERR
:
the object can not be found here;NOT_SUPPORTED_ERR
:
this operation is not supported;INUSE_ATTRIBUTE_ERR
:
the attribute is in use (historical);INVALID_STATE_ERR
:
the object is in an invalid state;SYNTAX_ERR
: the
string did not match the expected pattern;INVALID_MODIFICATION_ERR
:
the object can not be modified (historical);NAMESPACE_ERR
:
the operation is not allowed by Namespaces in XML;
[XMLNS]INVALID_ACCESS_ERR
:
the object does not support the operation or argument;VALIDATION_ERR
:
the operation is invalid (historical);TYPE_MISMATCH_ERR
:
the type of the object does not match the expected type;
SECURITY_ERR
:
the operation is insecure; NETWORK_ERR
: a
network error occurred; ABORT_ERR
: the user
aborted an operation; URL_MISMATCH_ERR
:
the given URL does not match another URL; QUOTA_EXCEEDED_ERR
:
the quota has been exceeded; TIMEOUT_ERR
: a
timeout occurred; NOT_READABLE_ERR
:
the file cannot be read, typically due due to permission problems
that occur after a reference to a file has been acquired;
DATA_CLONE_ERR
:
the object can not be cloned; ENCODING_ERR
: an
error occurred while encoding the data.The name
exception field
must return the name of the exception constant as a string.
The DOM represents a tree of Node
objects. The following structure is imposed
on this tree, represented as relationship between the node and its
child nodes:
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
ProcessingInstruction
Comment
Text
No children.
Node
interface Node { 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; unsigned short compareDocumentPosition(Node other); attribute DOMString nodeValue; attribute DOMString textContent; Node insertBefore([NoNull] Node newChild, Node refChild); Node replaceChild([NoNull] Node newChild, [NoNull] Node oldChild); Node removeChild([NoNull] Node oldChild); Node appendChild([NoNull] Node newChild); Node cloneNode(boolean deep); boolean isSameNode(Node node); boolean isEqualNode(Node node); DOMString lookupPrefix([TreatNullAs=EmptyString] DOMString namespace); DOMString lookupNamespaceURI(DOMString? prefix); boolean isDefaultNamespace([TreatNullAs=EmptyString] DOMString namespace); };
The nodeType
attribute must
return the type of the node, which must be one of the
following:
ELEMENT_NODE
ATTRIBUTE_NODE
(historical)TEXT_NODE
CDATA_SECTION_NODE
(historical)ENTITY_REFERENCE_NODE
(historical)ENTITY_NODE
(historical)PROCESSING_INSTRUCTION_NODE
COMMENT_NODE
DOCUMENT_NODE
DOCUMENT_TYPE_NODE
DOCUMENT_FRAGMENT_NODE
NOTATION_NODE
(historical)The constants marked historical can no longer be returned, but are still exposed on the interface.
The nodeName
attribute must
return the following, depending on the context node:
Element
The context node's tagName
attribute.
Text
"#text
".
ProcessingInstruction
The context node's target
attribute.
Comment
"#comment
".
Document
"#document
".
DocumentType
The context node's name
attribute.
DocumentFragment
"#document-fragment
".
The baseURI
attribute must
...
The ownerDocument
attribute
must return the Document
node
that the context node is associated
with, or null if there is none.
The parentNode
attribute must
run these steps:
If the context node does not have a parent node, return null and terminate these steps.
Return the parent node of the context node.
The parentElement
attribute
must return the parent node of the context
node if there is a parent and it is an Element
node, or null otherwise.
The hasChildNodes()
method
must return false if the context node's
firstChild
is null, or true
otherwise.
The childNodes
attribute must
return a NodeList
rooted at
the context node matching only child
nodes.
The firstChild
attribute must
return the first child node of the context
node, or null if there is none.
The lastChild
attribute must
return the last child node of the context
node, or null if there is none.
The previousSibling
attribute must run these steps:
If the context node does not have a previous sibling node, return null and terminate these steps.
Return the previous sibling node of the context node.
The nextSibling
attribute
must run these steps:
If the context node does not have a next sibling node, return null and terminate these steps.
Return the next sibling node of the context node.
These are the constants compareDocumentPosition()
returns.
DOCUMENT_POSITION_DISCONNECTED
DOCUMENT_POSITION_PRECEDING
DOCUMENT_POSITION_FOLLOWING
DOCUMENT_POSITION_CONTAINS
DOCUMENT_POSITION_CONTAINED_BY
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
The compareDocumentPosition(other)
method must ...
The nodeValue
attribute must
return the following, depending on the context node:
Text
Comment
ProcessingInstruction
The context node's textContent
attribute.
Null.
Setting the nodeValue
attribute must do as
described below, depending on the context
node:
Text
Comment
ProcessingInstruction
Set the context node's textContent
attribute to the
given value.
Do nothing.
The textContent
attribute
must return the following, depending on the context node:
DocumentFragment
Element
The concatenation of the data
of all the descendant
Text
nodes of the context node, in tree
order.
Text
Comment
The context node's data
attribute.
ProcessingInstruction
The context node's data
attribute.
Setting the textContent
attribute must do as
described below, depending on the context
node:
DocumentFragment
Element
Remove all the descendent nodes of the context node.
Let data be the given value.
If data is not the empty string, append a
new Text
node to the context node whose data
is set to data.
Text
Comment
Set context node's data
attribute to the given
value.
ProcessingInstruction
Set the context node's data
attribute to the
given value.
The insertBefore(newChild, refChild)
method must run these steps:
If the context node is
a Text
node, then raise a HIERARCHY_REQUEST_ERR
and terminate these steps.
If refChild is null, return the result of
invoking context node's appendChild
with newChild as argument and terminate these steps.
If refChild is not a child of the context node, then raise a NOT_FOUND_ERR
exception and terminate these steps.
If newChild is the context node or an ancestor of the context node raise a HIERARCHY_REQUEST_ERR
and terminate these steps.
If newChild is a DocumentType
node and its ownerDocument
is not null
raise a NOT_SUPPORTED_ERR
exception and terminate these steps.
If newChild is a DocumentType
node set its ownerDocument
to the context node's ownerDocument
.
If newChild is not a DocumentType
node let newChild be the result of invoking the context node's ownerDocument
adoptNode
method with
newChild as its argument.
If newChild is a DocumentFragment
node, insert the
children of newChild in the context node, in tree
order, so that the last child becomes the previous sibling of
refChild.
Otherwise insert newChild in the context node as the previous sibling of refChild.
Return newChild.
The replaceChild(newChild, oldChild)
method must run these steps:
If the context node is
a Text
node, then raise a HIERARCHY_REQUEST_ERR
and terminate these steps.
If oldChild is not a child of the context node, then raise a NOT_FOUND_ERR
exception and terminate these steps.
If newChild is the context node or an ancestor of the context node raise a HIERARCHY_REQUEST_ERR
and terminate these steps.
If newChild is a DocumentType
node and its ownerDocument
is not null
raise a NOT_SUPPORTED_ERR
exception and terminate these steps.
If newChild is a DocumentType
node set its ownerDocument
to the context node's ownerDocument
.
If newChild is not a DocumentType
node let newChild be the result of invoking the context node's ownerDocument
adoptNode
method with
newChild as its argument.
Let refChild be oldChild's nextSibling
.
Remove oldChild from the context node.
Return the result of invoking the context node's insertBefore
method with
newChild and refChild as
arguments.
The removeChild(oldChild)
method must run these steps:
If oldChild is not a child of the context node, then raise a NOT_FOUND_ERR
exception and terminate these steps.
Remove oldChild from the context node.
Return oldChild.
The appendChild(newChild)
method must run these steps:
If the context node is
a Text
node, then raise a HIERARCHY_REQUEST_ERR
and terminate these steps.
If newChild is the context node or an ancestor of the context node raise a HIERARCHY_REQUEST_ERR
and terminate these steps.
If newChild is a DocumentType
node and its ownerDocument
is not null
raise a NOT_SUPPORTED_ERR
exception and terminate these steps.
If newChild is a DocumentType
node set its ownerDocument
to the context node's ownerDocument
.
If newChild is not a DocumentType
node let newChild be the result of invoking the context node's ownerDocument
adoptNode
method with
newChild as its argument.
Append newChild to the context node.
Return newChild.
The cloneNode(deep)
method must return a clone of the context node,
with new ownerDocument being the context node's ownerDocument
, and the
clone children flag set if deep is
true.
The isSameNode(node)
method must return true if node is a reference to the same object as the context node, or false otherwise.
The isEqualNode(node)
method must return true if all of the
following conditions are true, or false otherwise:
node is not null.
node's nodeType
is the same as the
context node's nodeType
.
node's nodeName
is the same as the
context node's nodeName
.
node's nodeValue
is the same as the
context node's nodeValue
.
The following are also equal, depending on node:
DocumentType
Element
Its namespace, namespace prefix, local name, and its associated
collection of Attr
objects.
Text
Comment
Its data
.
ProcessingInstruction
—
node's childNodes
' length
is the same as the
context node's childNodes
' length
.
Calling isEqualNode
on each child node
of the context node, with the child
node of the same index in node as argument
returns true for every child node.
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 there is an attribute associated with the element whose namespace prefix is "xmlns
" and value is namespace then
return its local name and terminate these steps.
Return the result of running locate a namespace prefix on its
parentNode
using namespace, if parentNode
is an Element
node, or null otherwise.
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 there is an attribute associated with the node 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.
Return the result of running locate a namespace on its parentNode
using prefix, if parentNode
is an Element
node, or null otherwise.
Document
Return the result of running locate a namespace on its documentElement
using
prefix, if documentElement
is not
null, or null otherwise.
DocumentType
DocumentFragment
Return null.
Return the result of running locate a namespace on its parentNode
using prefix, if parentNode
is an Element
node, or null otherwise.
The lookupPrefix(namespace)
method must run these steps:
If namespace is the empty string return null.
Otherwise it depends on the context node:
Element
Return the result of running locate a namespace prefix for the node using namespace.
Document
Return the result of locating a namespace prefix for its
documentElement
, if that
is not null, or null otherwise.
DocumentType
DocumentFragment
Return null.
Return the result of locating a namespace prefix for its
parentNode
, if that is an
Element
node, or null
otherwise.
The lookupNamespaceURI(prefix)
method must return the result of
running locate a namespace for
the context node using prefix.
The isDefaultNamespace(namespace)
method must run these steps:
Let defaultNamespace be the result of
invoking lookupNamespaceURI
with
null as argument on the context
node.
If defaultNamespace is null let it be the empty string.
Return true if defaultNamespace is namespace, or false otherwise.
DocumentFragment
interface DocumentFragment : Node { };
Document
interface Document : Node { readonly attribute DOMImplementation implementation; attribute DOMString documentURI; readonly attribute DOMString compatMode; 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([TreatNullAs=EmptyString] 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, boolean deep); Node adoptNode(Node node); };
A Document
node 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
node 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, the Document
must be in no-quirks
mode.
The mode is only ever changed from the default if
the Document
node is created
by the HTML parser, based on
the presence, absence, or value of the DOCTYPE string. [HTML]
compatMode
Returns the string "CSS1Compat
" if the
context node is in no-quirks
mode or limited-quirks mode, and
"BackCompat
", if the Document
is in quirks
mode.
The implementation
attribute must return the DOMImplementation
object that is
associated with the Document
node.
documentURI Should document.documentURI really exist? be readonly?
The compatMode
IDL
attribute must return the literal string "CSS1Compat
" unless the context
node is in quirks mode, in which case it must
instead return the literal string "BackCompat
".
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.
The doctype
attribute must
return the child of the Document
node that is a DocumentType
node, if there is one, or
null otherwise.
The documentElement
attribute must return the child of the Document
node that is an Element
node, if there is one, or null
otherwise.
The getElementsByTagName(localName)
method must run these steps:
If localName is "*
" (U+002A),
return a NodeList
rooted at
the context node, whose filter matches
only Element
nodes.
Otherwise, if the context node is an
HTML document, return a NodeList
rooted at the context node, whose filter matches only the
following nodes:
Element
nodes in the
HTML namespace whose local name is localName converted to
lowercase.Element
nodes, not
in the HTML namespace, whose local name is localName.Otherwise, return a NodeList
rooted at the context node, whose filter matches only
Element
nodes whose local name is localName.
When invoked with the same argument the same NodeList
object may be returned as returned
by an earlier call.
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 run these
steps:
If both namespace and localName are "*
" (U+002A) return a
NodeList
rooted at the
context node, whose filter matches only
Element
nodes.
Otherwise, if just namespace is
"*
" (U+002A), return a NodeList
rooted at the context node, whose filter matches only
Element
nodes whose local name is localName.
Otherwise, if just localName is
"*
" (U+002A), return a NodeList
rooted at the context node, whose filter matches only
Element
nodes whose namespace is namespace.
Otherwise, return a NodeList
rooted at the context node, whose filter matches only
Element
nodes whose namespace is namespace and local name is localName.
When invoked with the same argument the same NodeList
object may be returned as returned
by an earlier call.
The getElementsByClassName(classNames)
method takes a string that contains a set of space-separated tokens
representing classes. When called, the method must return a
live NodeList
object containing all the elements
in the context node, in tree order, that have all the classes specified in the
classNames argument, having obtained the
classes by
splitting the string on spaces.
(Duplicates are ignored.) If there are no tokens specified in the
argument, then the method must return an empty NodeList
. If the 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.
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
node, in tree order, in the context node whose ID is elementId, or null if
there is none.
The createElement(localName)
method must run the these
steps:
If localName does not match the Name
production in
XML, raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
If the context node is an HTML document, let localName be converted to lowercase.
Return a new Element
node
with no attributes, namespace set to the HTML namespace, local name set to localName, and ownerDocument
set to the
context node.
The createElementNS(namespace, qualifiedName)
method must run these steps:
If qualifiedName does not match the
Name
production in
XML, raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
If qualifiedName does not match the
QName
production in Namespaces in XML, raise a NAMESPACE_ERR
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 an empty string, raise a NAMESPACE_ERR
exception and terminate these steps.
If prefix is "xml
" and
namespace is not the XML namespace, raise a NAMESPACE_ERR
exception and terminate these steps.
If qualifiedName or prefix is "xmlns
" and namespace is not the XMLNS
namespace, raise a NAMESPACE_ERR
exception and terminate these steps.
If namespace is the XMLNS namespace and neither qualifiedName nor prefix is
"xmlns
", raise a NAMESPACE_ERR
exception and terminate these steps.
Return a new Element
node
with no attributes, namespace set to namespace, namespace prefix set
to prefix, local name set to localName, and ownerDocument
set to the
context node.
The createDocumentFragment()
method must return a new DocumentFragment
node with its
ownerDocument
set to the
context node.
The createTextNode(data)
method must return a new Text
node with its data
attribute set to
data and ownerDocument
set to the
context node.
No check is performed that the text node contains
characters that match the Char
production in
XML.
The createComment(data)
method must return a new Comment
node with its data
attribute set to
data and ownerDocument
set to the
context node.
No check is performed that the comment contains
characters that match the Char
production in
XML or that it contains two adjacent hyphens or ends with a
hyphen.
The createProcessingInstruction(target,
data)
method must run these
steps:
If the context node is an HTML document, raise a NOT_SUPPORTED_ERR
exception and terminate these steps.
If target does not match the Name
production in
XML, raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
If data contains the string "?>
", raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
Return a new ProcessingInstruction
, with
target
set to target, data set to data,
and ownerDocument
set to the
context node.
No check is performed that the processing
instruction target contains "xml" or the colon, or that the data
contains characters that match the Char
production in
XML.
The importNode(node, deep)
method must
return a clone of node,
with new ownerDocument being the context node, and the clone children
flag set if deep is true.
The adoptNode(node)
method must run these steps:
If node is a Document
node or a DocumentType
node, raise a NOT_SUPPORTED_ERR
exception and terminate these steps.
If node is an Element
node, it is affected by a base URL
change.
If node's parentNode
is not null, remove
node from its parent.
Set ownerDocument
for node and all its descendent nodes
to the context
node.
Return node.
DOMImplementation
User agents must create a new DOMImplementation
object whenever a
new Document
node is created
and associate it with the that Document
node.
interface DOMImplementation { boolean hasFeature(DOMString feature, [TreatNullAs=EmptyString] DOMString version); DocumentType createDocumentType([TreatNullAs=EmptyString] DOMString qualifiedName, DOMString publicId, DOMString systemId); Document createDocument([TreatNullAs=EmptyString] DOMString namespace, [TreatNullAs=EmptyString] 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 new DocumentType
, with the given qualifiedName, publicId, and
systemId. If qualifiedName
does not match the Name
production in
XML, an INVALID_CHARACTER_ERR
exception is raised, and if it does not match the NCName
production in Namespaces in XML, a NAMESPACE_ERR
exception is raised.
implementation
.
createDocument
(
namespace, qualifiedName,
doctype )Returns a new Document
,
with a new root Element
whose
localName
is qualifiedName and whose namespaceURI
is namespace (unless qualifiedName is the
empty string), and with doctype, if it is
given, as its DocumentType
.
This method raises the same exceptions as the createElementNS
method,
when called with the same arguments. If doctype
comes from another Document
, a
WRONG_DOCUMENT_ERR
exception is raised.
implementation
.
createHTMLDocument
(
title )Returns a new Document
,
with a basic DOM already constructed with an appropriate
title
element.
The createDocumentType(qualifiedName,
publicId, systemId)
method must run the following
steps:
If qualifiedName does not match the
Name
production in
XML, raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
If qualifiedName does not match the
NCName
production in Namespaces in XML, raise a NAMESPACE_ERR
exception and terminate these steps.
Return a new DocumentType
, with qualifiedName as its name, publicId
as its public ID, and systemId as its system ID, and with its ownerDocument
set to null.
No check is performed that the publicId matches the PublicChar
production in XML or that the systemId does not
contain both a quotation mark (") and an apostrophe (').
The createDocument(namespace,
qualifiedName, doctype)
method must run the following
steps:
Let document be a new Document
node.
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
raised an exception, re-raise the same exception and terminate
these steps.
If doctype is not null, run the following substeps:
If the doctype's ownerDocument
is not null,
raise a WRONG_DOCUMENT_ERR
exception and terminate the overall set of steps.
Set the doctype's ownerDocument
to document.
Append doctype to document.
If element is not null, append element to document.
Return document.
The createHTMLDocument(title)
method, when invoked, must run the following steps:
Let doc be a newly created Document
object.
Mark doc as being an HTML document.
Create a new DocumentType
, with "html
" as its name and with its ownerDocument
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, and set its
data
attribute to the string
given by the method's argument (which could be the empty string).
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.
Element
interface Element : Node { readonly attribute DOMString namespaceURI; readonly attribute DOMString prefix; readonly attribute DOMString localName; readonly attribute DOMString tagName; readonly attribute Attr[] attributes; DOMString? getAttribute(DOMString qualifiedName); DOMString? getAttributeNS(DOMString namespace, DOMString localName); void setAttribute(DOMString qualifiedName, DOMString value); void setAttributeNS(DOMString namespace, DOMString qualifiedName, DOMString value); void removeAttribute(DOMString qualifiedName); void removeAttributeNS(DOMString namespace, DOMString localName); boolean hasAttribute(DOMString qualifiedName); boolean hasAttributeNS(DOMString namespace, DOMString localName); readonly attribute HTMLCollection children; NodeList getElementsByTagName(DOMString qualifiedName); NodeList getElementsByTagNameNS(DOMString namespace, DOMString localName); NodeList getElementsByClassName(DOMString classNames); };
Element
nodes have an
associated namespace, namespace prefix, local name, and qualified name.
When an Element
node is
created its local name is always given. Unless
explicitly given when an Element
node is created, its namespace and namespace prefix are null
and its qualified name is its namespace prefix, followed
by a ":
" (U+003A), followed by its local name, if its namespace prefix is not
null, or otherwise qualified name is just its
local name.
Element
nodes also have an
associated collection of Attr
objects, often called attributes.
Element
nodes can have a
unique identifier
(ID) and classes associated with them.
I think rather than leaving this up to markup specifications we should just state that id="" sets the ID and class="" sets the classes. We can then also define Element.id, Element.className, and Element.classList here. It would simplify a lot of stuff.
Specifications may define base URL change steps.
When an Element
node is
affected by a base URL
change, the user agent must run the base URL change steps, as defined in
other applicable
specifications.
The namespaceURI
attribute must return the context
node's namespace.
The prefix
attribute must
return the context node's namespace prefix.
The localName
attribute must
return the context node's local name.
The tagName
attribute must
return the context node's qualified name, converted to uppercase if the
context node is in the HTML namespace and its ownerDocument
is an HTML document.
The attributes
attribute
must return a read only array of the context node's associated Attr
objects.
The getAttribute(name)
method must run these steps:
If the context node is in the
HTML namespace and its ownerDocument
is an HTML document, let name be
converted to lowercase.
Return the value of the first Attr
in the context
node's attributes
whose qualified name is name, if the Attr
is
present, or null otherwise.
The getAttributeNS(namespace, localName)
method must return the value of the Attr
in the context
node's attributes
whose namespace is namespace and local name is localName, if the Attr
is
present, or null otherwise.
The setAttribute(qualifiedName, value)
method must run these steps:
If qualifiedName does not match the
Name
production in
XML, raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
If the context node is in the
HTML namespace and its ownerDocument
is an HTML document, let qualifiedName be converted to lowercase.
If qualifiedName starts with "xmlns
", raise a NAMESPACE_ERR
and
terminate these steps.
If the node does not have an Attr
object whose name is qualifiedName, create an Attr
object, whose local
name is qualifiedName and value is
value. Append this object to the context node's attributes
, as its last
item.
Otherwise, set the value of the first Attr
object in the context node's attributes
whose qualified name is qualifiedName, to value.
The setAttributeNS(namespace, qualifiedName, value)
method must run these steps:
If qualifiedName does not match the
Name
production in
XML, raise an INVALID_CHARACTER_ERR
exception and terminate these steps.
If qualifiedName does not match the
QName
production in Namespaces in XML, raise a NAMESPACE_ERR
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 an empty string, raise a NAMESPACE_ERR
exception and terminate these steps.
If prefix is "xml
" and
namespace is not the XML namespace, raise a NAMESPACE_ERR
exception and terminate these steps.
If qualifiedName or prefix is "xmlns
" and namespace is not the XMLNS
namespace, raise a NAMESPACE_ERR
exception and terminate these steps.
If namespace is the XMLNS namespace and neither qualifiedName nor prefix is
"xmlns
", raise a NAMESPACE_ERR
exception and terminate these steps.
If the node does not have an Attr
object whose namespace is namespace and local name is localName, create an Attr
object, whose namespace is namespace, namespace prefix is prefix, local name is localName, and value is value. Append
this object to the context node's
attributes
, as its last
item.
Otherwise, set the value of the Attr
object in the context node's attributes
whose namespace is namespace, and local name is localName, to value, and set its
namespace prefix to prefix.
The removeAttribute(qualifiedName)
method must remove the first
Attr
object in the context node's attributes
whose qualified name is qualifiedName.
The removeAttributeNS(namespace, localName)
method must remove the Attr
object
in the context node's attributes
whose namespace is namespace and local name is localName
The hasAttribute(qualifiedName)
method must run these
steps:
If the context node is in the
HTML namespace and its ownerDocument
is an HTML document, let qualifiedName be converted to lowercase.
Return true if context node's
attributes
contains an
Attr
whose qualified name is qualifiedName, or false otherwise.
The hasAttributeNS(namespace, localName)
method must return true if context
node's attributes
contains an
Attr
whose namespace is namespace and local name is localName, or false otherwise.
The children
attribute must
return an HTMLCollection
collection, rooted at the context node, whose filter matches only
Element
nodes whose
parentNode
is the context node.
The getElementsByTagName(qualifiedName)
method on the Element
interface
must return a live NodeList
with the nodes that the
getElementsByTagName
method would return when called on the context node's ownerDocument
and passed the
same argument, excluding any elements that are not descendants of
the context node on which the method
was invoked.
When invoked with the same argument the same NodeList
object may be returned as returned
by an earlier call.
The getElementsByTagNameNS(namespace,
localName)
method on the
Element
interface must return a
live NodeList
with the nodes that the
getElementsByTagNameNS
method would return when called on the context node's ownerDocument
and passed the
same arguments, excluding any elements that are not descendants of
the context node on which the method
was invoked.
When invoked with the same argument the same NodeList
object may be returned as returned
by an earlier call.
The getElementsByClassName(classNames)
method on the Element
interface
must return a live NodeList
with the nodes that the
getElementsByClassName
method would return when called on the context node's ownerDocument
and passed the
same argument, excluding any elements that are not descendants of
the context node on which the method
was invoked.
When invoked with the same argument the same NodeList
object may be returned as returned
by an earlier call.
Attr
interface Attr { readonly attribute DOMString? namespaceURI; readonly attribute DOMString? prefix; readonly attribute DOMString localName; readonly attribute DOMString name; attribute DOMString value; };
Just like Element
nodes,
Attr
objects have an associated
namespace, namespace prefix, local
name, and qualified name.
When an Attr
object is created
its local name is always given. Unless
explicitly given when an Attr
object is created, its namespace and namespace prefix are null and
its qualified name is its namespace prefix, followed by a
":
" (U+003A), followed by its local
name, if its namespace prefix is not null,
or otherwise qualified name is just its
local name.
Attr
objects also have an
associated value, which is always given when an
Attr
object is created.
The namespaceURI
attribute
must return the namespace.
The prefix
attribute must return
the namespace prefix.
The localName
attribute must
return the local name.
The name
attribute must return the
qualified name.
The value
attribute must return the
value.
Setting the value
attribute must set value to the
given value.
DocumentType
interface DocumentType : Node { readonly attribute DOMString name; readonly attribute DOMString publicId; readonly attribute DOMString systemId; };
DocumentType
nodes have
an associated name, public
ID, and system ID.
When a DocumentType
node is created name is always given. Unless explicitly
given when a DocumentType
node is created, its public ID and system
ID are the empty string.
The name
attribute must
return the context node's name.
The publicId
attribute
must return the context node's public
ID.
The systemId
attribute
must return the context node's system
ID.
ProcessingInstruction
interface ProcessingInstruction : Node { readonly attribute DOMString target; attribute DOMString data; };
ProcessingInstruction
nodes
have an associated target and data. When a ProcessingInstruction
node is
created both are given.
The target
attribute must return the context
node's target.
The data
attribute
must return the context node's data, and on
setting, set the context node's
data to the
new value.
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); };
The data
attribute must
return the data of the node, and on setting, must change the node's
data to the new value.
The length
attribute must
return the number of UTF-16 code units represented by the node's
data.
The substringData(offset, count)
method
must run these steps:
If offset is negative or is greater than the
context node's length
, or if count is negative, raise an INDEX_SIZE_ERR
exception and terminate these steps.
If offset+count is greater than the context node's length
, return a
DOMString
whose value is the UTF-16 code units from the offsetth UTF-16 code unit to the end of data.
Return a DOMString
whose value is the UTF-16 code
units from the offsetth UTF-16 code unit to the
offset+countth UTF-16 code unit in data.
The appendData(data)
method must append data to the context node's
data.
The insertData(offset, data)
method must
run these steps:
If offset is greater than the context node's length
, raise an
INDEX_SIZE_ERR
exception and terminate these steps.
Insert data into the context node's data after offset UTF-16 code units.
The deleteData(offset, count)
method
must run these steps:
If offset is greater than the context node's length
, raise an
INDEX_SIZE_ERR
exception and terminate these steps.
If offset+count is
greater than the context node's
length
let count be length
-offset.
Starting from offset UTF-16 code units remove count UTF-16 code units from the context node's data.
The replaceData(offset, count, data)
method must act as if the deleteData()
method is
invoked with offset and count as arguments followed by the insertData()
method with
offset and data as
arguments and re-raise any exceptions these methods might have
raised.
Text
interface Text : CharacterData { Text splitText(unsigned long offset); readonly attribute DOMString wholeText; Text replaceWholeText(DOMString data); };
splitText
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 node, in tree order.
The replaceWholeText(data)
method must run these steps:
Remove the contiguous
Text
nodes of the context
node.
If data is not the empty string, insert a
new Text
node whose data
is data at the place of the removed nodes, return the new
Text
node, and then terminate
these steps.
Return null.
Can we remove replaceWholeText() in favor of making wholeText no longer readonly? Do we even need this wholeText business?
Comment
interface Comment : CharacterData { };
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; };
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 length
attribute must
return the number of nodes represented by the
collection.
NodeList
s are enumerable.
Explain? for ...
in
HTMLCollection
The HTMLCollection
interface represents a generic collection of elements.
This interface is called HTMLCollection
for historical reasons.
The various getters on this interface return object
for interfaces that inherit from it, which return other objects for
historical reasons.
interface HTMLCollection { readonly attribute unsigned long length; caller getter Element item(unsigned long index); caller 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.
Returns null if index is out of range.
namedItem
(name)Returns the first item with ID or name name from the collection.
Returns null if no element with that ID or name could be found.
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 node in the
collection that matches the following
requirements:
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
Only HTMLPropertiesCollection.names, DataTranser.types, Clipboard.types, and Document.styleSheetSets seem to use this API. Should they use something like DOMString[] instead if Web IDL introduces that?
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.
Returns null if index is out of range.
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
length
−1, unless the
length
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.
Returns null if index is out of range.
contains
(token)Returns true if the token is present; false otherwise.
Throws a SYNTAX_ERR
exception if
token is empty.
Throws an INVALID_CHARACTER_ERR
exception if token contains any spaces.
add
(token)Adds token, unless it is already present.
Throws a SYNTAX_ERR
exception if
token is empty.
Throws an INVALID_CHARACTER_ERR
exception if token contains any spaces.
remove
(token)Removes token if it is present.
Throws a SYNTAX_ERR
exception if
token is empty.
Throws an INVALID_CHARACTER_ERR
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 SYNTAX_ERR
exception if
token is empty.
Throws an INVALID_CHARACTER_ERR
exception if token contains any spaces.
The length
attribute must
return the number of tokens that result from splitting the underlying string on
spaces. This is the length.
The object's supported property indices are the numbers in the range zero to length−1, unless the length is zero, in which case there are no supported property indices.
The item(index)
method must split
the underlying string on spaces, preserving the order of the
tokens as found in the underlying string, and then return the
indexth item in this list. If index is equal to or greater than the number of tokens,
then the method must return null.
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 the following
algorithm:
SYNTAX_ERR
exception and
stop the algorithm.INVALID_CHARACTER_ERR
exception and stop the algorithm.The add(token)
method must run the following
algorithm:
SYNTAX_ERR
exception and
stop the algorithm.INVALID_CHARACTER_ERR
exception and stop the algorithm.DOMTokenList
object's
underlying string then stop the algorithm.DOMTokenList
object's underlying string
is not the empty string and the last character of that string is
not a space character, then append a
U+0020 SPACE character to the end of that string.DOMTokenList
object's
underlying string.The remove(token)
method must run the following
algorithm:
SYNTAX_ERR
exception and
stop the algorithm.INVALID_CHARACTER_ERR
exception and stop the algorithm.The toggle(token)
method must run the following
algorithm:
SYNTAX_ERR
exception and
stop the algorithm.INVALID_CHARACTER_ERR
exception and stop the algorithm.DOMTokenList
object's
underlying string then remove the given token from the underlying string and stop the
algorithm, returning false.DOMTokenList
object's underlying string
is not the empty string and the last character of that string is
not a space character, then append a
U+0020 SPACE character to the end of that string.DOMTokenList
object's
underlying string.Objects implementing the DOMTokenList
interface must stringify to the object's
underlying string representation.
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.
DOMString
and DOMTimeStamp
originally defined
in DOM Level 3 Core are now defined in Web IDL.
The remainder of interfaces and interface members listed in this section are part of DOM Level 3 Core. Implementations conforming to this specification will however not support them.
Interfaces:
CDATASection
DOMConfiguration
DOMError
DOMErrorHandler
DOMImplementationList
DOMImplementationSource
DOMLocator
DOMObject
DOMUserData
Entity
EntityReference
NamedNodeMap
NameList
Notation
TypeInfo
UserDataHandler
Interface members:
Node
hasAttributes()
attributes
namespaceURI
prefix
localName
normalize()
isSupported
getFeature()
getUserData()
setUserData()
Document
createCDATASection()
createAttribute()
createAttributeNS()
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
Thanks to Dethe Elza, Jonas Sicking, and Henri Sivonen for their useful comments.
Special thanks to Sam Sneddon, Ms2ger, and Simon Pieters for editing the initial 80% 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]