getElementsByTagNameNS (W3C DOM Core method)
var dates = document.getElementByTagNameNS ('http://purl.org/dc/elements/1.1/', 'date');
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
<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/">
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');
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:
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.
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
pop() on it.
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
NodeList containing all the matched elements; if no
elements are found this will be a list with zero members.
Internet Explorer doesn't implement this method (it returns undefined).
Safari 1.3 and 2 don't
* 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
//this is not supported in Safari 1.3 and 2 getElementsByTagNameNS('http://www.w3.org/1999/xhtml', '*'); //these are supported fine getElementsByTagNameNS('*', 'foo'); getElementsByTagNameNS('*', '*');
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.
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
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