getElementsByTagNameNS (W3C DOM Core method)

Spec
Version Depr. Static
DOM2 No No
Browser support (more…)
IE7 FF1.5+ SA3+ OP9+
None Full Full Full
Returns
NodeList

Example

var dates = document.getElementByTagNameNS
    ('http://purl.org/dc/elements/1.1/', 'date');

The example above gets a reference to the collection of Dublin Core <date> elements within the current document, and saves it to the variable dates. The returned collection is live, which means that changes to the XML it represents are immediately reflected in the collection, without having to retrieve it again.

The second parameter to this method is the localName of the element, so the prefix is not taken into account per se, only in so far as it declares the namespace of elements within a different namespace context. For example, in the following XML the namespace context is RSS, and the code above would match the <dc:date> element:

<item>
  <title>Dust-Me Selectors</title>
  <link>http://www.sitepoint.com/dustmeselectors/</link>
  <dc:date>2007-07-30</dc:date>
  <description>
    Dust-Me Selectors is a Firefox extension
    that finds unused CSS selectors.
  </description>
</item>

(Providing, of course, that the dc prefix has been defined on the root element:)

<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">

That example code would also match the date element in the following XML, because the namespace context here is Dublin Core:

<element xmlns="http://purl.org/dc/elements/1.1/">
  <date>2007-07-30</date>
</element>

This method can also be used contextually, to get a reference to the elements that are inside a specific element, for example:

var items = list.getElementByTagNameNS('http://www.w3.org/1999/xhtml', 'li');

So if the list in that example were a ul element, the items variable would refer to a collection of all the li elements in the HTML namespace that are inside that list.

The elements are retrieved in the linear order in which they appear in the document, ie. they correspond to a flattened view of the DOM. So if, in the previous example, the list corresponded with this HTML:

<ul xmlns="http://www.w3.org/1999/xhtml">
  <li>Cheeses
    <ul>
      <li>Edam</li>
      <li>Gouda</li>
      <li>Cheddar</li>
    </ul>
  </li>
  <li>Hams
    <ul>
      <li>Prosciutto</li>
      <li>Parma</li>
      <li>Salami</li>
    </ul>
  </li>
</ul>

The returned collection would be in the following order:

  1. [0] Cheeses
  2. [1] Edam
  3. [2] Gouda
  4. [3] Cheddar
  5. [4] Hams
  6. [5] Prosciutto
  7. [6] Parma
  8. [7] Salami

Arguments

namespace (DOMString) required

The namespaceURI of the elements to match. A value of null means no namespace. The value * matches elements in all namespaces, including elements in no namespace.

name (DOMString) required

The localName of the elements to match. The value * matches all elements.

Description

Get an ordered list of all elements with a given local name and namespace URI, that are descendents of this document or element, in the linear order in which they appear in the DOM tree.

The returned collection is a NodeList — an ordered collection of nodes, indexed numerically starting from zero. If there are no matching elements then it's a collection with zero members.

CAUTION: A collection is not an array

Even though a collection looks like an array, it isn't an array — although you can iterate through it and refer to its members like an array, you can't use Array methods like push() or pop() on it.

An Element node can inherit its namespace from an ancestor, therefore every element which is a descendent of a namespaced node also has a namespace, even if it was created with a method which is not namespace aware (such as createElement, in which case it inherits the default namespace).

Return value

A NodeList containing all the matched elements; if no elements are found this will be a list with zero members.

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 Full Full Full Partial Partial Full Full Full

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

Safari 1.3 and 2 don't support the * parameter for all elements if a specific namespace is given; they do support the * parameter for all namespaces, or for all elements if all namespaces is specified:

//this is not supported in Safari 1.3 and 2
getElementsByTagNameNS('http://www.w3.org/1999/xhtml', '*');

//these are supported fine
getElementsByTagNameNS('*', 'foo');
getElementsByTagNameNS('*', '*');
: Behavior in HTML

Since namespaces are an XML construct, it's only reasonable to judge the behavior of this method in terms of XML (either on HTML pages in XHTML mode1, or pure XML). The behavioral variations of browsers in HTML mode2 are documented here for interest and reference, but the support summary table above does not consider this behavior.

Opera and Firefox treat elements as being in no namespace, therefore a search for all elements in the default namespace will return no elements. The exception to this is elements created using createElementNS, which are considered to be in their specified namespace (as expected). Firefox will match elements in no namespace if the namespace argument is null or an empty string; Opera will only match them if the namespace argument is an empty string. Theoretically this might also be the case in XHTML mode or XML, however it's impossible to establish (and irrelevant) because elements in those environments always have a namespace.

Safari in HTML mode treats elements as being in the HTML namespace, unless they have a prefix, in which case they're ignored completely (even if the prefix is html).

Footnotes

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

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

User-contributed notes

There are no comments yet.

Related Products