setAttributeNS (W3C DOM Core method)

Spec
Version Depr. Static
DOM2 No No
Browser support (more…)
IE7 FF1.5+ SA3+ OP9+
None Buggy Full Buggy
Returns
void
Throws
INVALID_CHARACTER_ERR, NO_MODIFICATION_ALLOWED_ERR, NAMESPACE_ERR

Example

document.documentElement.setAttributeNS
    ('http://www.w3.org/XML/1998/namespace', 'xml:lang', 'en-au-tas');

The example above sets an xml:lang attribute in the XML namespace with the value en-au-tas, and adds it to the documentElement.

So if the element in question were this HTML:

<html xmlns="http://www.w3.org/1999/xhtml">

Then the operation above would result in this:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-au-tas">

Arguments

namespace (DOMString) required

The namespaceURI of the attribute to create or alter. A value of null means no namespace.

name (DOMString) required

The qualified name of the attribute to create or alter.

value (DOMString) required

The string value for the attribute.

Description

Set a new attribute with the specified local name, namespace URI and value to this element.

If an attribute already exists with the same local name and namespace URI, its value is replaced and its prefix changed to the prefix part of the specified qualified name1.

When setting a value, the value is not parsed, so any entity references or other markup will be treated as literal text. To create an attribute containing entities the specification suggests to create an Attr node with appropriate Text and EntityReference nodes as children, then add it to an element using setAttributeNode, however in practise this rarely works (see Attr for details).

Unlike Element nodes, Attr nodes do not inherit a namespace from the element they're attached to — if an attribute does not have an explicitly defined namespace then it simply has no namespace (see Attr for details).

Compatibility

Internet Explorer Firefox Safari Opera
5.5 6.0 7.0 1.5 2.0 3.0 1.3 2.0 3.0 9.0 9.5
None None None Buggy Buggy Buggy Buggy Buggy Full Buggy Buggy

Internet Explorer doesn't implement this method (it returns undefined).

Opera 9.0 in pure XML (but not XHTML mode2) parses entities when setting the value of an attribute.

An element may contain two attributes which have the same local name but different namespaces (for example, an <a> element may contain both an href attribute in no namespace, and an html:href attribute in the XHTML namespace). Although these are different attributes, Opera will consider the html:href attribute to be an href attribute if an existing href attribute is not already defined (assuming that the html prefix has been declared and assigned to the default namespace). This behavior is not limited to XHTML, but occurs on all XML documents in relation to a prefix declared for the default namespace. This cannot really be considered a bug, because the DOM does not define attribute associations (that job is handled by a DTD); it's more like a convenience feature, though admittedly a very confusing one!

Safari 1.3 and 2 do the same thing as Opera in relation to XHTML (but not XML generally), however they also inherit a namespace from their owning element, therefore they will also overwrite attributes with no explicit namespace if the namespace argument matches the default.

In Firefox and Opera an empty-string namespace is treated the same as a null namespace (ie. it's taken to mean no namespace, when it should be treated as a real namespace URI); only Safari 3 gets this right.

: Behavior in HTML

All supported browsers in HTML mode3 behave exactly the same as they do in XHTML mode.

Footnotes

1 A qualified name is comprised of a local name, plus an optional prefix delimited with a colon, for example xml:lang.

2 On XHTML pages served as application/xhtml+xml.

3 On XHTML or HTML pages served as text/html.

User-contributed notes

There are no comments yet.

Related Products