Abstract

Selectors, which are widely used in CSS, are patterns that match against
elements in a tree structure [SELECT][CSS21]. The Selectors API
specification defines methods for retrieving Element nodes
from the DOM by matching
against a group of selectors. It is often desirable to perform DOM
operations on a specific set of elements in a document. These methods
simplify the process of acquiring specific elements, especially compared
with the more verbose techniques defined and used in the past.

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

This is the 22 December 2009 Candidate Recommendation of Selectors API.
W3C publishes a Candidate Recommendation to indicate that the document is
believed to be stable and to encourage implementation by the developer
community. The Web Applications
(WebApps) Working Group expects to request that the Director advance
this document to Proposed Recommendation once the Working Group has
developed a comprehensive Selectors
API test suite, and demonstrated that at least two complete
implementations exist which pass the Test Suite.

There are several known implementations believed to be complete and
interoperable (or on the point of being so) and the WebApps Working Group
expects to develop a test suite and use it to show that that these
implementations pass early in 2010. The Working Group does not plan to
request to advance to Proposed Recommendation prior to 30 April 2010.
There is no formal implementation report available at the present time.

The Last Call Working Draft for this specification resulted in a number
of Last Call comments which have all been addressed by the Working Group,
a list of which can be found in the Disposition
of Comments.

Publication as a Candidate Recommendation 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.

1. Introduction

This section is non-normative.

This specification introduces two methods that take a group of selectors
(often simply referred to as a selector) as an argument and return the
matching elements [SELECT]. With these methods, it is
easier to match a set of Element nodes based on specific
criteria, than having to subsequently filter the result of calling other
methods like getElementsByTagName().

In order to obtain the cells containing the results in the table, which
might be done, for example, to plot the values on a graph, there are at
least two approaches that may be taken. Using only the APIs from DOM
Level 2, it requires a script like the following that iterates through
each tr within each tbody in the
table to find the second cell of each row.

Note that the script operates on the DOM and works independently from
the syntax used to create the document. Thus this script will also work
correctly for an equivalent table created from well-formed XHTML instead
of HTML, or dynamically created and inserted into a document using DOM
APIs.

2. Conformance Requirements

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

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

The following conformance classes are defined (and considered) by this
specification:

conforming user agent

A user agent that implements the NodeSelector interface described
in this specification and conforms to all must-level
criteria that apply to implementations.

conforming application

An application that uses the interfaces defined in this specification
and conforms to all must-level criteria that apply to
applications.

2.1. Terminology and
Conventions

The terminology used in this specification is that from Selectors [SELECT].

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result
is equivalent.

The IDL used in this specification uses the syntax defined in Web IDL [WEBIDL].

The construction "Foo object", where Foo is
actually an interface, is sometimes used instead of the more accurate
"object implementing the Foo interface".

The interfaces used within, but not defined by, this specification,
including Document, DocumentFragment,
Node and Element are defined in DOM Level 3 Core
[DOM-LEVEL-3-CORE].

3. Interoperability
Considerations

This section is non-normative.

Some implementations might have different levels of support for
Selectors. If some implementations lack support for some selectors, then
the use of such selectors will result in those implementations failing to
return the expected results. Authors are advised to check for the DOM
Exceptions thrown by these APIs and provide a fallback for graceful
degradation.

3.1. Extensibility

This section is non-normative.

Extensions of the APIs defined in this specification are strongly
discouraged. Implementors, Working Groups and other interested
parties should discuss extensions on a relevant public forum, such as public-webapps@w3.org.

4. Security Considerations

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

If, at any time, the implementation detects a situation which would
violate security policies, the implementation may abort
and raise a security exception. If any other error condition occurs which
is not covered directly by this or any other relevant specification, the
implementation may abort and raise an appropriate,
language-binding-specific or implementation-specific exception.

5. Privacy Considerations

History theft is a potential privacy issue because the
:visited pseudo-class in Selectors [SELECT] allows authors to query
which links have been visited.

This is not a new problem, as it can already be exploited
using existing CSS and DOM APIs, such as getComputedStyle()[DOM-LEVEL-2-STYLE].

In this example, vlinks will acquire a list of links that
the user has visited. The author can then obtain the URIs and potentially
exploit this knowledge.

As defined in
Selectors ([SELECT], section 6.6.1), user
agents may treat all links as unvisited links. It is recommended that implementations behave consistently with
other uses of Selectors supported by the user agent.

6. The APIs

The term first used in the definitions of the
methods defined in this specification means first in document
order. The term document order means a
depth-first pre-order traversal of the DOM tree or subtree in question.
The term context node refers to the node upon
which the method was invoked. The term node’s
subtrees refers to the collection of elements that are descendants
of the context node. The term matching Element node refers
to an Element node that matches the group of selectors
(selectors) that was passed to the method, according to the
rules for matching elements defined in Selectors [SELECT].

The querySelector() method on the
NodeSelector interface
must, when invoked, return the first matching Element node within the node’s subtrees. If there is no such node,
the method must return null.

The querySelectorAll() method on the
NodeSelector interface
must, when invoked, return a NodeList
containing all of the matching Element nodes within the node’s subtrees, in document order. If there are no such nodes, the
method must return an empty NodeList.

The NodeList object returned by the querySelectorAll() method must be static, not live ([DOM-LEVEL-3-CORE],
section 1.1.1). Subsequent changes to the structure of the underlying
document must not be reflected in the
NodeList object. This means that the object will instead
contain a list of matching Element nodes that were in the
document at the time the list was created.

Implementers are advised that if null or
undefined are passed as the value of the selectors
parameter, they are to be handled as defined in WebIDL [WEBIDL]. Authors are advised to
avoid passing these values.

Authors are advised that while the use of pseudo-elements in
selectors is permitted, they will not match any elements in the document,
and thus would not result in any elements being returned. Therefore,
authors are advised to avoid the use of pseudo-elements in selectors that
are passed to the methods defined in this specification.

6.3. Resolving
Namespaces

This specification does not provide support for resolving
arbitrary namespace prefixes. However, support for a namespace prefix
resolution mechanism may be considered for inclusion in a future version
of this specification.

A namespace prefix needs to be resolved if the
namespace component is neither empty (e.g. |div),
representing the null namespace, or an asterisk (e.g. *|div),
representing any namespace. Since the asterisk or empty namespace prefix
do not need to be resolved, implementations that support the namespace
syntax in Selectors must support these. [SELECT]

Implementations that don't support the namespace syntax in
Selectors would instead throw a SYNTAX_ERR because it would
be treated as an invalid selector.

7. DOM Feature String

DOM3 Core defines several methods for checking for interface support, or
for obtaining implementations of interfaces, using feature
strings ([DOM-LEVEL-3-CORE],
section 1.3.6). A DOM application can use these methods, each of which
accept feature and version parameters, using the
values "Selectors-API" and "1.0"
(respectively).

Conforming implementations must respond with a
true value when the hasFeature method is queried
with these values. Authors are cautioned, however, that implementations
returning true might not be perfectly compliant, and that
implementations returning false might well have support for
features in this specification; in general, therefore, use of this method
is discouraged.

The methods accept a group of selectors (comma separated) as the
argument. The following example would select all p elements
in the document that have a class of either "error" or
"warning".

var alerts = document.querySelectorAll("p.warning, p.error");

The querySelector() methods
also accept a group of selectors and they will return the first element
(if any) that matches any of the selectors in the group.

var x = document.querySelector("#foo, #bar");

x would contain the first element in the document with an ID
of either foo or bar, or null if
there is no such element. In the sample document above, it would select
the div element with the ID of foo because it
is first in document order. The order of the selectors used in the
parameter has no effect and would have the same result if the order were
reversed, as in:

var x = document.querySelector("#bar, #foo");

The methods can also be invoked on elements. In the following example,
assume the event handler is registered on an element, and thus the method
is invoked on the target element of the event.

Even though the method is invoked on an element, selectors are still
evaluated in the context of the entire document. In the following
example, the method will still match the div element's child
p element, even though the body element is not
a descendant of the div element itself.

In ECMAScript, the language binding also allows NodeLists
to be addressed using the array notation, so that loop could be rewritten
like this:

for (var i = 0; i < lis.length; i++) {
process(lis[i]);
}

Since the NodeList objects returned by these methods are
not live, changes to the DOM do not affect the content of the list.
Consider the process() function called in the previous
examples is defined as follows:

function process(elmt) {
elmt.parentNode.removeChild(elmt);
}

This would cause each selected element to be removed from the DOM, but
each element will remain in the NodeList. If the list were a
live NodeList, removing an item from the DOM would also
remove the element from the list and adjust the indexes of subsequent
elements. That would have adverse effects upon the loop because not all
selected elements would be processed.

In documents comprising elements from multiple namespaces, it's
possible that some elements from different namespaces share the same
local name. Since this API does not natively support a namespace
resolution mechanism for selectors, obtaining a list of such elements
from a specific namespace, excluding all others, requires additional
processing to filter the result. The following example illustrates a
document containing video elements from both the SVG and
XHTML namespaces.