[Back] [Go to standard]  [Glossary]  [Help]   

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