Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Selectors API defines two methods for retrieving Element
nodes in the DOM using a group
of selectors as defined in [Selectors].
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 document is produced by the Web APIs WG, part of the Rich Web Clients Activity in the W3C Interaction Domain.
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. The editor's copy of this specification is available in W3C CVS. A detailed list of changes is also available from the CVS server.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
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.
Selector
Interface
NSResolver
Interface
StaticNodeList
Interface
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 [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 group of selectors (often simply referred to as selector) as argument and return the matched elements as result.
This section is non-normative.
Some ECMAScript [ECMA262] examples:
function resolver(str) { var prefixes = { h: "http://www.w3.org/1999/xhtml", g: "http://www.w3.org/2000/svg"} return prefixes[str]; } var a = document.matchAll("h|div > g|svg", resolver); var b = document.matchSingle("div.foo.bar");
a contains a StaticNodeList
of all the nodes matched
by h|div > g|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.
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 matchSingle()
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.
var f = document.matchSingle("#foo, #bar");
f would contain the first element in the document either
having an ID of foo
or bar
(or both).
Everything 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:
This section is non-normative.
Extensions of the APIs defined in this specification are strongly discouraged. User agents, Working Groups and other interested parties should discuss extensions on a relevant public forum, such as public-webapi@w3.org.
This section is non-normative.
This specification does not cover scoped selectors. In a future version
you might be able to do event.target.matchSingle("foo")
or
similar.
Selector
InterfaceObjects implementing the Document
interface defined in
DOM Level 3 Core must also implement the
Selector
interface [DOM3Core].
interface Selector { Node matchSingle(in DOMString selectors, in NSResolver nsresolver); StaticNodeList matchAll(in DOMString selectors, in NSResolver nsresolver); };
The interface is named Selector
because it might be implemented by
Element
nodes in the future.
The matchSingle(selectors, nsresolver)
method, when invoked, must return the first Element
node in
document order (using depth-first pre-order traversal) that matches the
group of selectors (selectors), if any. Otherwise it must return null
.
The matchAll(selectors, nsresolver)
method, when invoked, must return a StaticNodeList
of all the
Element
s that match the group of selectors
(selectors) in document order, if any. Otherwise it must return an empty StaticNodeList
.
Both matchSingle()
and matchAll()
take a group of selectors
(selectors) as defined in [Selectors] as first argument and an
NSResolver
(nsresolver) as second. User agents must
use the nsresolver argument to resolve namespace
prefixes. When the nsresolver argument is
null
user agents must ignore it.
When authors use namespace prefixes within selectors they must create an object implementing the NSResolver
interface (or create a
Function
in case of ECMAScript) and pass that as argument for
nsresolver. 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.
If the given group of selectors (selectors) is invalid, the
user agent 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 a NAMESPACE_ERR
exception
must be raised.
In languages that support optional arguments for methods, like
ECMAScript, omitting the nsresolver argument in either
the matchSingle()
or matchAll()
method must
return the same result as if the method was called with the nsresolver argument being null
.
Using pseudo-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.
NSResolver
InterfaceThe NSResolver
interface allows
prefixes to be bound to a namespace URI.
interface NSResolver {
DOMString lookupNamespaceURI(in DOMString prefix);
};
The lookupNamespaceURI(prefix)
method must return the namespace belonging to the
prefix (prefix) or the default namespace if the
prefix argument is null
or the empty string.
To resolve namespace prefixes user agents must pass
the prefix to the lookupNamespaceURI
method. To get
the default namespace user agents must invoke the
lookupNamespaceURI()
method
with the empty string. User agents must never invoke
the method with null
as argument [Selectors].
In ECMAScript (and languages that allow similar constructs) user agents
must support NSResolver
being implemented as a
Function
where the parameter of the function is identical to
the prefix argument described above.
StaticNodeList
Interfacetypedef 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.
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 using [CSS21] and because this specification did not
introduce the problem and it can already be exploited by other means user
agents don't have to take action upon it.
Another problem is hostile content. User agents should ensure they remain stable when facing a hostile
NSResolver
object. Potential
hostile things such an object could do include:
The editor would like to thank to the following people who have contributed to this specification (ordered on first name):
Thanks to all those who have helped to improve this specification by sending suggestions and corrections. (Please, keep bugging us with your issues!)