Annotation of 2006/webapi/selectors-api/Overview.html, revision 1.65
1.1 avankest 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2:
1.11 avankest 3: <html lang=en-US>
1.20 lhunt 4: <head><meta content="text/html;charset=UTF-8" http-equiv=Content-Type>
5:
1.1 avankest 6: <title>Selectors API</title>
7:
8: <style type="text/css">
1.36 lhunt 9: pre.idl { border:solid thin; background:#eee; color:#000; padding:0.5em }
1.50 lhunt 10: pre.idl :link, pre.idl :visited { color:inherit; background:transparent }
1.20 lhunt 11:
1.36 lhunt 12: div.example { border-left:double; padding-left:1em }
13: dfn { font-style:normal; font-weight:bolder }
14: em.ct { font-style:normal; font-weight:normal; font-variant:small-caps }
15: p.note { margin-left:2em; color:green; font-style:italic; font-weight:bold }
16: p.note:before { content:"Note: " }
17: .issue { padding:.5em; border:solid red }
18: .issue:before { content:"Issue: " }
19: code { color:#FF4500; }
20: code :link, code :visited { color:inherit }
21: </style>
1.41 lhunt 22: <link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel=stylesheet
1.29 lhunt 23: type="text/css">
1.1 avankest 24:
25: <body>
1.11 avankest 26: <div class=head>
1.31 lhunt 27: <p><a href="http://www.w3.org/"><img alt=W3C height=48
28: src="http://www.w3.org/Icons/w3c_home" width=72></a></p>
1.1 avankest 29:
1.46 lhunt 30: <h1 id=title>Selectors API</h1>
1.12 avankest 31: <!-- "DOM Selectors" was not acceptable. "DOM Level 4 Selectors" and
1.36 lhunt 32: conforming to the DOM specification template (if there is such a thing) is
33: just silly so we got stuck with this weird name. -->
1.12 avankest 34:
1.65 ! lhunt 35: <h2 class="no-num no-toc" id=W3C-doctype>W3C Working Draft 16 July 2008</h2>
1.1 avankest 36:
37: <dl>
1.5 avankest 38: <dt>This Version:
1.1 avankest 39:
1.11 avankest 40: <dd><a
1.65 ! lhunt 41: href="http://www.w3.org/TR/2008/ED-selectors-api-20080716/">http://www.w3.org/TR/2008/ED-selectors-api-20080716/</a>
1.1 avankest 42:
1.5 avankest 43: <dt>Latest Version:
1.1 avankest 44:
45: <dd><a
46: href="http://www.w3.org/TR/selectors-api/">http://www.w3.org/TR/selectors-api/</a>
47:
1.12 avankest 48: <dt>Previous Versions:
49:
50: <dd><a
1.44 lhunt 51: href="http://www.w3.org/TR/2007/WD-selectors-api-20071221/">http://www.w3.org/TR/2007/WD-selectors-api-20071221/</a>
52:
53: <dd><a
1.31 lhunt 54: href="http://www.w3.org/TR/2007/WD-selectors-api-20071019/">http://www.w3.org/TR/2007/WD-selectors-api-20071019/</a>
1.29 lhunt 55:
56: <dd><a
1.12 avankest 57: href="http://www.w3.org/TR/2006/WD-selectors-api-20060926/">http://www.w3.org/TR/2006/WD-selectors-api-20060926/</a>
1.1 avankest 58:
59: <dd><a
60: href="http://www.w3.org/TR/2006/WD-selectors-api-20060525/">http://www.w3.org/TR/2006/WD-selectors-api-20060525/</a>
61:
1.20 lhunt 62: <dt>Editors:
63:
1.46 lhunt 64: <dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a> (<a
65: href="http://www.opera.com/">Opera Software ASA</a>) <<a
66: href="mailto:annevk@opera.com">annevk@opera.com</a>>
67:
1.29 lhunt 68: <dd><a href="http://lachy.id.au/">Lachlan Hunt</a> (<a
69: href="http://www.opera.com/">Opera Software ASA</a>) <<a
1.20 lhunt 70: href="mailto:lachlan.hunt@lachy.id.au">lachlan.hunt@lachy.id.au</a>>
1.1 avankest 71: </dl>
72:
1.11 avankest 73: <p class=copyright><a
1.1 avankest 74: href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
1.44 lhunt 75: © 2006-2007 <a href="http://www.w3.org/"><acronym title="World Wide Web
76: Consortium">W3C</acronym></a><sup>®</sup> (<a
1.31 lhunt 77: href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute
78: of Technology">MIT</acronym></a>, <a
79: href="http://www.ercim.org/"><acronym title="European Research Consortium
80: for Informatics and Mathematics">ERCIM</acronym></a>, <a
81: href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
82: href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
83: <a
84: href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
85: and <a
86: href="http://www.w3.org/Consortium/Legal/copyright-documents">document
87: use</a> rules apply.</p>
1.33 lhunt 88: </div>
1.1 avankest 89:
90: <hr>
91:
1.11 avankest 92: <h2 class="no-num no-toc" id=abstract>Abstract</h2>
1.1 avankest 93:
1.23 lhunt 94: <p>Selectors, which are widely used in CSS, are patterns that match against
1.54 lhunt 95: elements in a tree structure <a href="#SELECT"
96: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a><a href="#CSS21"
97: rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>. The Selectors API
98: specification defines methods for retrieving <code>Element</code> nodes
99: from the <abbr title="Document Object Model">DOM</abbr> by matching
100: against a group of selectors. It is often desirable to perform DOM
101: operations on a specific set of elements in a document. These methods
102: simplify the process of acquiring specific elements, especially compared
103: with the more verbose techniques defined and used in the past.
1.1 avankest 104:
1.11 avankest 105: <h2 class="no-num no-toc" id=sotd>Status of this Document</h2>
1.1 avankest 106:
107: <p><em>This section describes the status of this document at the time of
108: its publication. Other documents may supersede this document. A list of
109: current W3C publications and the latest revision of this technical report
110: can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
111: index</a> at http://www.w3.org/TR/.</em>
112:
1.57 lhunt 113: <p>This is an Editor's Draft of "Selectors API". The W3C Membership and
114: other interested parties are invited to review the document and send
115: comments to <a
116: href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a
117: href="http://lists.w3.org/Archives/Public/public-webapps/">public
118: archive</a>) with <kbd>[selectors-api]</kbd> in the subject
1.29 lhunt 119:
120: <p><span class=notetoeditor>Web content and browser developers are
121: encouraged to review this draft. This draft is considered relatively
122: stable and is expected to progress to Candidate Recommendation after the
1.44 lhunt 123: review period.</span> The editor’s copy of this specification is <a
1.30 lhunt 124: href="http://dev.w3.org/2006/webapi/selectors-api/">available in W3C
125: CVS</a>. A detailed list of changes is also available <a
1.1 avankest 126: href="http://dev.w3.org/cvsweb/2006/webapi/selectors-api/">from the CVS
1.29 lhunt 127: server</a>.
1.1 avankest 128:
1.29 lhunt 129: <p>This document was developed by the <a
1.57 lhunt 130: href="http://www.w3.org/2008/webapps/">Web Applications Working Group</a>.
131: The Working Group expects to advance this Working Draft to Recommendation
1.29 lhunt 132: Status.
133:
134: <p>Publication as a Working Draft does not imply endorsement by the W3C
135: Membership. This is a draft document and may be updated, replaced or
136: obsoleted by other documents at any time. It is inappropriate to cite this
137: document as other than work in progress.
1.1 avankest 138:
139: <p>This document was produced by a group operating under the <a
140: href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
141: 2004 W3C Patent Policy</a>. W3C maintains a <a
142: href="http://www.w3.org/2004/01/pp-impl/38482/status"
1.11 avankest 143: rel=disclosure>public list of any patent disclosures</a> made in
1.1 avankest 144: connection with the deliverables of the group; that page also includes
145: instructions for disclosing a patent. An individual who has actual
146: knowledge of a patent which the individual believes contains <a
147: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
1.31 lhunt 148: Claim(s)</a> must disclose the information in accordance with <a
1.1 avankest 149: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
150: 6 of the W3C Patent Policy</a>.
151:
1.11 avankest 152: <h2 class="no-num no-toc" id=toc>Table of Contents</h2>
1.1 avankest 153: <!--begin-toc-->
154:
1.11 avankest 155: <ul class=toc>
156: <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
157: <ul class=toc>
1.36 lhunt 158: <li><a href="#examples"><span class=secno>1.1 </span>Examples</a>
1.49 lhunt 159: </ul>
1.1 avankest 160:
1.49 lhunt 161: <li><a href="#conformance"><span class=secno>2. </span>Conformance
162: Requirements</a>
163: <ul class=toc>
164: <li><a href="#terminology"><span class=secno>2.1 </span>Terminology and
165: Conventions</a>
166: </ul>
1.1 avankest 167:
1.49 lhunt 168: <li><a href="#interoperability"><span class=secno>3.
169: </span>Interoperability Considerations</a>
170: <ul class=toc>
171: <li><a href="#extensibility"><span class=secno>3.1
172: </span>Extensibility</a>
173: </ul>
174:
175: <li><a href="#security"><span class=secno>4. </span>Security
176: Considerations</a>
1.21 lhunt 177:
1.49 lhunt 178: <li><a href="#privacy"><span class=secno>5. </span>Privacy Considerations
179: </a>
1.1 avankest 180:
1.55 lhunt 181: <li><a href="#nodeselector"><span class=secno>6. </span>The <code
182: title="">NodeSelector</code> Interface</a>
1.16 avankest 183: <ul class=toc>
1.50 lhunt 184: <li><a href="#resolving"><span class=secno>6.1 </span>Resolving
185: Namespaces</a>
1.51 lhunt 186: </ul>
1.50 lhunt 187:
1.64 lhunt 188: <li><a href="#dom-feature"><span class=secno>7. </span>DOM Feature
189: String</a>
190:
191: <li><a href="#examples0"><span class=secno>8. </span>Examples</a>
192:
1.11 avankest 193: <li class=no-num><a href="#references">References</a>
1.54 lhunt 194: <ul class=toc>
195: <li class=no-num><a href="#normative-references">Normative
196: references</a>
197:
198: <li class=no-num><a href="#other-references">Other references</a>
199: </ul>
1.1 avankest 200:
1.11 avankest 201: <li class=no-num><a href="#acknowledgements">Acknowledgements</a>
1.1 avankest 202: </ul>
203: <!--end-toc-->
204:
1.11 avankest 205: <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
1.1 avankest 206:
207: <p><em>This section is non-normative.</em>
208:
1.20 lhunt 209: <p>This specification introduces two methods that take a group of selectors
1.24 lhunt 210: (often simply referred to as a selector) as an argument and return the
1.54 lhunt 211: matching elements <a href="#SELECT"
212: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>. With these methods, it is
213: easier to match a set of <code>Element</code> nodes based on specific
214: criteria. So instead of having to filter the result of a
215: <code>getElementsByTagName()</code> call, authors can directly
1.44 lhunt 216: “filter” in the query.
1.10 avankest 217:
1.36 lhunt 218: <h3 id=examples><span class=secno>1.1 </span>Examples</h3>
1.1 avankest 219:
220: <p><em>This section is non-normative.</em>
221:
1.54 lhunt 222: <p>Some ECMAScript <a href="#ECMA-262"
223: rel=biblioentry>[ECMA-262]<!--{{ECMA-262}}--></a> examples:
1.1 avankest 224:
1.14 avankest 225: <div class=example>
1.41 lhunt 226: <p>This is an example table written in HTML 4.01.</p>
1.22 lhunt 227:
1.20 lhunt 228: <pre><table id="score">
229: <thead>
230: <tr>
231: <th>Test
232: <th>Result
233: <tfoot>
234: <tr>
235: <th>Average
236: <td>82%
237: <tbody>
238: <tr>
239: <td>A
240: <td>87%
241: <tr>
242: <td>B
243: <td>78%
244: <tr>
245: <td>C
246: <td>81%
247: </table></pre>
248:
249: <p>In order to obtain the cells containing the results in the table, which
250: might be done, for example, to plot the values on a graph, there are at
251: least two approaches that may be taken. Using only the APIs from DOM
252: Level 2, it requires a script like the following that iterates through
253: each <code>tr</code> within each <code>tbody</code> in the
254: <code>table</code> to find the second cell of each row.</p>
255:
256: <pre>var table = document.getElementById("score");
1.23 lhunt 257: var groups = table.tBodies;
258: var rows = null;
1.24 lhunt 259: var cells = [];
1.20 lhunt 260:
1.23 lhunt 261: for (var i = 0; i < groups.length; i++) {
262: rows = groups[i].rows;
263: for (var j = 0; j < rows.length; j++) {
264: cells.push(rows[j].cells[1]);
1.20 lhunt 265: }
1.36 lhunt 266: }</pre>
1.20 lhunt 267:
1.46 lhunt 268: <p>Alternatively, using the <code
269: title=document-selectallelements>querySelectorAll()</code> method, that
270: script becomes much more concise.</p>
1.20 lhunt 271:
1.36 lhunt 272: <pre>var cells = document.querySelectorAll("#score>tbody>tr>td:nth-of-type(2)");</pre>
1.41 lhunt 273:
274: <p>This script will also function correctly for a table written in XHTML
275: markup instead of HTML.</p>
1.20 lhunt 276: </div>
277:
1.49 lhunt 278: <h2 id=conformance><span class=secno>2. </span>Conformance Requirements</h2>
1.1 avankest 279:
1.21 lhunt 280: <p>All diagrams, examples and notes in this specification are
1.20 lhunt 281: non-normative, as are all sections explicitly marked non-normative.
282: Everything else in this specification is normative.
1.1 avankest 283:
1.23 lhunt 284: <p>The key words <em class=ct>must</em>, <em class=ct>should</em>, and <em
285: class=ct>may</em> in the normative parts of this document are to be
1.54 lhunt 286: interpreted as described in RFC 2119 <a href="#RFC2119"
287: rel=biblioentry>[RFC2119]<!--{{!RFC2119}}--></a>.
1.1 avankest 288:
1.11 avankest 289: <p>The following conformance classes are defined (and considered) by this
290: specification:
1.1 avankest 291:
292: <dl>
1.22 lhunt 293: <dt><dfn id=conforming>conforming user agent</dfn>
1.1 avankest 294:
1.48 lhunt 295: <dd>A user agent that implements the <code><a
1.65 ! lhunt 296: href="#dom-document-selector">NodeSelector</a></code> interface described
! 297: in this specification and conforms to all <em class=ct>must</em>-level
! 298: criteria that apply to implementations.
1.22 lhunt 299:
1.65 ! lhunt 300: <dt><dfn id=conforming0>conforming application</dfn>
1.22 lhunt 301:
302: <dd>An application that uses the interfaces defined in this specification
1.36 lhunt 303: and conforms to all <em class=ct>must</em>-level criteria that apply to
304: applications.
1.1 avankest 305: </dl>
306:
1.49 lhunt 307: <h3 id=terminology><span class=secno>2.1 </span>Terminology and Conventions</h3>
1.16 avankest 308:
1.54 lhunt 309: <p>The terminology used in this specification is that from Selectors <a
310: href="#SELECT" rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>.
1.16 avankest 311:
1.23 lhunt 312: <p>Conformance requirements phrased as algorithms or specific steps may be
1.65 ! lhunt 313: implemented in any manner, so long as the end result is equivalent.
1.16 avankest 314:
1.23 lhunt 315: <p>The construction "<code>Foo</code> object", where <code>Foo</code> is
316: actually an interface, is sometimes used instead of the more accurate
1.24 lhunt 317: "object implementing the <code>Foo</code> interface".
1.23 lhunt 318:
1.54 lhunt 319: <p>The IDL used in this specification uses the syntax defined in Web IDL <a
320: href="#DOM-BINDINGS"
321: rel=biblioentry>[DOM-BINDINGS]<!--{{!DOM-BINDINGS}}--></a>.
1.46 lhunt 322:
1.49 lhunt 323: <h2 id=interoperability><span class=secno>3. </span>Interoperability
324: Considerations</h2>
1.16 avankest 325:
1.23 lhunt 326: <p><em>This section is non-normative.</em>
327:
1.65 ! lhunt 328: <p>Some implementations might have different levels of support for
! 329: Selectors. If some implementations lack support for some selectors, then
! 330: if those selectors are used, such implementations could return different
! 331: results from those that do support them.
1.19 avankest 332:
1.49 lhunt 333: <h3 id=extensibility><span class=secno>3.1 </span>Extensibility</h3>
1.5 avankest 334:
335: <p><em>This section is non-normative.</em>
336:
337: <p>Extensions of the APIs defined in this specification are <em>strongly
1.36 lhunt 338: discouraged</em>. Implementors, Working Groups and other interested
339: parties should discuss extensions on a relevant public forum, such as <a
1.57 lhunt 340: href="mailto:public-webapps@w3.org">public-webapps@w3.org</a>.
1.5 avankest 341:
1.49 lhunt 342: <h2 id=security><span class=secno>4. </span>Security Considerations</h2>
1.11 avankest 343:
344: <p>It is expected that implementing this specification introduces no new
1.21 lhunt 345: security risks for users.
346:
1.62 lhunt 347: <p>If, at any time, the implementation detects a situation which would
348: violate security policies, the implementation MAY abort and raise a
349: security exception. If any other error condition occurs which is not
350: covered directly by this or any other relevant specification, the
351: implementation <em class=ct>MAY</em> abort and raise an appropriate,
352: language-binding-specific or implementation-specific exception.
353:
1.49 lhunt 354: <h2 id=privacy><span class=secno>5. </span>Privacy Considerations</h2>
1.11 avankest 355:
1.20 lhunt 356: <p>History theft is a potential privacy issue because the
1.54 lhunt 357: <code>:visited</code> pseudo-class in Selectors <a href="#SELECT"
358: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a> allows authors to query
359: which links have been visited.
1.20 lhunt 360:
361: <p class=note>This is not a new problem, as it can already be exploited
362: using existing CSS and DOM APIs, such as <code>getComputedStyle()</code>
1.54 lhunt 363: <a href="#DOM-LEVEL-2-STYLE"
364: rel=biblioentry>[DOM-LEVEL-2-STYLE]<!--{{DOM-LEVEL-2-STYLE}}--></a>.
1.20 lhunt 365:
366: <div class=example>
1.36 lhunt 367: <p>In this example, <var>vlinks</var> will acquire a list of links that
368: the user has visited. The author can then obtain the URIs and potentially
1.20 lhunt 369: exploit this knowledge.</p>
370:
1.27 lhunt 371: <pre>var vlinks = document.querySelectorAll(":visited");
1.20 lhunt 372: for (var i = 0; i < vlinks.length; i++) {
373: doSomethingEvil(vlinks[i].href);
374: }</pre>
375: </div>
376:
377: <p>As <a href="http://www.w3.org/TR/css3-selectors/#link">defined in
1.54 lhunt 378: <cite>Selectors</cite></a> (<a href="#SELECT"
379: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>, section 6.6.1), user
380: agents <em class=ct>may</em> treat all links as unvisited links. It is <em
1.47 lhunt 381: class=ct>recommended</em> that implementations behave consistently with
382: other uses of Selectors supported by the user agent.
1.11 avankest 383:
1.55 lhunt 384: <h2 id=nodeselector><span class=secno>6. </span>The <code
385: title="">NodeSelector</code> Interface</h2>
1.16 avankest 386:
1.46 lhunt 387: <p>Objects implementing either the <code>Document</code>,
388: <code>DocumentFragment</code> or <code>Element</code> interfaces, as
1.36 lhunt 389: defined in DOM Level 3 Core, <em class=ct>must</em> also implement the
1.46 lhunt 390: <code><a href="#dom-document-selector">NodeSelector</a></code> interface.
1.54 lhunt 391: <a href="#DOM-LEVEL-3-CORE"
392: rel=biblioentry>[DOM-LEVEL-3-CORE]<!--{{!DOM-LEVEL-3-CORE}}--></a>
1.1 avankest 393:
1.59 lhunt 394: <pre
395: class=idl>[NoInterfaceObject] interface <dfn id=dom-document-selector>NodeSelector</dfn> {
1.61 lhunt 396: Element <a href="#queryselector" title=queryselector>querySelector</a>([Null=Empty, Undefined=Empty] in DOMString selectors);
1.65 ! lhunt 397: NodeList <a href="#queryselectorall" title=queryselectorall>querySelectorAll</a>([Null=Empty, Undefined=Empty] in DOMString selectors);
1.16 avankest 398: };
1.46 lhunt 399: </pre>
1.36 lhunt 400:
401: <p>The term <dfn id=first>first</dfn> used in the definitions of the
1.53 lhunt 402: <code><a href="#queryselector">querySelector</a></code> methods means
403: <em>first in document order</em>. The term <dfn id=document>document
404: order</dfn> means a depth-first pre-order traversal of the DOM tree or
405: subtree in question. The term <dfn id=context>context node</dfn> refers to
406: the node upon which the method was invoked. The term <dfn
407: id=nodes>node’s subtree</dfn> refers to the tree of elements that are
408: descendants of the <a href="#context">context node</a>. The term <dfn
409: id=matching>matching <code>Element</code> node</dfn> refers to an
410: <code>Element</code> node that matches the group of selectors
411: (<var>selectors</var>) that was passed to the method, according to the
1.54 lhunt 412: rules for matching elements defined in Selectors <a href="#SELECT"
1.65 ! lhunt 413: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>.
! 414:
! 415: <p>If the <a href="#context">context node</a> is a <code>Document</code>
! 416: node, then the <span>scope element</span> is the
! 417: <code>documentElement</code> of the given document. If the <a
! 418: href="#context">context node</a> is an <code>Element</code> node, then the
! 419: <span>scope element</span> is the same as the <a href="#context">context
! 420: node</a>.
! 421:
! 422: <p class=issue>The previous paragraph has been included to define which
! 423: element will be matched by the proposed <code>:scope</code> pseudo-class.
! 424: If and when that proposal is accepted, this will need an appropriate
! 425: reference.
1.53 lhunt 426:
427: <p>The <dfn id=queryselector
1.65 ! lhunt 428: title=queryselector><code>querySelector()</code></dfn> method on the
1.53 lhunt 429: <code><a href="#dom-document-selector">NodeSelector</a></code> interface
430: <em class=ct>must</em>, when invoked, return the first matching
1.46 lhunt 431: <code>Element</code> node within the node’s subtree. If there is no such
1.65 ! lhunt 432: node, the method <em class=ct>must</em> return <code>null</code>.
1.1 avankest 433:
1.53 lhunt 434: <p>The <dfn id=queryselectorall
1.65 ! lhunt 435: title=queryselectorall><code>querySelectorAll()</code></dfn> method on the
! 436: <code><a href="#dom-document-selector">NodeSelector</a></code> interface
! 437: <em class=ct>must</em>, when invoked, return a <code>NodeList</code>
! 438: containing all of the matching <code>Element</code> nodes within the
! 439: node’s subtree, in document order. If there are no such nodes, the
! 440: method <em class=ct>must</em> return an empty <code>NodeList</code>.
1.53 lhunt 441:
442: <p>Both <code title=queryselector><a
443: href="#queryselector">querySelector()</a></code> and <code
444: title=queryselectorall><a
1.65 ! lhunt 445: href="#queryselectorall">querySelectorAll()</a></code> take a <a
! 446: href="http://www.w3.org/TR/css3-selectors/#grouping">group of
! 447: selectors</a> (<var>selectors</var>) as their argument (<a href="#SELECT"
! 448: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>, section 5). The caller <em
! 449: class=ct>must</em> pass a valid group of selectors. The group of selectors
! 450: <em class=ct>must not</em> use <a href="#namespace"
! 451: title=need-to-resolve>namespace prefixes that need to be resolved</a>.
1.36 lhunt 452:
453: <p class=note>Authors are advised that while the use of pseudo-elements in
454: selectors is permitted, they will not match any elements in the document,
455: and thus would not result in any elements being returned. Therefore,
1.46 lhunt 456: authors should avoid the use of pseudo-elements in selectors that are
457: passed to the methods defined in this specification.
1.36 lhunt 458:
1.50 lhunt 459: <p>The implementation <em class=ct>must</em> first trim any leading or
1.61 lhunt 460: trailing <a href="http://www.w3.org/TR/css3-selectors/#whitespace"
1.65 ! lhunt 461: title=Selectors>whitespace</a> from the value of the <var>selectors</var>
! 462: parameter. The implementation <em class=ct>must</em> then process the
! 463: value according to <a
1.61 lhunt 464: href="http://www.w3.org/TR/css3-selectors/#w3cselgrammar">the grammar of
465: Selectors</a> (<a href="#SELECT"
1.65 ! lhunt 466: rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>, section 10). If the
! 467: <var>selectors</var> parameter is set to either <code>null</code> or
! 468: <code>undefined</code>, the implementation <em class=ct>must</em> behave
! 469: as if an empty string had been passed instead. Selectors are evaluated
! 470: against a given element in the context the entire DOM tree in which the
! 471: element is located. If the given group of selectors is <a
1.54 lhunt 472: href="http://www.w3.org/TR/css3-selectors/#Conformance">invalid</a> (<a
473: href="#SELECT" rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>, section
474: 13), the implementation <em class=ct>must</em> <a
1.25 lhunt 475: href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMException-SYNTAX_ERR">raise
1.54 lhunt 476: a <code>SYNTAX_ERR</code> exception</a> (<a href="#DOM-LEVEL-3-CORE"
477: rel=biblioentry>[DOM-LEVEL-3-CORE]<!--{{!DOM-LEVEL-3-CORE}}--></a>,
478: section 1.4).
1.20 lhunt 479:
1.50 lhunt 480: <p>If the user agent also supports some level of CSS, the implementation
481: <em class=ct>should</em> support the same set of selectors in both these
482: APIs and CSS.
1.1 avankest 483:
1.53 lhunt 484: <p>The <code>NodeList</code> object returned by the <code><a
1.65 ! lhunt 485: href="#queryselectorall">querySelectorAll()</a></code> method <em
1.53 lhunt 486: class=ct>must</em> be static, not <a
487: href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#td-live"
1.54 lhunt 488: title="Document Object Model Core">live</a>. (<a href="#DOM-LEVEL-3-CORE"
489: rel=biblioentry>[DOM-LEVEL-3-CORE]<!--{{!DOM-LEVEL-3-CORE}}--></a>,
490: section 1.1.1) Subsequent changes to the structure of the underlying
491: document <em class=ct>must not</em> be reflected in the
492: <code>NodeList</code> object. This means that the object will instead
493: contain a list of matching <code>Element</code> nodes that were in the
494: document at the time the list was created.
1.1 avankest 495:
1.50 lhunt 496: <h3 id=resolving><span class=secno>6.1 </span>Resolving Namespaces</h3>
497:
1.65 ! lhunt 498: <p>If the group of selectors include <a href="#namespace"
! 499: title=need-to-resolve>namespace prefixes that need to be resolved</a>, the
! 500: implementation must <a
! 501: href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMException-NAMESPACE_ERR">raise
! 502: a <code>NAMESPACE_ERR</code> exception</a> (<a href="#DOM-LEVEL-3-CORE"
1.54 lhunt 503: rel=biblioentry>[DOM-LEVEL-3-CORE]<!--{{!DOM-LEVEL-3-CORE}}--></a>,
504: section 1.4).
1.50 lhunt 505:
1.58 lhunt 506: <p>A <dfn id=namespace title=need-to-resolve>namespace prefix needs to be
507: resolved</dfn> if the namespace component is neither empty (e.g.
508: <code>|div</code>), representing the null namespace, or an an asterisk
509: (e.g. <code>*|div</code>), representing any namespace. Since the asterisk
1.60 lhunt 510: or empty namespace prefix do not need to be resolved, implementations that
511: support the namespace syntax in Selectors <em class=ct>must</em> support
1.65 ! lhunt 512: these. <a href="#SELECT" rel=biblioentry>[SELECT]<!--{{!SELECT}}--></a>
1.60 lhunt 513:
514: <p class=note>Implementations that don't support the namespace syntax in
515: Selectors would instead throw a <code>SYNTAX_ERR</code> because it would
516: be treated as an invalid selector.
1.50 lhunt 517:
1.64 lhunt 518: <h2 id=dom-feature><span class=secno>7. </span>DOM Feature String</h2>
519:
520: <p>DOM3 Core defines mechanisms for checking for interface support, and for
521: obtaining implementations of interfaces, using <a
522: href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMFeatures">feature
1.65 ! lhunt 523: strings</a>. (<a href="#DOM-LEVEL-3-CORE"
! 524: rel=biblioentry>[DOM-LEVEL-3-CORE]<!--{{!DOM-LEVEL-3-CORE}}--></a>,
! 525: section 1.3.6)
1.64 lhunt 526:
527: <p>A DOM application can use the <dfn id=hasfeature
528: title=hasFeature><code>hasFeature(<var>feature</var>,
529: <var>version</var>)</code></dfn> method of the
530: <code>DOMImplementation</code> interface with parameter values "<code
531: title="">Selectors-API</code>" and "<code>1.0</code>" (respectively) to
532: determine whether or not this module is supported by the implementation.
533: Conforming implementations <em class=ct>must</em> respond with a
534: <code>true</code> value when the <code><a
535: href="#hasfeature">hasFeature</a></code> method is queried with this
536: value. Authors are cautioned, however, that UAs returning
537: <code>true</code> might not be perfectly compliant, and that UAs returning
538: <code>false</code> might well have support for features in this
539: specification; in general, therefore, use of this method is discouraged.
540:
541: <h2 id=examples0><span class=secno>8. </span>Examples</h2>
542:
1.65 ! lhunt 543: <p class=issue>Since removing all the NSResolver examples, this section
! 544: needs to reviewed and possibly expanded.
1.20 lhunt 545:
1.22 lhunt 546: <div class=example>
1.36 lhunt 547: <p>The following examples make use of this sample document.</p>
1.20 lhunt 548:
1.22 lhunt 549: <pre><html xmlns="http://www.w3.org/1999/xhtml"
550: xmlns:svg="http://www.w3.org/2000/svg"
551: xml:lang="en">
552: <head>
553: <title>Selectors API Example</title>
554: </head>
555: <body>
1.44 lhunt 556: <div><svg:svg … > … </svg:svg></div>
557: <p><svg:svg … > … </svg:svg></p>
558: <p><svg xmlns="http://www.w3.org/2000/svg" … > … </svg></p>
1.22 lhunt 559: </body>
1.36 lhunt 560: </html></pre>
1.20 lhunt 561:
1.65 ! lhunt 562: <p>The methods accept a group of selectors (comma separated) as the
! 563: argument. The following example would select all <code>p</code> elements
! 564: in the document that have a class of either "<code>error</code>" or
! 565: "<code>warning</code>".</p>
! 566:
! 567: <pre>var alerts = document.querySelectorAll("p.warning, p.error");</pre>
1.21 lhunt 568:
1.65 ! lhunt 569: <p>The <code title=document-selectelement>querySelector()</code> methods
! 570: also accept a group of selectors and they will return the first element
! 571: (if any) that matches any of the selectors in the group.</p>
! 572:
! 573: <pre>var x = document.querySelector("#foo, #bar");</pre>
! 574:
! 575: <p><var>x</var> would contain the first element in the document with an ID
! 576: of either <code>foo</code> or <code>bar</code> (or both).</p>
1.21 lhunt 577:
1.65 ! lhunt 578: <p>The methods can also be invoked on elements. In this example, the
! 579: method is invoked on an element that is the target of an event listener.</p>
1.22 lhunt 580:
1.65 ! lhunt 581: <pre>function handle(evt) {
! 582: var x = evt.target.querySelector("span");
! 583: ...
! 584: // Do something with x
1.21 lhunt 585: }</pre>
1.14 avankest 586:
1.21 lhunt 587: <p>This example demonstrates how to iterate through the items in a
1.43 lhunt 588: <code>NodeList</code>.</p>
1.21 lhunt 589:
1.41 lhunt 590: <pre>var lis = document.querySelectorAll("ul.nav>li");
1.24 lhunt 591: for (var i = 0; i < lis.length; i++) {
1.21 lhunt 592: process(lis.item(i));
593: }</pre>
594:
595: <p>In ECMAScript, the language binding also allows <code>NodeList</code>s
1.43 lhunt 596: and to be addressed using the array notation, so that loop could be
597: rewritten like this:</p>
1.21 lhunt 598:
1.24 lhunt 599: <pre>for (var i = 0; i < lis.length; i++) {
1.21 lhunt 600: process(lis[i]);
601: }</pre>
602:
1.43 lhunt 603: <p>Since the <code>NodeList</code> objects returned by these methods are
1.22 lhunt 604: not live, changes to the DOM do not affect the content of the list.
1.21 lhunt 605: Consider the <code>process()</code> function called in the previous
606: examples is defined as follows:</p>
607:
1.36 lhunt 608: <pre>function process(elmt) {
1.21 lhunt 609: elmt.parentNode.removeChild(elmt);
610: }</pre>
611:
612: <p>This would cause each selected element to be removed from the DOM, but
1.43 lhunt 613: each element will remain in the <code>NodeList</code>. If the list were a
1.21 lhunt 614: live <code>NodeList</code>, removing an item from the DOM would also
615: remove the element from the list and adjust the indexes of subsequent
616: elements. That would have adverse effects upon the loop because not all
617: selected elements would be processed.</p>
618: </div>
619:
1.11 avankest 620: <h2 class=no-num id=references>References</h2>
1.1 avankest 621:
1.54 lhunt 622: <h3 class=no-num id=normative-references>Normative references</h3>
623: <!--begin-normative-->
624: <!-- Sorted by label -->
625:
626: <dl class=bibliography>
627: <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
628: <!---->
629:
630: <dt id=CSS21>[CSS21]
631:
632: <dd>Bert Bos; et al. <a
633: href="http://www.w3.org/TR/2007/CR-CSS21-20070719"><cite>Cascading Style
634: Sheets Level 2 Revision 1 (CSS 2.1) Specification.</cite></a> 19 July
635: 2007. W3C Candidate Recommendation. (Work in progress.) URL: <a
636: href="http://www.w3.org/TR/2007/CR-CSS21-20070719">http://www.w3.org/TR/2007/CR-CSS21-20070719</a>
637: </dd>
638: <!---->
639:
640: <dt id=DOM-BINDINGS>[DOM-BINDINGS]
641:
642: <dd>Cameron McCormack. <a
643: href="http://www.w3.org/TR/2008/WD-DOM-Bindings-20080410"><cite>Language
644: Bindings for DOM Specifications.</cite></a> 10 April 2008. W3C Working
645: Draft. (Work in progress.) URL: <a
646: href="http://www.w3.org/TR/2008/WD-DOM-Bindings-20080410">http://www.w3.org/TR/2008/WD-DOM-Bindings-20080410</a>
647: </dd>
648: <!---->
649:
650: <dt id=DOM-LEVEL-3-CORE>[DOM-LEVEL-3-CORE]
651:
652: <dd>Arnaud Le Hors; et al. <a
653: href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407"><cite>Document
654: Object Model (DOM) Level 3 Core Specification.</cite></a> 7 April 2004.
655: W3C Recommendation. URL: <a
656: href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407">http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407</a>
657: </dd>
658: <!---->
659:
660: <dt id=RFC2119>[RFC2119]
661:
662: <dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key
663: words for use in RFCs to Indicate Requirement Levels.</cite></a> Internet
664: RFC 2119. URL: <a
665: href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
666: </dd>
667: <!---->
668:
669: <dt id=SELECT>[SELECT]
670:
671: <dd>Daniel Glazman; Tantek Çelik; Ian Hickson. <a
672: href="http://www.w3.org/TR/2005/WD-css3-selectors-20051215"><cite>Selectors.</cite></a>
673: 15 December 2005. W3C Working Draft. (Work in progress.) URL: <a
674: href="http://www.w3.org/TR/2005/WD-css3-selectors-20051215">http://www.w3.org/TR/2005/WD-css3-selectors-20051215</a>
675: </dd>
676: <!---->
677: </dl>
678: <!--end-normative-->
1.1 avankest 679:
1.54 lhunt 680: <h3 class=no-num id=other-references>Other references</h3>
681: <!--begin-informative-->
682: <!-- Sorted by label -->
683:
684: <dl class=bibliography>
685: <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
686: <!---->
687:
688: <dt id=DOM-LEVEL-2-STYLE>[DOM-LEVEL-2-STYLE]
689:
690: <dd>Vidur Apparao; Philippe Le Hégaret; Chris Wilson. <a
691: href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113"><cite>Document
692: Object Model (DOM) Level 2 Style Specification.</cite></a> 13 November
693: 2000. W3C Recommendation. URL: <a
694: href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113">http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113</a>
695: </dd>
696: <!---->
697:
698: <dt id=ECMA-262>[ECMA-262]
699:
700: <dd><a
701: href="http://www.ecma-international.org/publications/standards/Ecma-262.htm"><cite>ECMAScript
702: Language Specification, Third Edition.</cite></a> December 1999. URL: <a
703: href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">http://www.ecma-international.org/publications/standards/Ecma-262.htm</a>
704: </dd>
705: <!---->
1.1 avankest 706: </dl>
1.54 lhunt 707: <!--end-informative-->
1.1 avankest 708:
1.11 avankest 709: <h2 class=no-num id=acknowledgements>Acknowledgements</h2>
1.1 avankest 710:
1.45 avankest 711: <p>The editors would like to thank to the following people who have
1.7 avankest 712: contributed to this specification (ordered on first name):
713:
1.1 avankest 714: <ul>
1.19 avankest 715: <li>Alex Russell
716:
1.44 lhunt 717: <li>Björn Höhrmann
1.1 avankest 718:
1.36 lhunt 719: <li>Boris Zbarsky
720:
1.1 avankest 721: <li>Cameron McCormack
722:
1.19 avankest 723: <li>Charles McCathieNevile
724:
725: <li>Chris Wilson
726:
1.1 avankest 727: <li>Daniel Schierbeck
728:
1.19 avankest 729: <li>Dave Massy
730:
1.44 lhunt 731: <li>David Håsäther
1.36 lhunt 732:
1.1 avankest 733: <li>Dean Jackson
734:
1.44 lhunt 735: <li>Erik Dahlström
1.36 lhunt 736:
1.1 avankest 737: <li>Ian Hickson
738:
739: <li>Jim Ley
740:
741: <li>Jonas Sicking
742:
1.11 avankest 743: <li>Jorgen Horstink
744:
1.5 avankest 745: <li>Karl Dubost
746:
1.1 avankest 747: <li>Maciej Stachowiak
748:
749: <li>Mohamed Zergaoui
750:
1.24 lhunt 751: <li>Philip Taylor
752:
1.19 avankest 753: <li>Robert Sayre
754:
1.1 avankest 755: <li>Robin Berjon
1.14 avankest 756:
1.19 avankest 757: <li>Simon Pieters
758:
1.36 lhunt 759: <li>Steven Pemberton
760:
1.14 avankest 761: <li>Tarquin Wilton-Jones
1.21 lhunt 762:
763: <li>Travis Leithead
1.1 avankest 764: </ul>
765:
766: <p>Thanks to all those who have helped to improve this specification by
767: sending suggestions and corrections. (Please, keep bugging us with your
768: 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