Selectors API

Examples

This section is non-normative.

Some ECMAScript [ECMA262] examples:

function resolver(str) {
  var prefixes = {
    xh:  "http://www.w3.org/1999/xhtml",
    svg: "http://www.w3.org/2000/svg"}
  return prefixes[str];
}
var a = document.matchAll("xh|div > svg|svg", resolver);
var b = document.match("div.foo.bar");

a contains a StaticNodeList of all the nodes matched by xh|div > svg|svg (namespace prefixes are resolved using the function in this case). b would contain the first div element which has the classes foo and bar set. (So in case of multiple div elements matching div.foo.bar only the first is returned because match is used and not matchAll.)

function test(){
  var c = document.matchAll(":root"),
      d = document.documentElement;
  return c[0] === d;
}

test() would return true when both matchAll and :root are supported.

When using :root like this it's probably better (and faster) to use match given that there's only one possible result. This is just to illustrate how it works.

var e = document.matchAll("p.warning, p.alert");

The above code snippet shows that besides using a single selector you can also pass a group of selectors (basically comma-separated selectors) as argument. e would contain a StaticNodeList with all p elements in the document that have a warning or alert class.

Conformance Requirements

Everying in this specification is normative except for diagrams, examples, notes and sections marked non-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 following conformance classes are defined by this specification:

conforming implementation

A UA that implements all interfaces described in this specification and follows all must-, required- and shall-level of critera in this specification.

conforming document

A document that follows all must-, required- and shall-level of critera in this specification that apply to document authors.

conforming authoring tool

One that produces conforming documents.

Outstanding Issues

This section is non-normative.

The draft has several outstanding issues that either need to be addressed in one way or another at some point:

• Several people have raised issues with naming the methods match and matchAll as those might suggest a boolean return value. Alternate suggestions have been select and selectAll.
• There was at least one request for scoped selectors. For example, being able to do event.target.match() or in other words allowing the methods on Element nodes. Given that Selectors itself has no notion of scoped selectors this might be difficult to define and is perhaps better delayed until the CSS WG has defined scoped selectors.
• It would be nice if extensibility was addressed by DOM Level 3 Core or a separate specification that all DOM specifications could reuse.
• Need to look into XPathNSResolver and the default namespace.
• If DOM Level 3 Core gets errata we might be able to get away with not having a new interface at all for NodeList (StaticNodeList), but just say that the object implementing the NodeList interface is not live.

The DocumentSelector Interface

Objects implementing the Document interface defined in DOM Level 3 Core must also implement the DocumentSelector interface [DOM3Core].

interface DocumentSelector {
  Node            match(in DOMString selectors, in XPathNSResolver nsresolver);
  StaticNodeList  matchAll(in DOMString selectors, in XPathNSResolver nsresolver);
};

The match method, when invoked, must return the first (using depth-first pre-order traversal) Element that matches the group of selectors (selectors), if any. Otherwise it must return null.

The matchAll method, when invoked, must return a StaticNodeList of all the Elements that match the group of selectors (selectors) in document order (using depth-first pre-order traversal), if any. Otherwise it must return null.

Both match and matchAll take a group of selectors (selectors) as defined in [Selectors] as first argument and an XPathNSResolver (nsresolver) as second. UAs must use the nsresolver argument to resolve namespace prefixes as defined in [DOM3XPath]. When the nsresolver argument is null UAs must ignore it.

When authors use namespace prefixes within selectors they must create an object implementing the XPathNSResolver interface (or create a Function in case of ECMAScript) and pass that as argument for nsresolver as defined in in [DOM3XPath]. If they don't use namespace prefixes within selectors authors may set nsresolver to null or omit the argument completely if the language binding allows it.

Make sure [DOM3XPath] actually defines this. Otherwise this draft will have to. (Which is needed anyway when this goes beyond Last Call and DOM Level 3 XPath does not.)

If the given group of selectors (selectors) is invalid, the UA must raise a SYNTAX_ERR exception. If the given group of selectors (selectors) uses namespace prefixes and the prefix can not be resolved using the nsresolver argument UAs must raise a NAMESPACE_ERR exception.

Using psuedo-elements in one of the selectors could mean that nothing is returned for that particular selector when it doesn't resolve in one or more Element nodes.

In languages that support optional arguments for methods, like ECMAScript, omitting the nsresolver argument in either the match or matchAll method must return the same result as if the method was called with the nsresolver argument being null.

The StaticNodeList Interface

typedef StaticNodeList NodeList;

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