Selectors API

Conformance requirements

As well as sections marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in the normative parts of this document are to be interpreted as described in [RFC2119].

The DocumentSelector interface

Objects implementing the Document interface defined in DOM Level 3 Core must also implement the DocumentSelector interface. UAs implementing the DocumentSelector interface must also implement the XPathNSResolver interface defined in DOM Level 3 XPath and the StaticNodeList interface defined in this specification [DOM3XPATH].

interface DocumentSelector {
  StaticNodeList     getElementsBySelector(in DOMString selector);
  StaticNodeList     getElementsBySelector(in DOMString selector, in XPathNSResolver nsresolver);
};

getElementsBySelector returns a StaticNodeList of all the Elements that match the selector selector in document order [DOM3CORE]. If the selector selector uses namespace prefixes they must be resolved using the nsresolver argument.

If the given selector selector is an invalid selector or contains a pseudo-element the UA must raise a SYNTAX_ERR exception [Selectors]. If the given selector selector uses namespace prefixes and the prefix can not be resolved using the nsresolver argument the UA must raise a NAMESPACE_ERR exception.

Something like this would be possible in ECMAScript:

function NSResolver(prefix){
 if("xh" == prefix)
  return "http://www.w3.org/1999/xhtml";
 else if("svg" == prefix)
  return "http://www.w3.org/2000/svg";
 else // ouch!
  return null;
}
var x = document.getElementsBySelector("xh|div > svg|svg", NSResolver);
var y = document.getElementsBySelector("div.foo.bar");

Cool!

The StaticNodeList interface

interface NodeList {
  Node               item(in unsigned long index);
  readonly attribute unsigned long   length;
};

The StaticNodeList must be implemented identically to the NodeList interface as defined in DOM Level 3 Core with the exception that the interface, as the name suggests, is static and not live [DOM3CORE].