Annotation of 2006/webapi/selectors-api/Overview.html, revision 1.6
1.1 avankest 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2:
3: <html lang="en-US">
4: <head>
5: <title>Selectors API</title>
6:
7: <style type="text/css">
8: dfn { font-style:normal; font-weight:bolder }
9: em.ct { font-style:normal; font-weight:normal; font-variant:small-caps }
10: .example { margin-left:2em }
11: .note { color:green }
12: .note::before { content:"Note: " }
13: .issue { color:red }
14: .issue::before { content:"Issue: "}
15: </style>
16:
17: <link href="http://www.w3.org/StyleSheets/TR/base.css" rel="stylesheet">
18:
19: <body>
20: <div class="head">
21: <p><a href="http://www.w3.org/"><img alt="W3C"
22: src="http://www.w3.org/Icons/w3c_home"></a></p>
23:
24: <h1 id="title">Selectors API</h1>
25:
1.5 avankest 26: <h2 class="no-num no-toc" id="W3C-doctype">Editor's Draft September 2006</h2>
1.1 avankest 27:
28: <dl>
1.5 avankest 29: <dt>This Version:
1.1 avankest 30:
31: <dd>http://www.w3.org/TR/YYYY/TT-selectors-api-YYYYMMDD
32:
1.5 avankest 33: <dt>Latest Version:
1.1 avankest 34:
35: <dd><a
36: href="http://www.w3.org/TR/selectors-api/">http://www.w3.org/TR/selectors-api/</a>
37:
1.5 avankest 38: <dt>Previous Version:
1.1 avankest 39:
40: <dd><a
41: href="http://www.w3.org/TR/2006/WD-selectors-api-20060525/">http://www.w3.org/TR/2006/WD-selectors-api-20060525/</a>
42:
43: <dt>Editor:
44:
45: <dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a> (<a
46: href="http://www.opera.com/">Opera Software ASA</a>) <<a
47: href="mailto:annevk@opera.com">annevk@opera.com</a>>
48: </dl>
49:
50: <p class="copyright"><a
51: href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
52: © 2006 <a href="http://www.w3.org/"><abbr title="World Wide Web
53: Consortium">W3C</abbr></a><sup>®</sup> (<a
54: href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of
55: Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><abbr
56: title="European Research Consortium for Informatics and
57: Mathematics">ERCIM</abbr></a>, <a
58: href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
59: href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
60: <a
61: href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
62: and <a
63: href="http://www.w3.org/Consortium/Legal/copyright-documents">document
64: use</a> rules apply.</p>
65: </div>
66:
67: <hr>
68:
69: <h2 class="no-num no-toc" id="abstract">Abstract</h2>
70:
1.4 avankest 71: <p>Selectors API defines two methods for retrieving <code>Element</code>
72: nodes in the <abbr title="Document Object Model">DOM</abbr> using a group
73: of selectors as defined in [<cite><a
1.1 avankest 74: href="#ref-selectors">Selectors</a></cite>].
75:
76: <h2 class="no-num no-toc" id="sotd">Status of this Document</h2>
77:
78: <p><em>This section describes the status of this document at the time of
79: its publication. Other documents may supersede this document. A list of
80: current W3C publications and the latest revision of this technical report
81: can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
82: index</a> at http://www.w3.org/TR/.</em>
83:
1.5 avankest 84: <p>This document is produced by the <a
85: href="http://www.w3.org/2006/webapi">Web APIs WG</a>, part of the <a
86: href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients Activity</a>
87: in the W3C <a href="http://www.w3.org/Interaction/">Interaction
88: Domain</a>.
1.1 avankest 89:
90: <p>Web content and browser developers are encouraged to review this draft.
91: Please send comments to <a
92: href="mailto:public-webapi@w3.org">public-webapi@w3.org</a>, the W3C's
93: public email list for issues related to Web APIs. <a
94: href="http://lists.w3.org/Archives/Public/public-webapi/">Archives</a> of
95: the list are available. The editor's copy of this specification is <a
1.3 avankest 96: href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/selectors-api/Overview.html?content-type=text/html;%20charset=utf-8">available
1.1 avankest 97: in W3C CVS</a>. A detailed list of changes is also available <a
98: href="http://dev.w3.org/cvsweb/2006/webapi/selectors-api/">from the CVS
99: server</a>.
100:
101: <p>Implementors should be aware that this specification is not stable.
102: <strong>Implementors who are not taking part in the discussions are likely
103: to find the specification changing out from under them in incompatible
104: ways.</strong> Vendors interested in implementing this specification
105: before it eventually reaches the Candidate Recommendation stage should
106: join the aforementioned mailing lists and take part in the discussions.
107:
108: <p>This document was produced by a group operating under the <a
109: href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
110: 2004 W3C Patent Policy</a>. W3C maintains a <a
111: href="http://www.w3.org/2004/01/pp-impl/38482/status"
112: rel="disclosure">public list of any patent disclosures</a> made in
113: connection with the deliverables of the group; that page also includes
114: instructions for disclosing a patent. An individual who has actual
115: knowledge of a patent which the individual believes contains <a
116: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
117: Claim(s)</a> must disclose the information in accordance with <a
118: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
119: 6 of the W3C Patent Policy</a>.
120:
121: <h2 class="no-num no-toc" id="toc">Table of Contents</h2>
122: <!--begin-toc-->
123:
124: <ul class="toc">
125: <li><a href="#introduction"><span class="secno">1. </span>Introduction</a>
126:
127: <ul class="toc">
128: <li><a href="#examples"><span class="secno">1.1. </span>Examples</a>
129:
130: <li><a href="#conformance"><span class="secno">1.2. </span>Conformance
131: Requirements</a>
132:
1.5 avankest 133: <li><a href="#extensibility"><span class="secno">1.3.
134: </span>Extensibility</a>
135:
1.6 ! avankest 136: <li><a href="#notcovered"><span class="secno">1.4. </span>Not in this
1.5 avankest 137: Specification</a>
1.1 avankest 138: </ul>
139:
1.6 ! avankest 140: <li><a href="#documentselector"><span class="secno">2. </span>The <code
! 141: title="">Selector</code> Interface</a>
! 142:
! 143: <li><a href="#nsresolver"><span class="secno">3. </span>The <code
! 144: title="">NSResolver</code> Interface</a>
1.1 avankest 145:
1.6 ! avankest 146: <li><a href="#staticnodelist"><span class="secno">4. </span>The <code
! 147: title="">StaticNodeList</code> Interface</a>
1.1 avankest 148:
1.6 ! avankest 149: <li><a href="#security"><span class="secno">5. </span>Security
1.1 avankest 150: Considerations</a>
151:
152: <li class="no-num"><a href="#references">References</a>
153:
154: <li class="no-num"><a href="#acknowledgements">Acknowledgements</a>
155: </ul>
156: <!--end-toc-->
157:
158: <h2 id="introduction"><span class="secno">1. </span>Introduction</h2>
159:
160: <p><em>This section is non-normative.</em>
161:
162: <p>It is often desirable to perform script and or DOM operations on a
1.4 avankest 163: specific set of elements in a document. Selectors [<cite><a
1.1 avankest 164: href="#ref-selectors">Selectors</a></cite>], mostly used in <abbr
165: title="Cascading Style Sheets">CSS</abbr> [<cite><a
166: href="#ref-css21">CSS21</a></cite>] context, provides a way of matching
167: such a set of elements. This specification introduces two methods which
168: take a group of selectors (often referred to as selector) as argument and
169: return the matched elements as result.
170:
171: <h3 id="examples"><span class="secno">1.1. </span>Examples</h3>
172:
173: <p><em>This section is non-normative.</em>
174:
175: <p>Some ECMAScript [<cite><a href="#ref-ecma262">ECMA262</a></cite>]
176: examples:
177:
178: <pre>function resolver(str) {
179: var prefixes = {
180: xh: "http://www.w3.org/1999/xhtml",
181: svg: "http://www.w3.org/2000/svg"}
182: return prefixes[str];
183: }
184: var <var>a</var> = document.matchAll("xh|div > svg|svg", resolver);
1.6 ! avankest 185: var <var>b</var> = document.matchSingle("div.foo.bar");</pre>
1.1 avankest 186:
1.6 ! avankest 187: <p><var>a</var> contains a <code><a
! 188: href="#staticnodelist0">StaticNodeList</a></code> of all the nodes matched
! 189: by <code>xh|div > svg|svg</code> (namespace prefixes are resolved using
! 190: the function in this case). <var>b</var> would contain the first
! 191: <code>div</code> element which has the classes <code>foo</code> and
1.1 avankest 192: <code>bar</code> set. (So in case of multiple <code>div</code> elements
193: matching <code>div.foo.bar</code> only the first is returned because
1.6 ! avankest 194: <code><a href="#matchsingle">matchSingle()</a></code> is used and not
! 195: <code><a href="#matchall">matchAll()</a></code>.)
1.1 avankest 196:
197: <pre>function test(){
198: var c = document.matchAll(":root"),
199: d = document.documentElement;
200: return c[0] === d;
201: }</pre>
202:
1.6 ! avankest 203: <p><code>test()</code> would return <code>true</code> when both <code><a
! 204: href="#matchall">matchAll()</a></code> and <code>:root</code> are
! 205: supported.
1.1 avankest 206:
207: <p class="note">When using <code>:root</code> like this it's probably
1.6 ! avankest 208: better (and faster) to use <code><a
! 209: href="#matchsingle">matchSingle()</a></code> given that there's only one
! 210: possible result. This is just to illustrate how it works.
1.1 avankest 211:
212: <pre>var <var>e</var> = document.matchAll("p.warning, p.alert");</pre>
213:
214: <p>The above code snippet shows that besides using a single selector you
215: can also pass a group of selectors (basically comma-separated selectors)
1.6 ! avankest 216: as argument. <var>e</var> would contain a <code><a
! 217: href="#staticnodelist0">StaticNodeList</a></code> with all <code>p</code>
! 218: elements in the document that have a <code>warning</code> or
! 219: <code>alert</code> class.
1.1 avankest 220:
221: <h3 id="conformance"><span class="secno">1.2. </span>Conformance
222: Requirements</h3>
223:
1.6 ! avankest 224: <p>Everything in this specification is normative except for diagrams,
1.1 avankest 225: examples, notes and sections marked non-normative.
226:
227: <p>The key words <em class="ct">must</em>, <em class="ct">must not</em>,
228: <em class="ct">required</em>, <em class="ct">shall</em>, <em
229: class="ct">shall not</em>, <em class="ct">should</em>, <em
230: class="ct">should not</em>, <em class="ct">recommended</em>, <em
231: class="ct">may</em>, and <em class="ct">optional</em> in the normative
232: parts of this document are to be interpreted as described in [<cite><a
233: href="#ref-rfc2119">RFC2119</a></cite>].
234:
235: <p>The following conformance classes are defined by this specification:
236:
237: <dl>
238: <dt><dfn id="conforming">conforming implementation</dfn>
239:
1.5 avankest 240: <dd>A user agent that implements all interfaces described in this
241: specification and follows all <em class="ct">must</em>-, <em
242: class="ct">required</em>- and <em class="ct">shall</em>-level of critera
243: in this specification.
1.1 avankest 244:
245: <dt><dfn id="conforming0">conforming document</dfn>
246:
247: <dd>A document that follows all <em class="ct">must</em>-, <em
248: class="ct">required</em>- and <em class="ct">shall</em>-level of critera
249: in this specification that apply to document authors.
250:
251: <dt><dfn id="conforming1">conforming authoring tool</dfn>
252:
253: <dd>One that produces conforming documents.
254: </dl>
255:
1.5 avankest 256: <h3 id="extensibility"><span class="secno">1.3. </span>Extensibility</h3>
257:
258: <p><em>This section is non-normative.</em>
259:
260: <p>Extensions of the APIs defined in this specification are <em>strongly
261: discouraged</em>. User agents, Working Groups and other interested parties
262: should discuss extensions on a relevant public forum, such as <a
263: href="mailto:public-webapi@w3.org">public-webapi@w3.org</a>.
264:
1.6 ! avankest 265: <h3 id="notcovered"><span class="secno">1.4. </span>Not in this
1.5 avankest 266: Specification</h3>
267:
268: <p><em>This section is non normative.</em>
1.1 avankest 269:
1.5 avankest 270: <p>This specification does not cover scoped selectors. In a future version
1.6 ! avankest 271: you might be able to do <code>event.target.matchSingle("foo")</code> or
! 272: similar.
1.1 avankest 273:
1.6 ! avankest 274: <h2 id="documentselector"><span class="secno">2. </span>The <code
! 275: title="">Selector</code> Interface</h2>
1.1 avankest 276:
277: <p>Objects implementing the <code>Document</code> interface defined in
278: <cite>DOM Level 3 Core</cite> <em class="ct">must</em> also implement the
1.6 ! avankest 279: <code><a href="#selector">Selector</a></code> interface [<cite><a
1.1 avankest 280: href="#ref-dom3core">DOM3Core</a></cite>].
281:
1.6 ! avankest 282: <pre class="idl">interface <dfn id="selector">Selector</dfn> {
! 283: Node <span><a href="#matchsingle">matchSingle</a></span>(in DOMString <var>selectors</var>, in NSResolver <var title="">nsresolver</var>);
! 284: StaticNodeList <span><a href="#matchall">matchAll</a></span>(in DOMString <var>selectors</var>, in NSResolver <var title="">nsresolver</var>);
1.1 avankest 285: };</pre>
286:
1.6 ! avankest 287: <p class="note">The interface is named <code><a
! 288: href="#selector">Selector</a></code> because it might be implemented by
! 289: <code>Element</code> nodes in the future.
! 290:
! 291: <p>The <dfn id="matchsingle"
! 292: title="matchsingle"><code>matchSingle(<var>selectors</var>, <var
! 293: title="">nsresolver</var>)</code></dfn> method, when invoked, <em
1.2 avankest 294: class="ct">must</em> return the first <code>Element</code> node in
295: document order (using depth-first pre-order traversal) that matches the
296: group of selectors (<var>selectors</var>), if any. Otherwise it <em
297: class="ct">must</em> return <code>null</code>.
1.1 avankest 298:
1.6 ! avankest 299: <p>The <dfn id="matchall"
! 300: title="matchall"><code>matchAll(<var>selectors</var>, <var
! 301: title="">nsresolver</var>)</code></dfn> method, when invoked, <em
! 302: class="ct">must</em> return a <code><a
! 303: href="#staticnodelist0">StaticNodeList</a></code> of all the
1.1 avankest 304: <code>Element</code>s that match the group of selectors
1.2 avankest 305: (<var>selectors</var>) in document order, if any. Otherwise it <em
1.6 ! avankest 306: class="ct">must</em> return an empty <code><a
! 307: href="#staticnodelist0">StaticNodeList</a></code>.
1.1 avankest 308:
1.6 ! avankest 309: <p>Both <code><a href="#matchsingle">matchSingle()</a></code> and <code><a
! 310: href="#matchall">matchAll()</a></code> take a group of selectors
! 311: (<var>selectors</var>) as defined in [<cite><a
1.1 avankest 312: href="#ref-selectors">Selectors</a></cite>] as first argument and an
1.6 ! avankest 313: <code><a href="#nsresolver0">NSResolver</a></code> (<var
! 314: title="">nsresolver</var>) as second. User agents <em class="ct">must</em>
! 315: use the <var title="">nsresolver</var> argument to resolve namespace
! 316: prefixes. When the <var title="">nsresolver</var> argument is
! 317: <code>null</code> user agents <em class="ct">must</em> ignore it.
1.1 avankest 318:
319: <p>When authors use namespace prefixes within <var>selectors</var> they <em
1.6 ! avankest 320: class="ct">must</em> create an object implementing the <code><a
! 321: href="#nsresolver0">NSResolver</a></code> interface (or create a
! 322: <code>Function</code> in case of ECMAScript) and pass that as argument for
! 323: <var title="">nsresolver</var>. If they don't use namespace prefixes
! 324: within <var>selectors</var> authors <em class="ct">may</em> set <var
! 325: title="">nsresolver</var> to <code>null</code> or omit the argument
! 326: completely if the language binding allows it.
1.1 avankest 327:
328: <p>If the given group of selectors (<var>selectors</var>) is invalid, the
1.5 avankest 329: user agent <em class="ct">must</em> raise a <code>SYNTAX_ERR</code>
330: exception. If the given group of selectors (<var>selectors</var>) uses
1.6 ! avankest 331: namespace prefixes and the prefix can not be resolved using the <var
! 332: title="">nsresolver</var> argument <em class="ct">must</em> raise a
1.1 avankest 333: <code>NAMESPACE_ERR</code> exception.
334:
1.5 avankest 335: <p class="note">Using pseudo-elements in one of the selectors could mean
1.1 avankest 336: that nothing is returned for that particular selector when it doesn't
337: resolve in one or more <code>Element</code> nodes.
338:
339: <p>In languages that support optional arguments for methods, like
1.6 ! avankest 340: ECMAScript, omitting the <var title="">nsresolver</var> argument in either
! 341: the <code><a href="#matchsingle">matchSingle()</a></code> or <code><a
! 342: href="#matchall">matchAll()</a></code> method <em class="ct">must</em>
! 343: return the same result as if the method was called with the <var
! 344: title="">nsresolver</var> argument being <code>null</code>.
1.1 avankest 345:
1.6 ! avankest 346: <h2 id="nsresolver"><span class="secno">3. </span>The <code
! 347: title="">NSResolver</code> Interface</h2>
! 348:
! 349: <pre class="idl">interface <dfn id="nsresolver0">NSResolver</dfn> {
! 350: DOMString lookupNamespaceURI(in DOMString prefix);
! 351: };</pre>
1.1 avankest 352:
1.6 ! avankest 353: <p class="issue">Need to write this.
1.1 avankest 354:
1.6 ! avankest 355: <h2 id="staticnodelist"><span class="secno">4. </span>The <code
! 356: title="">StaticNodeList</code> Interface</h2>
! 357:
! 358: <pre
! 359: class="idl">typedef <dfn id="staticnodelist0">StaticNodeList</dfn> NodeList;</pre>
! 360:
! 361: <p>The <code><a href="#staticnodelist0">StaticNodeList</a></code> <em
! 362: class="ct">must</em> be implemented identically to the
! 363: <code>NodeList</code> interface as defined in [<cite><a
1.1 avankest 364: href="#ref-dom3core">DOM3Core</a></cite>] with the exception that the
365: interface, as the name suggests, is static and not live.
366:
1.6 ! avankest 367: <h2 id="security"><span class="secno">5. </span>Security Considerations</h2>
1.1 avankest 368:
369: <p>It is expected that implementing this specification introduces no new
370: risks for users.
371:
372: <p>History theft is a potential security problem, because of the
373: <code>:visited</code> pseudo-class in [<cite><a
374: href="#ref-selectors">Selectors</a></cite>]. <code>:visited</code> can
1.5 avankest 375: already be used to query which links are visited using [<cite><a
376: href="#ref-css21">CSS21</a></cite>] and because this specification did not
377: introduce the problem and it can already be exploited by other means user
378: agents don't have to take action upon it.
1.1 avankest 379:
1.5 avankest 380: <p>Another problem is hostile content. User agents <em
381: class="ct">should</em> ensure they remain stable when facing a hostile
1.6 ! avankest 382: <code><a href="#nsresolver0">NSResolver</a></code> object. Potential
! 383: hostile things such an object could do include:
1.1 avankest 384:
385: <ul>
386: <li>Returning inconsistent results;
387:
388: <li>Hanging;
389:
390: <li>Changing the DOM during the operation.
391: </ul>
392:
393: <h2 class="no-num" id="references">References</h2>
394:
395: <dl>
396: <dt id="ref-css21">[CSS21]
397:
398: <dd>(Informative) <cite><a href="http://www.w3.org/TR/CSS21">Cascading
399: Style Sheets, level 2 revision 1</a></cite>, B. Bos, T. Çelik, I.
1.6 ! avankest 400: Hickson, H. Wium Lie, editors. World Wide Web Consortium, June 2005.
1.1 avankest 401:
402: <dt id="ref-dom3core">[DOM3Core]
403:
404: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-Core">Document Object
405: Model (DOM) Level 3 Core Specification</a></cite>, A. Le Hors, P. Le
406: Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors.
407: World Wide Web Consortium, April 2004.
408:
409: <dt id="ref-ecma262">[ECMA262]
410:
411: <dd><cite><a
412: href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript
413: Language Specification</a></cite>, Third Edition. ECMA, December 1999.
414:
415: <dt id="ref-selectors">[Selectors]
416:
417: <dd><cite><a
418: href="http://www.w3.org/TR/css3-selectors">Selectors</a></cite>, D.
419: Glazman, T. Çelik, I. Hickson, P. Linss, J. Williams, editors. World
420: Wide Web Consortium, December 2005.
421:
422: <dt id="ref-rfc2119">[RFC2119]
423:
424: <dd><cite><a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119: Key
425: words for use in RFCs to Indicate Requirement Levels</a></cite>, S.
426: Bradner. IETF, March 1997.
427: </dl>
428:
429: <h2 class="no-num" id="acknowledgements">Acknowledgements</h2>
430:
431: <ul>
432: <li>Björn Höhrmann
433:
434: <li>Cameron McCormack
435:
436: <li>Daniel Schierbeck
437:
438: <li>Dean Jackson
439:
440: <li>Ian Hickson
441:
442: <li>Jim Ley
443:
444: <li>Jonas Sicking
445:
1.5 avankest 446: <li>Karl Dubost
447:
1.1 avankest 448: <li>Lachlan Hunt
449:
450: <li>Maciej Stachowiak
451:
452: <li>Mohamed Zergaoui
453:
454: <li>Robin Berjon
455: </ul>
456:
457: <p>Thanks to all those who have helped to improve this specification by
458: sending suggestions and corrections. (Please, keep bugging us with your
459: issues!)
Webmaster