Abstract

This specification defines two methods for retrieving Element
nodes in the DOM using a group of
selectors as defined in
[Selectors].

Status of this Document

This section describes the status of this document at
the time of its publication. Other documents may supersede this
document. A list of current W3C publications and the
latest revision of this technical report can be found in the
W3C technical reports
index at http://www.w3.org/TR/.

Web content and browser developers are encouraged to review
this draft. Please send comments to public-webapi@w3.org, the
W3C's
public email list for issues related to Web APIs. Archives
of the list are available.

Publication as a Working Draft does not imply endorsement by
the W3C
Membership. This is a draft document and may be updated,
replaced or obsoleted by other documents at any time. It is
inappropriate to cite this document as other than work in
progress.

Table of Contents

Introduction

This section is non-normative.

It is often desirable to perform script and or DOM operations on a
specific set of elements in a document.
[Selectors], mostly used in
CSS
[CSS21] context, provides a way of
matching such a set of elements. This specification introduces two methods
which take a selector (technically a group of selectors) as argument and
return the matched elements as result.

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.)

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].

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 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 may 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.

Extensibility

Extensions to the DocumentSelector interface are reserved
for future work by the Web APIs WG. WGs besides the Web APIs WG
may extend the interface, but must
coordinate that with the Web APIs WG. UAs may extend
the interface, but must prefix the new members using a
string specific to the vendor following the
VendorMember scheme. (Normally members follow the
member scheme.)
FooSetDefaultNamespace(ns) would be an example for
company Foo.

Authors may use extension mechanisms specific to the
host language, like .prototype in ECMAScript.

The StaticNodeList Interface

typedef StaticNodeList NodeList;

The StaticNodeListmust 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.

Security Considerations

It is expected that implementing this specification introduces no new
risks for users.

History theft is a potential security problem, because of the
:visited pseudo-class in
[Selectors].
:visited can already be used to query which links are visited
and which are not using methods from
[DOM2Style] and even
[CSS21] and because
this specification did not introduce the problem and it can already be
exploited by other means UAs don't have to take action upon it.

Another problem is hostile content. UAs should ensure
they remain stable when facing a hostile XPathNSResolver
object. Potential hostile things such an object could do include: