Element : Node
Return to: HTML DOM Level 2 index

Represents an element in an HTML or XML document.

Constructors

Constructor Action IE Mozilla Netscape Opera Safari
Element Constructor() : Element
Represents an element in an HTML or XML document.
 Show Details

Element() : Element

Represents an element in an HTML or XML document.

Returns
Element

Visibility
internal

Properties

Property Action IE Mozilla Netscape Opera Safari
tagName : String
The tag name for this element
 Show Details 5.0+ 1.0+ 6.0+ 8.0+ 1.3+

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

Functions

Method Action IE Mozilla Netscape Opera Safari
static getAttribute(String name) : String
Gets an attribute value by name.
 Show Details 5.0+ 1.0+ 6.0+ 7.0+ 1.0+
  • IE: Incorrectly returns the value "object" on the "style" attribute.
  • Opera: Returns internal style information on the "style" attribute.

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

Returns
String

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.

See Also

Element.getAttributeNode|Node.attributes

Availability

HTML DOM Level 2|W3C
static getAttributeNode(String name) : Attr
Gets an attribute node by name
 Show Details 6.0+ 1.0+ 6.0+ 7.0+ 1.0+

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

Returns
Attr

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.
See Also

Element.getAttribute|Element.getAttributeNodeNS|Node.attributes

Availability

HTML DOM Level 2|W3C
static getAttributeNodeNS(String namespaceURI, String localName) : Attr
Gets an attribute node by local name and namespace URI.
 Show Details no 1.0+ 6.0+ 8.0+ no

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

Returns
Attr

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.

See Also

Element.getAttributeNode|Element.getAttributeNS

Availability

HTML DOM Level 2|W3C
static getAttributeNS(String namespaceURI, String localName) : String
Gets an attribute value by local name and namespace URI
 Show Details no 1.0+ 6.0+ 8.0+ no

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

Returns
String

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.

See Also

Element.getAttribute|Element.getAttributeNodeNS

Availability

HTML DOM Level 2|W3C
static getElementsByTagName(String name) : NodeList
Returns a NodeList array of all Element nodes descending from the specified Element.
 Show Details 5.0+ 1.0+ 6.0+ 7.0+ 1.0+
  • IE: Does not work in IE 5.0 on Windows.

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

Returns
NodeList

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.

See Also

Document.getElementById|Document.getElementsByTagName|HTMLDocument.getElementsByName

Availability

HTML DOM Level 2|W3C
static getElementsByTagNameNS(String namespaceURI, String localName) : NodeList
Gets a list of all descendent elements by local tag name and namespace URI
 Show Details no 1.0+ 6.0+ 8.0+ no

Parameters
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.)

Returns
NodeList

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.

See Also

Document.getElementsByTagNameNS|Element.getElementsByTagName

Availability

HTML DOM Level 2|W3C
hasAttribute(String name) : Boolean
Determines if the given attribute exists on this element.
 Show Details

Parameters
String name Name of the attribute to check.

Returns
Boolean

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.
See Also

Attr.specified|Element.getAttribute|Element.setAttribute

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
 Show Details no 1.0+ 6.0+ 8.0+ 1.3+

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

Returns
Boolean

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.
See Also

Element.getAttributeNS|Element.setAttributeNS

Availability

HTML DOM Level 2|W3C
removeAttribute(String name) : void
Removes an attribute by name
 Show Details 4.0+ 1.0+ 6.0+ 8.0+ 1.0+

Parameters
String name Name of the attribute to remove.

Returns
void

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.
See Also

Element.getAttribute|Element.setAttribute|Node.attributes

Availability

HTML DOM Level 2|W3C
static removeAttributeNode(Attr oldAttr) : Attr
Removes the specified attribute node
 Show Details 6.0+ 1.0+ 6.0+ 8.0+ 1.0+
  • IE: Minimal support in IE 6.0 (Windows) and IE 5 (Mac).

Parameters
Attr oldAttr Node to remove from the attribute.

Returns
Attr

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
 Show Details no 1.0+ 6.0+ 8.0+ no

Returns
void

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.
See Also

Element.getAttributeNS|Element.removeAttribute|Element.setAttributeNS

Availability

HTML DOM Level 2|W3C
setAttribute(String name, String value) : void
Adds a new attribute.
 Show Details 5.0+ 1.0+ 6.0+ 8.0+ 1.0+
  • IE: IE removes event attributes when you try to set style attributes.

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

Returns
void

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.
See Also

Element.getAttribute|Element.removeAttribute|Element.setAttributeNode

Availability

HTML DOM Level 2|W3C
static setAttributeNode(Attr newAttr) : Attr
Adds the given attribute node
 Show Details 4.0+ 1.0+ 6.0+ 8.0+ 1.0+
  • Safari: Safari will create the attribute, but you will have to use nodeValue to set its value.

Parameters
Attr newAttr Attr node of the attribute to set.

Returns
Attr

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
static setAttributeNodeNS(Attr newAttr) : Attr
Sets an attribute value with the given node's name and namespace URI.
 Show Details no 1.0+ 6.0+ 8.0+ no

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

Returns
Attr

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.
See Also

Attr|Element.setAttributeNS|Element.setAttributeNode

Availability

HTML DOM Level 2|W3C
setAttributeNS(String namespaceURI, String qualifiedName, String value) : void
Adds a new attribute with a namespace URI
 Show Details no 1.0+ 6.0+ 8.0+ no

Parameters
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.

Returns
void

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.
See Also

Element.setAttribute|Element.setAttributeNode

Availability

HTML DOM Level 2|W3C

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

text_javascript aptana_docs