DOM2 Reference
   [Back] [Go to standard]  [Glossary]  [Help]   
| Reference Search | Sitemap | XML Glossary |       ZVON | IDOOX

Element

Type of the interface: fundamental
Own properties:
attributes -  tagName
methods -  getAttribute, getAttributeNS, getAttributeNode, getAttributeNodeNS, getElementsByTagName, getElementsByTagNameNS, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNS, removeAttributeNode, setAttribute, setAttributeNS, setAttributeNode, setAttributeNodeNS
Inherited properties:
attributes -  attributes, childNodes, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling
methods -  appendChild, cloneNode, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild

Description:
Apart from text, Element nodes are the most common objects in every XML document.


 attribute:    Element.tagName      example  
readonly: yes
type: DOMString
description: The name of the element.
note: 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.

 attribute:    Element.attributes      (inherited from Node)   example  
readonly: yes
type: NamedNodeMap
description: A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.

 attribute:    Element.childNodes      (inherited from Node)   example  
readonly: yes
type: NodeList
description: A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes.

 attribute:    Element.firstChild      (inherited from Node)   example  
readonly: yes
type: Node
description: The first child of this node. If there is no such node, this returns null.

 attribute:    Element.lastChild      (inherited from Node)   example  
readonly: yes
type: Node
description: The last child of this node. If there is no such node, this returns null.

 attribute:    Element.localName      (inherited from Node)   example  
readonly: yes
type: DOMString
description: Returns the local part of the qualified name of this node.
note: For nodes of any type other than 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.

 attribute:    Element.namespaceURI      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The namespace URI of this node, or null if it is unspecified.
note:
  • For nodes of any type other than 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.
  • Per the Namespaces in XML Specification 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.

 attribute:    Element.nextSibling      (inherited from Node)   example  
readonly: yes
type: Node
description: The node immediately following this node. If there is no such node, this returns null.

 attribute:    Element.nodeName      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The name of this node, depending on its type.

 attribute:    Element.nodeType      (inherited from Node)   example  
readonly: yes
type: unsigned short
description: A code representing the type of the underlying object.

 attribute:    Element.nodeValue      (inherited from Node)   example  
readonly: no
type: DOMString
description: The value of this node, depending on its type.
note: When it is defined to be null, setting it has no effect.
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  This exception raises on setting when the node is readonly.
DOMException DOMSTRING_SIZE_ERR  -  This exception raises on retrieval when it would return more characters than fit in a DOMString variable on the implementation platform.

 attribute:    Element.ownerDocument      (inherited from Node)   example  
readonly: yes
type: Document
description: The 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.

 attribute:    Element.parentNode      (inherited from Node)   example  
readonly: yes
type: Node
description: The parent of this node. All nodes, except 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.

 attribute:    Element.prefix      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The namespace prefix of this node, or null if it is unspecified.
exceptions:
DOMException INVALID_CHARACTER_ERR  -  This exception is raised on setting if the specified prefix contains an illegal character.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  This exception is raised on setting if this node is readonly.
DOMException NAMESPACE_ERR  -  This exception is raised on setting if the specified prefix is malformed, if the namespaceURI of this node is null, if the specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace", if this node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualifiedName of this node is "xmlns".

 attribute:    Element.previousSibling      (inherited from Node)   example  
readonly: yes
type: Node
description: The node immediately preceding this node. If there is no such node, this returns null.


 method:    Element.getAttribute(name)      example  
description: Retrieves an attribute value by name.
parameters:
DOMString name  -  The name of the attribute to retrieve.
returns:
DOMString  -  The Attr value as a string, or the empty string if that attribute does not have a specified or default value.
exceptions:  none

 method:    Element.getAttributeNS(namespaceURI, localName)      example  
description: Retrieves an attribute value by local name and namespace URI.
parameters:
DOMString namespaceURI  -  The namespace URI of the attribute to retrieve.
DOMString localName  -  The local name of the attribute to retrieve.
returns:
DOMString  -  The Attr value as a string, or the empty string if that attribute does not have a specified or default value.
exceptions:  none

 method:    Element.getAttributeNode(name)      example  
description: Retrieves an attribute node by name.
parameters:
DOMString name  -  The name (nodeName) of the attribute to retrieve.
returns:
Attr  -  The Attr node with the specified name (nodeName) or null if there is no such attribute.
exceptions:  none

 method:    Element.getAttributeNodeNS(namespaceURI, localName)      example  
description: Retrieves an Attr node by local name and namespace URI.
parameters:
DOMString namespaceURI  -  The namespace URI of the attribute to retrieve.
DOMString localName  -  The local name of the attribute to retrieve.
returns:
Attr  -  The Attr node with the specified attribute local name and namespace URI or null if there is no such attribute.
exceptions:  none

 method:    Element.getElementsByTagName(name)      example  
description: Returns a NodeList containing all Elements with the given tag name in the same order as they appear in the source document.
parameters:
DOMString name  -  The name of the tag to match on. The special value "*" matches all tags.
returns:
NodeList  -  A list of matching Element nodes.
exceptions:  none

 method:    Element.getElementsByTagNameNS(namespaceURI, localName)      example  
description: Returns a NodeList containing all Elements of the given local name and namespace URI in the same order as they appear in the source document.
parameters:
DOMString namespaceURI  -  The namespace URI of the elements to match on. The special value "*" matches all namespaces.
DOMString localName  -  The local name of the elements to match on. The special value "*" matches all local names.
returns:
NodeList  -  A new NodeList object containing all the matched Elements.
exceptions:  none

 method:    Element.hasAttribute(name)      example  
description: Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.
parameters:
DOMString name  -  The name of the attribute to look for.
returns:
Boolean  -  true if an attribute with a given name is specified on this element or has a default value, false otherwise.
exceptions:  none

 method:    Element.hasAttributeNS(namespaceURI, localName)      example  
description: Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.
parameters:
DOMString namespaceURI  -  The namespace URI of the attribute to look for.
DOMString localName  -  The local name of the attribute to look for.
returns:
Boolean  -  true if an attribute with a given local name and namespace URI is specified or has a default value on this element, false otherwise.
exceptions:  none

 method:    Element.removeAttribute(name)      example  
description: Removes an attribute by name.
parameters:
DOMString name  -  The name of the attribute to remove.
returns:  nothing
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
note: If the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.

 method:    Element.removeAttributeNS(namespaceURI, localName)      example  
description: Removes an attribute by local name and namespace URI.
parameters:
DOMString namespaceURI  -  The namespace URI of the attribute to remove.
DOMString localName  -  The local name of the attribute to remove.
returns:  nothing
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
note: If the removed attribute has a default value it is immediately replaced. The replacing attribute has the same namespace URI and local name, as well as the original prefix.

 method:    Element.removeAttributeNode(oldAttr)      example  
description: Removes the specified attribute node.
parameters:
Attr oldAttr  -  The Attr node to remove from the attribute list.
returns:
Attr  -  The Attr node that was removed.
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
DOMException NOT_FOUND_ERR  -  Raised if oldAttr is not an attribute of the element.
note: If the removed Attr has a default value it is immediately replaced. The replacing attribute has the same namespace URI and local name, as well as the original prefix, when applicable.

 method:    Element.setAttribute(name, value)      example  
description: Adds a new attribute.
parameters:
DOMString name  -  The name of the attribute to create or alter.
DOMString value  -  Value to set in string form.
returns:  nothing
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified name contains an invalid character.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
note: If an attribute with that name is already present in the element, its value is changed to be that of 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 setAttributeNode to assign it as the value of an attribute.

 method:    Element.setAttributeNS(namespaceURI, qualifiedName, value)      example  
description: Adds a new attribute.
parameters:
DOMString namespaceURI  -  The namespace URI of the attribute to create or alter.
DOMString qualifiedName  -  The qualified name of the attribute to create or alter.
DOMString value  -  Value to set in string form.
returns:  nothing
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified qualified name contains an invalid character.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
DOMException NAMESPACE_ERR  -  Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", or if the qualifiedName is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".
note: If an attribute with the same local name and namespace URI is already present on the element, its prefix is changed to be the prefix part of the 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.

 method:    Element.setAttributeNode(newAttr)      example  
description: Adds a new attribute.
parameters:
Attr newAttr  -  The Attr node to add to the attribute list.
returns:
Attr  -  If the newAttr attribute replaces an existing attribute, the replaced Attr node is returned, otherwise null is returned.
exceptions:
DOMException WRONG_DOCUMENT_ERR  -  Raised if newAttr was created from a different document than the one that created the element.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
DOMException INUSE_ATTRIBUTE_ERR  -  Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
note: If an attribute with that name () is already present in the element, it is replaced by the new one.

 method:    Element.setAttributeNodeNS(newAttr)      example  
description: Adds a new attribute.
parameters:
Attr newAttr  -  The Attr node to add to the attribute list.
returns:
Attr  -  If the newAttr attribute replaces an existing attribute with the same local name and namespace URI, the replaced Attr node is returned, otherwise null is returned.
exceptions:
DOMException WRONG_DOCUMENT_ERR  -  Raised if newAttr was created from a different document than the one that created the element.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
DOMException INUSE_ATTRIBUTE_ERR  -  Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
note: If an attribute with that local name and that namespace URI is already present in the element, it is replaced by the new one.

 method:    Element.appendChild(newChild)      (inherited from Node)   example  
description: Adds the 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.
parameters:
Node newChild  -  The node to add. If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node.
returns:
Node  -  The node added.
exceptions:
DOMException HIERARCHY_REQUEST_ERR  -  Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors or this node itself.
DOMException WRONG_DOCUMENT_ERR  -  Raised if newChild was created from a different document than the one that created this node.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly or if the previous parent of the node being inserted is readonly.

 method:    Element.cloneNode(deep)      (inherited from Node)   example  
description: Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent (parentNode is null).
parameters:
Boolean deep  -  If true, recursively clone the subtree under the specified node; if false, clone only the node itself (and its attributes, if it is an Element).
returns:
Node  -  The duplicate node.
exceptions:  none
note:
  • Cloning an 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 text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning an Attribute directly, as opposed to be cloned as part of an Element cloning operation, returns a specified attribute (specified is true). Cloning any other type of node simply returns a copy of this node.
  • Note that cloning an immutable subtree results in a mutable copy, but the children of an EntityReference clone are readonly. In addition, clones of unspecified Attr nodes are specified. And, cloning Document, DocumentType, Entity, and Notation nodes is implementation dependent.

 method:    Element.hasAttributes()      (inherited from Node)   example  
description: Returns whether this node (if it is an element) has any attributes.
parameters:  none
returns:
Boolean  -  true if this node has any attributes, false otherwise.
exceptions:  none

 method:    Element.hasChildNodes()      (inherited from Node)   example  
description: Returns whether this node has any children.
parameters:  none
returns:
Boolean  -  true if this node has any children, false otherwise.
exceptions:  none

 method:    Element.insertBefore(newChild, refChild)      (inherited from Node)   example  
description: Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children.
parameters:
Node newChild  -  The node to insert.
Node refChild  -  The reference node, i.e., the node before which the new node must be inserted.
returns:
Node  -  The node being inserted.
exceptions:
DOMException HIERARCHY_REQUEST_ERR  -  Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors or this node itself.
DOMException WRONG_DOCUMENT_ERR  -  Raised if newChild was created from a different document than the one that created this node.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly or if the parent of the node being inserted is readonly.
DOMException NOT_FOUND_ERR  -  Raised if refChild is not a child of this node.
note: If 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.

 method:    Element.isSupported(feature, version)      (inherited from Node)   example  
description: Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.
parameters:
DOMString feature  -  The name of the feature to test. This is the same name which can be passed to the method hasFeature on DOMImplementation.
DOMString version  -  This is the version number of the feature to test. In Level 2, version 1, this is the string "2.0". If the version is not specified, supporting any version of the feature will cause the method to return true.
returns:
Boolean  -  Returns true if the specified feature is supported on this node, false otherwise.
exceptions:  none

 method:    Element.normalize()      (inherited from Node)   example  
description: Puts all 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.
parameters:  none
returns:  nothing
exceptions:  none
note:
  • 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 lookups) that depend on a particular document tree structure are to be used.
  • 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.

 method:    Element.removeChild(oldChild)      (inherited from Node)   example  
description: Removes the child node indicated by oldChild from the list of children, and returns it.
parameters:
Node oldChild  -  The node being removed.
returns:
Node  -  The node removed.
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
DOMException NOT_FOUND_ERR  -  Raised if oldChild is not a child of this node.

 method:    Element.replaceChild(newChild, oldChild)      (inherited from Node)   example  
description: Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
parameters:
Node newChild  -  The new node to put in the child list.
Node oldChild  -  The node being replaced in the list.
returns:
Node  -  The node replaced.
exceptions:
DOMException HIERARCHY_REQUEST_ERR  -  Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to put in is one of this node's ancestors or this node itself.
DOMException WRONG_DOCUMENT_ERR  -  Raised if newChild was created from a different document than the one that created this node.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node or the parent of the new node is readonly.
DOMException NOT_FOUND_ERR  -  Raised if oldChild is not a child of this node.
note: If 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.