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