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