HTML DOM Level 2 Reference: Element

Represents an element in an HTML or XML document.

Constructors

Constructor IE Mozilla Netscape Opera Safari Netscapte
Element Constructor
Represents an element in an HTML or XML document.

Constructor	IE	Mozilla	Netscape	Opera	Safari	Netscapte
Element Constructor Represents an element in an HTML or XML document.

Properties

Property IE Mozilla Netscape Opera Safari Netscapte
tagName
The tag name for this element
5.0+ 1.0+ 6.0+ 8.0+ 1.3+ no

Property	IE	Mozilla	Netscape	Opera	Safari	Netscapte
tagName The tag name for this element	5.0+	1.0+	6.0+	8.0+	1.3+	no

Methods

Method IE Mozilla Netscape Opera Safari Netscapte
getAttribute
Gets an attribute value by name.
5.0+ 1.0+ 6.0+ 7.0+ 1.0+ no
IE: Incorrectly returns the value "object" on the "style" attribute.
Opera: Returns internal style information on the "style" attribute.
getAttributeNode
Gets an attribute node by name
6.0+ 1.0+ 6.0+ 7.0+ 1.0+ no

getAttributeNodeNS
Gets an attribute node by local name and namespace URI.
no 1.0+ 6.0+ 8.0+ no no

getAttributeNS
Gets an attribute value by local name and namespace URI
no 1.0+ 6.0+ 8.0+ no no

getElementsByTagName
Returns a NodeList array of all Element nodes descending from the specified Element.
5.0+ 1.0+ 6.0+ 7.0+ 1.0+ no
IE: Does not work in IE 5.0 on Windows.
getElementsByTagNameNS
Gets a list of all descendent elements by local tag name and namespace URI
no 1.0+ 6.0+ 8.0+ no no

hasAttribute
Determines if the given attribute exists on this element.

hasAttributeNS
Determines if the given attribute local name and namespace URI exists on this element
no 1.0+ 6.0+ 8.0+ 1.3+ no

removeAttribute
Removes an attribute by name
4.0+ 1.0+ 6.0+ 8.0+ 1.0+ no

removeAttributeNode
Removes the specified attribute node
6.0+ 1.0+ 6.0+ 8.0+ 1.0+ no
IE: Minimal support in IE 6.0 (Windows) and IE 5 (Mac).
removeAttributeNS
Removes an attribute by local name and namespace URI
no 1.0+ 6.0+ 8.0+ no no

setAttribute
Adds a new attribute.
5.0+ 1.0+ 6.0+ 8.0+ 1.0+ no
IE: IE removes event attributes when you try to set style attributes.
setAttributeNode
Adds the given attribute node
4.0+ 1.0+ 6.0+ 8.0+ 1.0+ no
Safari: Safari will create the attribute, but you will have to use nodeValue to set its value.
setAttributeNodeNS
Sets an attribute value with the given node's name and namespace URI.
no 1.0+ 6.0+ 8.0+ no no

setAttributeNS
Adds a new attribute with a namespace URI
no 1.0+ 6.0+ 8.0+ no no

Method	IE	Mozilla	Netscape	Opera	Safari	Netscapte
getAttribute Gets an attribute value by name.	5.0+	1.0+	6.0+	7.0+	1.0+	no
IE: Incorrectly returns the value "object" on the "style" attribute. Opera: Returns internal style information on the "style" attribute.
getAttributeNode Gets an attribute node by name	6.0+	1.0+	6.0+	7.0+	1.0+	no

getAttributeNodeNS Gets an attribute node by local name and namespace URI.	no	1.0+	6.0+	8.0+	no	no

getAttributeNS Gets an attribute value by local name and namespace URI	no	1.0+	6.0+	8.0+	no	no

getElementsByTagName Returns a NodeList array of all Element nodes descending from the specified Element.	5.0+	1.0+	6.0+	7.0+	1.0+	no
IE: Does not work in IE 5.0 on Windows.
getElementsByTagNameNS Gets a list of all descendent elements by local tag name and namespace URI	no	1.0+	6.0+	8.0+	no	no

hasAttribute Determines if the given attribute exists on this element.

hasAttributeNS Determines if the given attribute local name and namespace URI exists on this element	no	1.0+	6.0+	8.0+	1.3+	no

removeAttribute Removes an attribute by name	4.0+	1.0+	6.0+	8.0+	1.0+	no

removeAttributeNode Removes the specified attribute node	6.0+	1.0+	6.0+	8.0+	1.0+	no
IE: Minimal support in IE 6.0 (Windows) and IE 5 (Mac).
removeAttributeNS Removes an attribute by local name and namespace URI	no	1.0+	6.0+	8.0+	no	no

setAttribute Adds a new attribute.	5.0+	1.0+	6.0+	8.0+	1.0+	no
IE: IE removes event attributes when you try to set style attributes.
setAttributeNode Adds the given attribute node	4.0+	1.0+	6.0+	8.0+	1.0+	no
Safari: Safari will create the attribute, but you will have to use nodeValue to set its value.
setAttributeNodeNS Sets an attribute value with the given node's name and namespace URI.	no	1.0+	6.0+	8.0+	no	no

setAttributeNS Adds a new attribute with a namespace URI	no	1.0+	6.0+	8.0+	no	no

Remarks

One of the most critical objects within the DOM, the Element object represents an individual element within an XML or HTML document. Due to the capabilities of XML elements, this object provides several methods for handling attributes.

The attribute manipulation methods can be divided into three different groups: plain methods, node-oriented methods, and namespace-aware methods. The first category is the simplest, and permits both the attribute name and value to be supplied to the method, thus creating an Attr under the covers. The second category enables a user to create an Attr themselves, and merely to attach it to the Element object. The final category is similar to the first, except an extra argument can be supplied which allows you to create an attribute with an XML namespace.

Many of the capabilities of this object is inherited from Node, since they share many similarities. Therefore, this object exposes methods to get at all the available attributes (since it inherits the attributes property), individual attribute values, or individual Attr objects.

References

HTMLElement | Node

Availability

HTML DOM Level 2 | W3C

Constructor Detail

Element Element()

Represents an element in an HTML or XML document.

Visibility: internal

Property Detail

String tagName - read only

The tag name for this element

For examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/aboutnodes.html

Remarks

Identifies the name of an element in a source document, including any namespace prefix. For example, in the following XML content, tagName value of the outer element (the ]]> element) returns "example1", while the inner element has a tagName value of "test:example2", even though the element name itself, without the namespace prefix is simply "example2".:

]]>

Availability

HTML DOM Level 2 | W3C

Method Detail

getAttribute(String name) : static String

Gets an attribute value by name.

String name The name of the attribute to get the value for.

Using getAttribute

var node = document.getElementById('toolbar');
                    if (node.getAttribute('visible') == true) {
                    // Magic happens here
                    }

For more examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes2.html

Remarks

This method retrieves one of the element's attributes that has the supplied name, and returns its value. If no attribute by that name exists as a child of the given element, an empty string is returned.

Its important to note that a copy of the attribute's value is returned, rather than a reference to the actual value. This means that you cannot modify the attribute value using this method. You need to use another method (like getAttributeNode or getAttributeNodeNS) that returns the Attr object itself to make changes.

Availability

HTML DOM Level 2 | W3C

getAttributeNode(String name) : static Attr

Gets an attribute node by name

String name The name of the attribute to get the Attr node object for.

Using getAttributeNode

var attr = element.getAttributeNode("class");
                    if (! attr.specified) {
                    // This attribute is a default value
                    }

For more examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes2.html

Remarks

This method retrieves an attribute from an element, as an Attr object, rather than as a String. This is similar to the getAttribute method, except that method only returns the attribute's value. getAttributeNode lets you access a given attribute object without having to iterate over the attributes property.

Availability

HTML DOM Level 2 | W3C

getAttributeNodeNS(String namespaceURI, String localName) : static Attr

Gets an attribute node by local name and namespace URI.

String namespaceURI The namespace URI of the attribute node to get.
String localName Local name of the attribute node to get.

Using getAttributeNodeNS

var attr = element.getAttributeNodeNS("http://mozref.com/NS/test", "name");
                    if (! attr.specified) {
                    // This attribute is a default value
                    }

Remarks

Similar to getAttributeNode and to getAttributeNS, this method retrieves an attribute's Attr object from the current Element by specifying both the attribute's namespace URI and local name.

Supplying the namespaceURI parameter with a null value is functionally equivilant to calling getAttributeNode.

Availability

HTML DOM Level 2 | W3C

getAttributeNS(String namespaceURI, String localName) : static String

Gets an attribute value by local name and namespace URI

String namespaceURI The namespace URI of the attribute to get.
String localName The local name of the attribute to get.

Using getAttributeNS

/* Given the source XML:
                    
                    
                    
                    */
                    var value = element.getAttributeNS("http://mozref.com/NS/test", "name");

Remarks

Similar to getAttribute, this method retrieves one of the element's attributes. In this instance though, both the namespace URI and local name of the attribute can be used to select the appropriate attribute.

Supplying the namespaceURI parameter with a null value is functionally equivilant to calling getAttribute.

Availability

HTML DOM Level 2 | W3C

getElementsByTagName(String name) : static NodeList

Returns a NodeList array of all Element nodes descending from the specified Element.

String name Tag name of the element(s) to retrieve. (Use "*" as a wild card to return all tags.)

Using getElementsByTagName

var ctxt = document.getElementById("sidebar-div");
                    for ( var link in ctxt.getElementsByTagName("a") ) {
                    // Do something with this link
                    }

For additional examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/basics.html

Remarks

When trying to retrieve elements from the DOM, you do not often know the ID of the elements in question, but you know the type of element they are. Therefore, the Document object provides the getElementsByTagName method for searching the DOM and returning a list of elements matching the supplied tag name.

However, there may be many instances of that same XML element that are not relevant. Therefore, this same method is made available on all Element nodes, permitting you to search from the potentially much smaller subset of elements that are descendents of the current element.

Availability

HTML DOM Level 2 | W3C

getElementsByTagNameNS(String namespaceURI, String localName) : static NodeList

Gets a list of all descendent elements by local tag name and namespace URI

String namespaceURI Namespace URI of the elements to get. (Use "*" as a wild card.)
String localName The local name of the elements to get. (Use "*" as a wild card to return all tag names.)

Using getElementsByTagNameNS

var ctxt = document.getElementById("toolbar-menubar");
                    var menuitems = ctxt.getElementsByTagNameNS(
                    "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul",
                    "menuitem");
                    for ( var menuitem in menuitems ) {
                    // Do something with this menu item
                    }

Remarks

Similar to getElementsByTagName, this method retrieves an element's descendent Element objects that match the supplied namespace URI and local name.

Supplying the namespaceURI parameter with a null value is functionally equivilant to calling getElementsByTagName.

Availability

HTML DOM Level 2 | W3C

hasAttribute(String name) : Boolean

Determines if the given attribute exists on this element.

String name Name of the attribute to check.

Using hasAttribute

if (!element.hasAttribute("id")) {
                    element.setAttribute("id", "newvalue");
                    }

For more examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes3.html

Remarks

Use this method to verify that an attribute exists on an Element before retrieving that attribute.

Availability

HTML DOM Level 2HTML DOM Level 2 | W3C

hasAttributeNS(String namespaceURI, String localName) : Boolean

Determines if the given attribute local name and namespace URI exists on this element

String namespaceURI Namespace URI of the attribute to check.
String localName Local name of the attribute to check.

Using hasAttributeNS

/* Given the source XML:
                    
                    
                    
                    */
                    if (!element.hasAttributeNS("http://mozref.com/NS/test", "name")) {
                    element.setAttributeNS("http://mozref.com/NS/test", "name", "newvalue");
                    }

Remarks

Similar to hasAttribute, this method returns a boolean value indicating an attribute exists on the given element. In this instance, the hasAttributeNS method takes an extra parameter specifying the namespace URI for the attribute, enabling you to check for attributes that have a namespace associated with them.

Availability

HTML DOM Level 2 | W3C

removeAttribute(String name) : void

Removes an attribute by name

String name Name of the attribute to remove.

Using removeAttribute

if (element.hasAttribute("id")) {
                    element.removeAttribute("id");
                    }

For more examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes2.html

Remarks

Removes the specified attribute from the element. If the attribute has a defined default value, it will be set to that default value.

Throws

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only.

Availability

HTML DOM Level 2 | W3C

removeAttributeNode(Attr oldAttr) : static Attr

Removes the specified attribute node

Attr oldAttr Node to remove from the attribute.

For examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes2.html

Remarks

Removes an attribute from an element. If the attribute has a defined default value, the new attribute node value will immediately be set to that.

Throws

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only. Raises a NOT_FOUND_ERR error if oldAttr object is not an attribute of this element.

See Also

Attr | Element.removeAttribute

Availability

HTML DOM Level 2 | W3C

removeAttributeNS() : void

Removes an attribute by local name and namespace URI

Remarks

This method removes an attribute from an Element based on the attribute's local name and namespace URI. If this attribute has a default value, a new attribute with the default value will immediately replace it, with the same local name, namespace URI and namespace prefix as the original attribute.

Throws

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only.

Availability

HTML DOM Level 2 | W3C

setAttribute(String name, String value) : void

Adds a new attribute.

String name Name of the attribute to set.
String value String value of the attribute to set.

Using setAttribute

var node = document.getElementById('address-list');
                    document.setAttribute('ref', 'urn:root');
                    document.setAttribute('datasources', 'http://mozref.com/reference/objects.rdf');

For more examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes2.html

Remarks

Sets either a new attribute value or updates an existing attribute value. This method can only set values as text strings, not HTML. Entities will not be parsed. To assign values containing entities to an attribute, use setAttributeNode or setAttributeNodeNS.

Throws

Raises an INVALID_CHARACTER_ERR error if the supplied name contains an invalid character.

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only.

Availability

HTML DOM Level 2 | W3C

setAttributeNode(Attr newAttr) : static Attr

Adds the given attribute node

Attr newAttr Attr node of the attribute to set.

Using setAttributeNode

var attr = node1.getAttributeNode("class");
                    node1.removeAttribute("class");
                    node2.setAttributeNode(attr);

For more examples, see the quirksmode test page:

http://www.quirksmode.org/dom/tests/attributes3.html

Remarks

This method adds the specified Attr object as an attribute to the current element. You may specifiy actual DOM nodes instead of specifying separate arguments for the attribute name and value.

If the element already has the attribute, setAttribute will replace the node and return the old attribute node. Returns null, otherwise.

Throws

Raises a WRONG_DOCUMENT_ERR error if the supplied newAttr was created from a different document.

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only.

Raises an INUSE_ATTRIBUTE_ERR error if the supplied newAttr is already bound to another Element object.

See Also

Attr | Element.setAttribute

Availability

HTML DOM Level 2 | W3C

setAttributeNodeNS(Attr newAttr) : static Attr

Sets an attribute value with the given node's name and namespace URI.

Attr newAttr Attr node of the attribute to set, including the namespace information.

Remarks

Like it's non-namespace aware counterpart setAttributeNode, this method sets or replaces an attribute in an Element node by supplying the actual Attr node that is to be bound to the object. Unlike setAttributeNode, this method is aware of, and can set, the attribute using the localName and namespaceURI.

If an attribute already exists in this Element with the supplied attribute name properties, then it is replaced, and the old attribute is returned. Otherwise, null is returned.

Throws

Raises a WRONG_DOCUMENT_ERR error if the supplied newAttr was created from a different document.

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only.

Raises an INUSE_ATTRIBUTE_ERR error if the supplied newAttr is already bound to another Element object.

Availability

HTML DOM Level 2 | W3C

setAttributeNS(String namespaceURI, String qualifiedName, String value) : void

Adds a new attribute with a namespace URI

String namespaceURI Namespace URI of the attribute to set.
String qualifiedName Fully qualified name of the attribute to set.
String value String value of the attribute to set.

Using setAttributeNS

node.setAttributeNS(
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
                    "rdf:about",
                    "urn:root"
                    );

Remarks

This method, similar to the setAttribute method, sets a new attribute value. If the attribute already exists, it's value is set to the one supplied to this method. This version of the method however takes both a qualified name and namespace URI when setting the attribute. This permits the creation of attributes defined with namespaces.

Like setAttribute, this method accepts only plain string values, and as such cannot be used for defining entity references within strings. Any entity reference will be escaped prior to being set with the attribute. If you would like to assign values containing entities to an attribute, please see setAttributeNode or setAttributeNodeNS.

Throws

Raises an INVALID_CHARACTER_ERR error if the supplied name contains an invalid character.

Raises a NO_MODIFICATION_ALLOWED_ERR error if the node is read-only.

Raises a NAMESPACE_ERR error if the qualifiedName is invalid, if the qualifiedName contains a namespace prefix yet no namespaceURI is supplied, if the namespace prefix is "xml" or "xmlns" and has a namespaceURI that does not match the prefix.

Availability

HTML DOM Level 2 | W3C

String	namespaceURI	The namespace URI of the attribute node to get.
String	localName	Local name of the attribute node to get.

String	namespaceURI	The namespace URI of the attribute to get.
String	localName	The local name of the attribute to get.

String	namespaceURI	Namespace URI of the elements to get. (Use "*" as a wild card.)
String	localName	The local name of the elements to get. (Use "*" as a wild card to return all tag names.)

String	namespaceURI	Namespace URI of the attribute to check.
String	localName	Local name of the attribute to check.

String	name	Name of the attribute to set.
String	value	String value of the attribute to set.

String	namespaceURI	Namespace URI of the attribute to set.
String	qualifiedName	Fully qualified name of the attribute to set.
String	value	String value of the attribute to set.

Element : Node

Constructors

Properties

Methods

Remarks

References

Availability

Constructor Detail

Element Element()

Property Detail

String tagName - read only

Method Detail

getAttribute(String name) : static String

Using getAttribute

getAttributeNode(String name) : static Attr

Using getAttributeNode

getAttributeNodeNS(String namespaceURI, String localName) : static Attr

Using getAttributeNodeNS

getAttributeNS(String namespaceURI, String localName) : static String

Using getAttributeNS

getElementsByTagName(String name) : static NodeList

Using getElementsByTagName

getElementsByTagNameNS(String namespaceURI, String localName) : static NodeList

Using getElementsByTagNameNS

hasAttribute(String name) : Boolean

Using hasAttribute

hasAttributeNS(String namespaceURI, String localName) : Boolean

Using hasAttributeNS

removeAttribute(String name) : void

Using removeAttribute

removeAttributeNode(Attr oldAttr) : static Attr

removeAttributeNS() : void

setAttribute(String name, String value) : void

Using setAttribute

setAttributeNode(Attr newAttr) : static Attr

Using setAttributeNode

setAttributeNodeNS(Attr newAttr) : static Attr

setAttributeNS(String namespaceURI, String qualifiedName, String value) : void

Using setAttributeNS