Annotation of 2006/webapi/selectors-api/Overview.html, revision 1.3
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:
26: <h2 class="no-num no-toc" id="W3C-doctype">Editor's Draft June 2006</h2>
27:
28: <dl>
29: <dt>This version:
30:
31: <dd>http://www.w3.org/TR/YYYY/TT-selectors-api-YYYYMMDD
32:
33: <dt>Latest version:
34:
35: <dd><a
36: href="http://www.w3.org/TR/selectors-api/">http://www.w3.org/TR/selectors-api/</a>
37:
38: <dt>Previous version:
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:
71: <p>This specification defines two methods for retrieving
72: <code>Element</code> nodes in the <abbr title="Document Object
73: Model">DOM</abbr> using a group of selectors as defined in [<cite><a
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:
84: <p><strong>This is the editor's copy of the specification and has no
85: official standing.</strong></p>
86: <!-- This document is produced by the <a href="http://www.w3.org/2006/webapi">Web API <abbr title="Working Group">WG</abbr></a>, part of the <a href="http://www.w3.org/2006/rwc/Activity">Rich Web Clients Activity</a> in the W3C <a href="http://www.w3.org/Interaction/">Interaction Domain</a>. -->
87:
88: <p>Web content and browser developers are encouraged to review this draft.
89: Please send comments to <a
90: href="mailto:public-webapi@w3.org">public-webapi@w3.org</a>, the W3C's
91: public email list for issues related to Web APIs. <a
92: href="http://lists.w3.org/Archives/Public/public-webapi/">Archives</a> of
93: the list are available. The editor's copy of this specification is <a
1.3 ! avankest 94: href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/selectors-api/Overview.html?content-type=text/html;%20charset=utf-8">available
1.1 avankest 95: in W3C CVS</a>. A detailed list of changes is also available <a
96: href="http://dev.w3.org/cvsweb/2006/webapi/selectors-api/">from the CVS
97: server</a>.
98:
99: <p>Implementors should be aware that this specification is not stable.
100: <strong>Implementors who are not taking part in the discussions are likely
101: to find the specification changing out from under them in incompatible
102: ways.</strong> Vendors interested in implementing this specification
103: before it eventually reaches the Candidate Recommendation stage should
104: join the aforementioned mailing lists and take part in the discussions.
105:
106: <p>This document was produced by a group operating under the <a
107: href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
108: 2004 W3C Patent Policy</a>. W3C maintains a <a
109: href="http://www.w3.org/2004/01/pp-impl/38482/status"
110: rel="disclosure">public list of any patent disclosures</a> made in
111: connection with the deliverables of the group; that page also includes
112: instructions for disclosing a patent. An individual who has actual
113: knowledge of a patent which the individual believes contains <a
114: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
115: Claim(s)</a> must disclose the information in accordance with <a
116: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
117: 6 of the W3C Patent Policy</a>.
118:
119: <h2 class="no-num no-toc" id="toc">Table of Contents</h2>
120: <!--begin-toc-->
121:
122: <ul class="toc">
123: <li><a href="#introduction"><span class="secno">1. </span>Introduction</a>
124:
125: <ul class="toc">
126: <li><a href="#examples"><span class="secno">1.1. </span>Examples</a>
127:
128: <li><a href="#conformance"><span class="secno">1.2. </span>Conformance
129: Requirements</a>
130:
131: <li><a href="#issues"><span class="secno">1.3. </span>Outstanding
132: Issues</a>
133: </ul>
134:
135: <li><a href="#interfaces"><span class="secno">2. </span>Interfaces</a>
136: <ul class="toc">
137: <li><a href="#documentselector"><span class="secno">2.1. </span>The
138: <code>DocumentSelector</code> Interface</a>
139: <ul class="toc">
140: <li><a href="#extensibility"><span class="secno">2.1.1.
141: </span>Extensibility</a>
142: </ul>
143:
144: <li><a href="#staticnodelist"><span class="secno">2.2. </span>The
145: <code>StaticNodeList</code> Interface</a>
146: </ul>
147:
148: <li><a href="#security"><span class="secno">3. </span>Security
149: Considerations</a>
150:
151: <li class="no-num"><a href="#references">References</a>
152:
153: <li class="no-num"><a href="#acknowledgements">Acknowledgements</a>
154: </ul>
155: <!--end-toc-->
156:
157: <h2 id="introduction"><span class="secno">1. </span>Introduction</h2>
158:
159: <p><em>This section is non-normative.</em>
160:
161: <p>It is often desirable to perform script and or DOM operations on a
162: specific set of elements in a document. [<cite><a
163: href="#ref-selectors">Selectors</a></cite>], mostly used in <abbr
164: title="Cascading Style Sheets">CSS</abbr> [<cite><a
165: href="#ref-css21">CSS21</a></cite>] context, provides a way of matching
166: such a set of elements. This specification introduces two methods which
167: take a group of selectors (often referred to as selector) as argument and
168: return the matched elements as result.
169:
170: <h3 id="examples"><span class="secno">1.1. </span>Examples</h3>
171:
172: <p><em>This section is non-normative.</em>
173:
174: <p>Some ECMAScript [<cite><a href="#ref-ecma262">ECMA262</a></cite>]
175: examples:
176:
177: <pre>function resolver(str) {
178: var prefixes = {
179: xh: "http://www.w3.org/1999/xhtml",
180: svg: "http://www.w3.org/2000/svg"}
181: return prefixes[str];
182: }
183: var <var>a</var> = document.matchAll("xh|div > svg|svg", resolver);
184: var <var>b</var> = document.match("div.foo.bar");</pre>
185:
186: <p><var>a</var> contains a <code>StaticNodeList</code> of all the nodes
187: matched by <code>xh|div > svg|svg</code> (namespace prefixes are
188: resolved using the function in this case). <var>b</var> would contain the
189: first <code>div</code> element which has the classes <code>foo</code> and
190: <code>bar</code> set. (So in case of multiple <code>div</code> elements
191: matching <code>div.foo.bar</code> only the first is returned because
192: <code><a href="#match">match</a></code> is used and not <code><a
193: href="#matchall">matchAll</a></code>.)
194:
195: <pre>function test(){
196: var c = document.matchAll(":root"),
197: d = document.documentElement;
198: return c[0] === d;
199: }</pre>
200:
201: <p><code>test()</code> would return <code>true</code> when both <code><a
202: href="#matchall">matchAll</a></code> and <code>:root</code> are supported.
203:
204: <p class="note">When using <code>:root</code> like this it's probably
205: better (and faster) to use <code><a href="#match">match</a></code> given
206: that there's only one possible result. This is just to illustrate how it
207: works.
208:
209: <pre>var <var>e</var> = document.matchAll("p.warning, p.alert");</pre>
210:
211: <p>The above code snippet shows that besides using a single selector you
212: can also pass a group of selectors (basically comma-separated selectors)
213: as argument. <var>e</var> would contain a <code>StaticNodeList</code> with
214: all <code>p</code> elements in the document that have a
215: <code>warning</code> or <code>alert</code> class.
216:
217: <h3 id="conformance"><span class="secno">1.2. </span>Conformance
218: Requirements</h3>
219:
220: <p>Everying in this specification is normative except for diagrams,
221: examples, notes and sections marked non-normative.
222:
223: <p>The key words <em class="ct">must</em>, <em class="ct">must not</em>,
224: <em class="ct">required</em>, <em class="ct">shall</em>, <em
225: class="ct">shall not</em>, <em class="ct">should</em>, <em
226: class="ct">should not</em>, <em class="ct">recommended</em>, <em
227: class="ct">may</em>, and <em class="ct">optional</em> in the normative
228: parts of this document are to be interpreted as described in [<cite><a
229: href="#ref-rfc2119">RFC2119</a></cite>].
230:
231: <p>The following conformance classes are defined by this specification:
232:
233: <dl>
234: <dt><dfn id="conforming">conforming implementation</dfn>
235:
236: <dd>A UA that implements all interfaces described in this specification
237: and follows all <em class="ct">must</em>-, <em class="ct">required</em>-
238: and <em class="ct">shall</em>-level of critera in this specification.
239:
240: <dt><dfn id="conforming0">conforming document</dfn>
241:
242: <dd>A document that follows all <em class="ct">must</em>-, <em
243: class="ct">required</em>- and <em class="ct">shall</em>-level of critera
244: in this specification that apply to document authors.
245:
246: <dt><dfn id="conforming1">conforming authoring tool</dfn>
247:
248: <dd>One that produces conforming documents.
249: </dl>
250:
251: <h3 id="issues"><span class="secno">1.3. </span>Outstanding Issues</h3>
252:
253: <p><em>This section is non-normative.</em>
254:
255: <p>The draft has several outstanding issues that either need to be
256: addressed in one way or another at some point:
257:
258: <ul>
259: <li>Several people have raised issues with naming the methods <code><a
260: href="#match">match</a></code> and <code><a
261: href="#matchall">matchAll</a></code> as those might suggest a boolean
262: return value. Alternate suggestions have been <code>select</code> and
263: <code>selectAll</code>.
264:
265: <li>There was at least one request for scoped selectors. For example,
266: being able to do <code>event.target.match()</code> or in other words
267: allowing the methods on <code>Element</code> nodes. Given that Selectors
268: itself has no notion of scoped selectors this might be difficult to
269: define and is perhaps better delayed until the CSS WG has defined scoped
270: selectors.
271:
272: <li>It would be nice if extensibility was addressed by DOM Level 3 Core or
273: a separate specification that all DOM specifications could reuse.
274:
275: <li>Need to look into <code>XPathNSResolver</code> and the default
276: namespace.
277:
278: <li>If DOM Level 3 Core gets errata we might be able to get away with not
279: having a new interface at all for <code>NodeList</code>
280: (<code>StaticNodeList</code>), but just say that the object implementing
281: the <code>NodeList</code> interface is not live.
282: </ul>
283:
284: <h2 id="interfaces"><span class="secno">2. </span>Interfaces</h2>
285:
286: <h3 id="documentselector"><span class="secno">2.1. </span>The
287: <code>DocumentSelector</code> Interface</h3>
288:
289: <p>Objects implementing the <code>Document</code> interface defined in
290: <cite>DOM Level 3 Core</cite> <em class="ct">must</em> also implement the
291: <code>DocumentSelector</code> interface [<cite><a
292: href="#ref-dom3core">DOM3Core</a></cite>].
293:
294: <pre class="idl">interface DocumentSelector {
295: Node match(in DOMString <var>selectors</var>, in XPathNSResolver <var>nsresolver</var>);
296: StaticNodeList matchAll(in DOMString <var>selectors</var>, in XPathNSResolver <var>nsresolver</var>);
297: };</pre>
298:
299: <p>The <dfn id="match"><code>match</code></dfn> method, when invoked, <em
1.2 avankest 300: class="ct">must</em> return the first <code>Element</code> node in
301: document order (using depth-first pre-order traversal) that matches the
302: group of selectors (<var>selectors</var>), if any. Otherwise it <em
303: class="ct">must</em> return <code>null</code>.
1.1 avankest 304:
305: <p>The <dfn id="matchall"><code>matchAll</code></dfn> method, when invoked,
306: <em class="ct">must</em> return a <code>StaticNodeList</code> of all the
307: <code>Element</code>s that match the group of selectors
1.2 avankest 308: (<var>selectors</var>) in document order, if any. Otherwise it <em
309: class="ct">must</em> return <code>null</code>.
1.1 avankest 310:
311: <p>Both <code><a href="#match">match</a></code> and <code><a
312: href="#matchall">matchAll</a></code> take a group of selectors
313: (<var>selectors</var>) as defined in [<cite><a
314: href="#ref-selectors">Selectors</a></cite>] as first argument and an
315: <code>XPathNSResolver</code> (<var>nsresolver</var>) as second. UAs <em
316: class="ct">must</em> use the <var>nsresolver</var> argument to resolve
317: namespace prefixes as defined in [<cite><a
318: href="#ref-dom3xpath">DOM3XPath</a></cite>]. When the
319: <var>nsresolver</var> argument is <code>null</code> UAs <em
320: class="ct">must</em> ignore it.
321:
322: <p>When authors use namespace prefixes within <var>selectors</var> they <em
323: class="ct">must</em> create an object implementing the
324: <code>XPathNSResolver</code> interface (or create a <code>Function</code>
325: in case of ECMAScript) and pass that as argument for
326: <code>nsresolver</code> as defined in in [<cite><a
327: href="#ref-dom3xpath">DOM3XPath</a></cite>]. If they don't use namespace
328: prefixes within <var>selectors</var> authors <em class="ct">may</em> set
329: <var>nsresolver</var> to <code>null</code> or omit the argument completely
330: if the language binding allows it.
331:
332: <p class="issue">Make sure [DOM3XPath] actually defines this. Otherwise
333: this draft will have to. (Which is needed anyway when this goes beyond
334: Last Call and DOM Level 3 XPath does not.)
335:
336: <p>If the given group of selectors (<var>selectors</var>) is invalid, the
337: UA <em class="ct">must</em> raise a <code>SYNTAX_ERR</code> exception. If
338: the given group of selectors (<var>selectors</var>) uses namespace
339: prefixes and the prefix can not be resolved using the
340: <var>nsresolver</var> argument UAs <em class="ct">must</em> raise a
341: <code>NAMESPACE_ERR</code> exception.
342:
343: <p class="note">Using psuedo-elements in one of the selectors could mean
344: that nothing is returned for that particular selector when it doesn't
345: resolve in one or more <code>Element</code> nodes.
346:
347: <p>In languages that support optional arguments for methods, like
348: ECMAScript, omitting the <var>nsresolver</var> argument in either the
349: <code><a href="#match">match</a></code> or <code><a
350: href="#matchall">matchAll</a></code> method <em class="ct">must</em>
351: return the same result as if the method was called with the
352: <var>nsresolver</var> argument being <code>null</code>.
353:
354: <h4 id="extensibility"><span class="secno">2.1.1. </span>Extensibility</h4>
355:
356: <p>Extensions to the <code>DocumentSelector</code> interface are reserved
357: for future work by the Web APIs WG. WGs besides the Web APIs WG <em
358: class="ct">may</em> extend the interface, but <em class="ct">must</em>
359: coordinate that with the Web APIs WG. UAs <em class="ct">may</em> extend
360: the interface, but <em class="ct">must</em> prefix the new members using a
361: string specific to the vendor following the
362: <var>Vendor</var><var>Member</var> scheme. (Normally members follow the
363: <var>member</var> scheme.)
364: <code>FooSetDefaultNamespace(<var>ns</var>)</code> would be an example for
365: company Foo.
366:
367: <p>Authors <em class="ct">may</em> use extension mechanisms specific to the
368: host language, like <code>.prototype</code> in ECMAScript.
369:
370: <h3 id="staticnodelist"><span class="secno">2.2. </span>The
371: <code>StaticNodeList</code> Interface</h3>
372:
373: <p class="issue">Replace with <code>DOMArray</code>?
374:
375: <pre class="idl">typedef StaticNodeList NodeList;</pre>
376:
377: <p>The <code>StaticNodeList</code> <em class="ct">must</em> be implemented
378: identically to the <code>NodeList</code> interface as defined in [<cite><a
379: href="#ref-dom3core">DOM3Core</a></cite>] with the exception that the
380: interface, as the name suggests, is static and not live.
381:
382: <h2 id="security"><span class="secno">3. </span>Security Considerations</h2>
383:
384: <p>It is expected that implementing this specification introduces no new
385: risks for users.
386:
387: <p>History theft is a potential security problem, because of the
388: <code>:visited</code> pseudo-class in [<cite><a
389: href="#ref-selectors">Selectors</a></cite>]. <code>:visited</code> can
390: already be used to query which links are visited and which are not using
391: methods from [<cite><a href="#ref-dom2style">DOM2Style</a></cite>] and
392: even [<cite><a href="#ref-css21">CSS21</a></cite>] and because this
393: specification did not introduce the problem and it can already be
394: exploited by other means UAs don't have to take action upon it.
395:
396: <p>Another problem is hostile content. UAs <em class="ct">should</em>
397: ensure they remain stable when facing a hostile
398: <code>XPathNSResolver</code> object. Potential hostile things such an
399: object could do include:
400:
401: <ul>
402: <li>Returning inconsistent results;
403:
404: <li>Hanging;
405:
406: <li>Changing the DOM during the operation.
407: </ul>
408:
409: <p class="issue">It was said that this section is in need of examples...
410:
411: <h2 class="no-num" id="references">References</h2>
412:
413: <dl>
414: <dt id="ref-css21">[CSS21]
415:
416: <dd>(Informative) <cite><a href="http://www.w3.org/TR/CSS21">Cascading
417: Style Sheets, level 2 revision 1</a></cite>, B. Bos, T. Çelik, I.
418: Hickson, H. Wium Lie, editors. World Wide Web Consortium, June 2005.
419:
420: <dt id="ref-dom2style">[DOM2Style]
421:
422: <dd>(Informative) <cite><a
423: href="http://www.w3.org/TR/DOM-Level-2-Style">Document Object Model (DOM)
424: Level 2 Style Specification</a></cite>, C. Wilson, P. Le Hégaret, V.
425: Apparao, editors. World Wide Web Consortium, November 2000.
426:
427: <dt id="ref-dom3core">[DOM3Core]
428:
429: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-Core">Document Object
430: Model (DOM) Level 3 Core Specification</a></cite>, A. Le Hors, P. Le
431: Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors.
432: World Wide Web Consortium, April 2004.
433:
434: <dt id="ref-dom3xpath">[DOM3XPath]
435:
436: <dd><cite><a href="http://www.w3.org/TR/DOM-Level-3-XPath">Document Object
437: Model (DOM) Level 3 XPath Specification</a></cite>, R. Whitmer, editor.
438: World Wide Web Consortium, February 2004.
439:
440: <dt id="ref-ecma262">[ECMA262]
441:
442: <dd><cite><a
443: href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript
444: Language Specification</a></cite>, Third Edition. ECMA, December 1999.
445:
446: <dt id="ref-selectors">[Selectors]
447:
448: <dd><cite><a
449: href="http://www.w3.org/TR/css3-selectors">Selectors</a></cite>, D.
450: Glazman, T. Çelik, I. Hickson, P. Linss, J. Williams, editors. World
451: Wide Web Consortium, December 2005.
452:
453: <dt id="ref-rfc2119">[RFC2119]
454:
455: <dd><cite><a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119: Key
456: words for use in RFCs to Indicate Requirement Levels</a></cite>, S.
457: Bradner. IETF, March 1997.
458: </dl>
459:
460: <h2 class="no-num" id="acknowledgements">Acknowledgements</h2>
461:
462: <ul>
463: <li>Björn Höhrmann
464:
465: <li>Cameron McCormack
466:
467: <li>Daniel Schierbeck
468:
469: <li>Dean Jackson
470:
471: <li>Ian Hickson
472:
473: <li>Jim Ley
474:
475: <li>Jonas Sicking
476:
477: <li>Lachlan Hunt
478:
479: <li>Maciej Stachowiak
480:
481: <li>Mohamed Zergaoui
482:
483: <li>Robin Berjon
484: </ul>
485:
486: <p>Thanks to all those who have helped to improve this specification by
487: sending suggestions and corrections. (Please, keep bugging us with your
488: issues!)
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to Overview.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / 2006 / webapi / selectors-api