Element
interface represents an element in an HTML or XML
document. Elements may have attributes associated with them; since the
Element
interface inherits from Node
, the
generic Node
interface attribute attributes
may
be used to retrieve the set of all attributes for an element. There are
methods on the Element
interface to retrieve either an
Attr
object by name or an attribute value by name. In XML,
where an attribute value may contain entity references, an
Attr
object should be retrieved to examine the possibly
fairly complex sub-tree representing the attribute value. On the other
hand, in HTML, where all attributes have simple string values, methods to
directly access an attribute value can safely be used as a convenience.
Note: In DOM Level 2, the method normalize
is
inherited from the Node
interface where it was moved.
See also the Document Object Model (DOM) Level 3 Core Specification.
Attr
.CDATASection
.Comment
.DocumentFragment
.Document
.DocumentType
.Element
.Entity
.EntityReference
.Notation
.ProcessingInstruction
.Text
node.newChild
to the end of the list of children
of this node. If the newChild
is already in the tree, it
is first removed.parentNode
is null
) and no user data. User
data associated to the imported node is not carried over. However, if
any UserDataHandlers
has been specified along with the
associated data these handlers will be called with the appropriate
parameters before this method returns.
Element
copies all attributes and their
values, including those generated by the XML processor to represent
defaulted attributes, but this method does not copy any children it
contains unless it is a deep clone. This includes text contained in
an the Element
since the text is contained in a child
Text
node. Cloning an Attr
directly, as
opposed to be cloned as part of an Element
cloning
operation, returns a specified attribute (specified
is
true
). Cloning an Attr
always clones its
children, since they represent its value, no matter whether this is a
deep clone or not. Cloning an EntityReference
automatically constructs its subtree if a corresponding
Entity
is available, no matter whether this is a deep
clone or not. Cloning any other type of node simply returns a copy of
this node.
EntityReference
clone are readonly
. In addition, clones of unspecified Attr
nodes are
specified. And, cloning Document
,
DocumentType
, Entity
, and
Notation
nodes is implementation dependent.getAttributeNodeNS
method.Attr
node by local name and namespace URI.
null
as the
namespaceURI
parameter for methods if they wish to have
no namespace.null
as the
namespaceURI
parameter for methods if they wish to have
no namespace.NamedNodeMap
containing the attributes of this node (if
it is an Element
) or null
otherwise.null
if the
implementation wasn't able to obtain an absolute URI. This value is
computed as described in . However, when the Document
supports the feature "HTML" [DOM Level 2 HTML]
, the base URI is computed using first the value of the href
attribute of the HTML BASE element if any, and the value of the
documentURI
attribute from the Document
interface otherwise.NodeList
that contains all children of this node. If
there are no children, this is a NodeList
containing no
nodes.NodeList
of all descendant Elements
with a given tag name, in document order.NodeList
of all the descendant
Elements
with a given local name and namespace URI in
document order.Node
interface.null
.null
.ELEMENT_NODE
and
ATTRIBUTE_NODE
and nodes created with a DOM Level 1
method, such as Document.createElement()
, this is always
null
.null
if it is
unspecified (see ).
ELEMENT_NODE
and
ATTRIBUTE_NODE
and nodes created with a DOM Level 1
method, such as Document.createElement()
, this is always
null
.
Note: Per the Namespaces in XML Specification [XML Namespaces] an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace.
null
.null
, setting it has no effect,
including if the node is read-only.Document
object associated with this node. This is
also the Document
object used to create new nodes. When
this node is a Document
or a DocumentType
which is not used with any Document
yet, this is
null
.Attr
,
Document
, DocumentFragment
,
Entity
, and Notation
may have a parent.
However, if a node has just been created and not yet added to the
tree, or if it has been removed from the tree, this is
null
.null
if it is
unspecified. When it is defined to be null
, setting it
has no effect, including if the node is read-only.
nodeName
attribute, which holds the qualified name, as
well as the tagName
and name
attributes of
the Element
and Attr
interfaces, when
applicable.
null
makes it unspecified,
setting it to an empty string is implementation dependent.
namespaceURI
and localName
do not change.
ELEMENT_NODE
and
ATTRIBUTE_NODE
and nodes created with a DOM Level 1
method, such as createElement
from the
Document
interface, this is always null
.null
.Node.localName
is different
from null
, this attribute is a qualified name. For
example, in:
<elementExample id="demo"> ... </elementExample> ,
tagName
has the value
"elementExample"
. Note that this is case-preserving in
XML, as are all of the operations of the DOM. The HTML DOM returns
the tagName
of an HTML element in the canonical
uppercase form, regardless of the case in the source HTML document.null
, setting it
has no effect. On setting, any possible children this node may have
are removed and, if it the new string is not empty or
null
, replaced by a single Text
node
containing the string this attribute is set to.
Text.isElementContentWhitespace
). Similarly, on setting,
no parsing is performed either, the input string is taken as pure
textual content.
Node type | Content |
---|---|
ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the textContent
attribute value of every child node, excluding COMMENT_NODE and
PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
node has no children. |
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | nodeValue |
DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null |
setUserData
with the same key.true
when an attribute with a given name is
specified on this element or has a default value, false
otherwise.true
when an attribute with a given local name and
namespace URI is specified on this element or has a default value,
false
otherwise.
null
as the
namespaceURI
parameter for methods if they wish to have
no namespace.newChild
before the existing child node
refChild
. If refChild
is null
,
insert newChild
at the end of the list of children.
newChild
is a DocumentFragment
object,
all of its children are inserted, in the same order, before
refChild
. If the newChild
is already in the
tree, it is first removed.
Note: Inserting a node before itself is implementation dependent.
namespaceURI
is the
default namespace or not.Node.isSameNode()
. All nodes that are the
same will also be equal, though the reverse may not be true.
nodeName
, localName
,
namespaceURI
, prefix
, nodeValue
. This is: they are both null
, or they have the same
length and are character for character identical.
attributes
NamedNodeMaps
are equal. This
is: they are both null
, or they have the same length and
for each node that exists in one map there is a node that exists in
the other map and is equal, although not necessarily at the same
index.
childNodes
NodeLists
are equal.
This is: they are both null
, or they have the same
length and contain equal nodes at the same index. Note that
normalization can affect equality; to avoid this, nodes should be
normalized before being compared.
DocumentType
nodes to be equal, the following
conditions must also be satisfied:
publicId
, systemId
,
internalSubset
.
entities
NamedNodeMaps
are equal.
notations
NamedNodeMaps
are equal.
ownerDocument
, baseURI
, and
parentNode
attributes, the specified
attribute for Attr
nodes, the schemaTypeInfo
attribute for Attr
and Element
nodes, the
Text.isElementContentWhitespace
attribute for
Text
nodes, as well as any user data or event listeners
registered on the nodes.
Note: As a general rule, anything not mentioned in the description above is not significant in consideration of equality checking. Note that future versions of this specification may take into account more attributes and implementations conform to this specification are expected to be updated accordingly.
Node
references returned by the implementation reference
the same object. When two Node
references are references
to the same object, even if through a proxy, the references may be
used completely interchangeably, such that all attributes have the
same values and calling the same DOM method on either reference
always has exactly the same effect.Text
nodes in the full depth of the sub-tree
underneath this Node
, including attribute nodes, into a
"normal" form where only structure (e.g., elements, comments,
processing instructions, CDATA sections, and entity references)
separates Text
nodes, i.e., there are neither adjacent
Text
nodes nor empty Text
nodes. This can
be used to ensure that the DOM view of a document is the same as if
it were saved and re-loaded, and is useful when operations (such as
XPointer [XPointer]
lookups) that depend on a particular document tree structure are to
be used. If the parameter "normalize-characters" of the
DOMConfiguration
object attached to the
Node.ownerDocument
is true
, this method
will also fully normalize the characters of the Text
nodes.
Note: In cases where the document contains
CDATASections
, the normalize operation alone may not be
sufficient, since XPointers do not differentiate between
Text
nodes and CDATASection
nodes.
Document.normalizeDocument()
to guarantee this
information is up-to-date.
removeAttributeNS
method.Attr
node is defined in the DTD, a new node
immediately appears with the default value as well as the
corresponding namespace URI, local name, and prefix when applicable.
The implementation may handle default values from other schemas
similarly but applications should use
Document.normalizeDocument()
to guarantee this
information is up-to-date.Document.normalizeDocument()
to guarantee this
information is up-to-date.
null
as the
namespaceURI
parameter for methods if they wish to have
no namespace.oldChild
from the list
of children, and returns it.oldChild
with newChild
in the list of children, and returns the oldChild
node.
newChild
is a DocumentFragment
object,
oldChild
is replaced by all of the
DocumentFragment
children, which are inserted in the
same order. If the newChild
is already in the tree, it
is first removed.
Note: Replacing a node with itself is implementation dependent.
Attr
node plus any
Text
and EntityReference
nodes, build the
appropriate subtree, and use setAttributeNode
to assign
it as the value of an attribute.
setAttributeNS
method.nodeName
) is already present in the element, it is
replaced by the new one. Replacing an attribute node by itself has no
effect.
setAttributeNodeNS
method.null
as the
namespaceURI
parameter for methods if they wish to have
no namespace.qualifiedName
, and
its value is changed to be the value
parameter. This
value is a simple string; it is not parsed as it is being set. So any
markup (such as syntax to be recognized as an entity reference) is
treated as literal text, and needs to be appropriately escaped by the
implementation when it is written out. In order to assign an
attribute value that contains entity references, the user must create
an Attr
node plus any Text
and
EntityReference
nodes, build the appropriate subtree,
and use setAttributeNodeNS
or
setAttributeNode
to assign it as the value of an
attribute.
null
as the
namespaceURI
parameter for methods if they wish to have
no namespace.isId
is true
, this method
declares the specified attribute to be a user-determined ID attribute
. This affects the value of Attr.isId
and the behavior
of Document.getElementById
, but does not change any
schema that may be in use, in particular this does not affect the
Attr.schemaTypeInfo
of the specified Attr
node. Use the value false
for the parameter
isId
to undeclare an attribute for being a
user-determined ID attribute.
setIdAttributeNS
method.isId
is true
, this method
declares the specified attribute to be a user-determined ID attribute
. This affects the value of Attr.isId
and the behavior
of Document.getElementById
, but does not change any
schema that may be in use, in particular this does not affect the
Attr.schemaTypeInfo
of the specified Attr
node. Use the value false
for the parameter
isId
to undeclare an attribute for being a
user-determined ID attribute.isId
is true
, this method
declares the specified attribute to be a user-determined ID attribute
. This affects the value of Attr.isId
and the behavior
of Document.getElementById
, but does not change any
schema that may be in use, in particular this does not affect the
Attr.schemaTypeInfo
of the specified Attr
node. Use the value false
for the parameter
isId
to undeclare an attribute for being a
user-determined ID attribute.null
, setting it has no effect,
including if the node is read-only.null
if it is
unspecified. When it is defined to be null
, setting it
has no effect, including if the node is read-only.
nodeName
attribute, which holds the qualified name, as
well as the tagName
and name
attributes of
the Element
and Attr
interfaces, when
applicable.
null
makes it unspecified,
setting it to an empty string is implementation dependent.
namespaceURI
and localName
do not change.
ELEMENT_NODE
and
ATTRIBUTE_NODE
and nodes created with a DOM Level 1
method, such as createElement
from the
Document
interface, this is always null
.null
, setting it
has no effect. On setting, any possible children this node may have
are removed and, if it the new string is not empty or
null
, replaced by a single Text
node
containing the string this attribute is set to.
Text.isElementContentWhitespace
). Similarly, on setting,
no parsing is performed either, the input string is taken as pure
textual content.
Node type | Content |
---|---|
ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the textContent
attribute value of every child node, excluding COMMENT_NODE and
PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
node has no children. |
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | nodeValue |
DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null |
getUserData
with the
same key.