Commit | Line | Data |
---|---|---|
6a1aa64f DV |
1 | <?xml version="1.0" encoding="utf-8" ?> |
2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
3 | ||
4 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
5 | <head> | |
6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | |
7 | <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> | |
8 | <title>MochiKit.Selector - Selecting elements by CSS selector syntax</title> | |
9 | ||
10 | <link rel="stylesheet" href="../../../include/css/documentation.css" type="text/css" /> | |
11 | <script type="text/javascript" src="../../../packed/MochiKit/MochiKit.js"></script> | |
12 | <script type="text/javascript" src="../../js/toc.js"></script> | |
13 | </head> | |
14 | <body> | |
15 | <div class="document"> | |
16 | <div class="section"> | |
17 | <h1><a id="name" name="name">Name</a></h1> | |
18 | <p>MochiKit.Selector - Selecting elements by CSS selector syntax</p> | |
19 | </div> | |
20 | <div class="section"> | |
21 | <h1><a id="synopsis" name="synopsis">Synopsis</a></h1> | |
22 | <pre class="literal-block"> | |
23 | MochiKit.Base.map(MochiKit.Visual.fade, $$('p.fademe')); | |
24 | </pre> | |
25 | </div> | |
26 | <div class="section"> | |
27 | <h1><a id="description" name="description">Description</a></h1> | |
28 | <p>MochiKit.Selector provides utilities to select elements by CSS | |
29 | selector syntax. In particular it provides the <a class="mochiref reference" href="#fn-$$">$$</a> | |
30 | function.</p> | |
31 | </div> | |
32 | <div class="section"> | |
33 | <h1><a id="dependencies" name="dependencies">Dependencies</a></h1> | |
34 | <ul class="simple"> | |
35 | <li><a class="mochiref reference" href="Base.html">MochiKit.Base</a></li> | |
36 | <li><a class="mochiref reference" href="DOM.html">MochiKit.DOM</a></li> | |
37 | <li><a class="mochiref reference" href="Iter.html">MochiKit.Iter</a></li> | |
38 | </ul> | |
39 | </div> | |
40 | <div class="section"> | |
41 | <h1><a id="overview" name="overview">Overview</a></h1> | |
42 | <p>This module provides facilities to select childs of a DOM node by | |
43 | using CSS selector syntax. In particular, it provides the | |
44 | <a class="mochiref reference" href="#fn-$$">$$</a> function, which performs such a selection on the | |
45 | current document.</p> | |
46 | <p>Many of CSS3 <a class="footnote-reference" href="#id3" id="id1" name="id1">[1]</a> selectors are supported:</p> | |
47 | <ul> | |
48 | <li><p class="first">Select by tag name (<tt class="docutils literal"><span class="pre">A</span></tt>)</p> | |
49 | </li> | |
50 | <li><p class="first">Select by class (<tt class="docutils literal"><span class="pre">.theclass</span></tt>)</p> | |
51 | </li> | |
52 | <li><p class="first">Select by id (<tt class="docutils literal"><span class="pre">#someid</span></tt>)</p> | |
53 | </li> | |
54 | <li><dl class="first docutils"> | |
55 | <dt>Combinators</dt> | |
56 | <dd><ul class="first last simple"> | |
57 | <li>Descendant: <tt class="docutils literal"><span class="pre">E</span> <span class="pre">F</span></tt></li> | |
58 | <li>Child: <tt class="docutils literal"><span class="pre">E</span> <span class="pre">></span> <span class="pre">F</span></tt></li> | |
59 | <li>Immediate following sibling: <tt class="docutils literal"><span class="pre">E</span> <span class="pre">+</span> <span class="pre">F</span></tt></li> | |
60 | <li>Following sibling: <tt class="docutils literal"><span class="pre">E</span> <span class="pre">~</span> <span class="pre">F</span></tt></li> | |
61 | </ul> | |
62 | </dd> | |
63 | </dl> | |
64 | </li> | |
65 | <li><dl class="first docutils"> | |
66 | <dt>Attribute selectors</dt> | |
67 | <dd><ul class="first last simple"> | |
68 | <li>simple "has attribute" (without operator)</li> | |
69 | <li><tt class="docutils literal"><span class="pre">=</span></tt> equal</li> | |
70 | <li><tt class="docutils literal"><span class="pre">!=</span></tt> not equal (not in CSS std.)</li> | |
71 | <li><tt class="docutils literal"><span class="pre">~=</span></tt> word containment</li> | |
72 | <li><tt class="docutils literal"><span class="pre">^=</span></tt> starts-with</li> | |
73 | <li><tt class="docutils literal"><span class="pre">$=</span></tt> ends-with</li> | |
74 | <li><tt class="docutils literal"><span class="pre">*=</span></tt> substring containment</li> | |
75 | <li><tt class="docutils literal"><span class="pre">|=</span></tt> first part of hyphen deleimited (eg. lang|="en" matches lang="en-US")</li> | |
76 | </ul> | |
77 | </dd> | |
78 | </dl> | |
79 | </li> | |
80 | <li><dl class="first docutils"> | |
81 | <dt>Pseudo-classes</dt> | |
82 | <dd><ul class="first last simple"> | |
83 | <li><tt class="docutils literal"><span class="pre">:root</span></tt>, <tt class="docutils literal"><span class="pre">:nth-child</span></tt>, <tt class="docutils literal"><span class="pre">:nth-last-child</span></tt>, <tt class="docutils literal"><span class="pre">:nth-of-type</span></tt>, <tt class="docutils literal"><span class="pre">:nth-last-of-type</span></tt>, <tt class="docutils literal"><span class="pre">:first-child</span></tt>, <tt class="docutils literal"><span class="pre">:last-child</span></tt>, <tt class="docutils literal"><span class="pre">:first-of-type</span></tt>, <tt class="docutils literal"><span class="pre">:last-of-type</span></tt>, <tt class="docutils literal"><span class="pre">:only-child</span></tt>, <tt class="docutils literal"><span class="pre">:only-of-type</span></tt>, <tt class="docutils literal"><span class="pre">:empty</span></tt>, <tt class="docutils literal"><span class="pre">:enabled</span></tt>, <tt class="docutils literal"><span class="pre">:disabled</span></tt>, <tt class="docutils literal"><span class="pre">:checked</span></tt>, <tt class="docutils literal"><span class="pre">:not(<any</span> <span class="pre">other</span> <span class="pre">selector>)</span></tt></li> | |
84 | </ul> | |
85 | </dd> | |
86 | </dl> | |
87 | </li> | |
88 | </ul> | |
89 | <p>Multiple selectors can be concatenated, like this: <tt class="docutils literal"><span class="pre">P.quote[author~='Torvalds']</span></tt>, | |
90 | in which case elements matching <em>all</em> the selectors are returned. Furthermore, such | |
91 | concatenations can be <em>combined</em> by joining them with spaces and combinators. | |
92 | This invokes the regular CSS behaviour of matching parts of the combination in | |
93 | sequence, starting off each part from the elements returned by the preceeding part.</p> | |
94 | <p>For the <tt class="docutils literal"><span class="pre">:nth-*</span></tt> pseudoclasses, the <tt class="docutils literal"><span class="pre">an+b</span></tt> syntax is partially | |
95 | supported, specifically a and b must be non-negative and only a is | |
96 | optional (this differs from the CSS std.) Also, <tt class="docutils literal"><span class="pre">odd</span></tt> and <tt class="docutils literal"><span class="pre">even</span></tt> | |
97 | are supported, e.g. <tt class="docutils literal"><span class="pre">table</span> <span class="pre">tr:nth-child(odd)</span></tt> gives you every | |
98 | other row of table starting with the first one.</p> | |
99 | <p>For further documentation of CSS selectors, refer to the W3C CSS standard. <a class="footnote-reference" href="#id3" id="id2" name="id2">[1]</a></p> | |
100 | <p>The original version of this module was ported from Prototype.</p> | |
101 | <p><strong>Note:</strong> Due to how Internet Explorer handles node attributes, some attribute | |
102 | selectors may not work as expected. In particular <tt class="docutils literal"><span class="pre">a[title]</span></tt> will not work | |
103 | as all <tt class="docutils literal"><span class="pre">A</span></tt> elements in the Internet Explorer DOM model have a title attribute | |
104 | regardless of whether it's specified in the markup or not.</p> | |
105 | </div> | |
106 | <div class="section"> | |
107 | <h1><a id="api-reference" name="api-reference">API Reference</a></h1> | |
108 | <div class="section"> | |
109 | <h2><a id="functions" name="functions">Functions</a></h2> | |
110 | <p> | |
111 | <a name="fn-$$"></a> | |
112 | <a class="mochidef reference" href="#fn-$$">$$(expression[, ...])</a>:</p> | |
113 | <blockquote> | |
114 | <p>Performs a selection on the active document. Equivalent | |
115 | to <tt class="docutils literal"><span class="pre">findChildElements(MochiKit.DOM.currentDocument(),</span> <span class="pre">[expression,</span> <span class="pre">...])</span></tt></p> | |
116 | <dl class="docutils"> | |
117 | <dt><em>Availability</em>:</dt> | |
118 | <dd>Available in MochiKit 1.4+</dd> | |
119 | </dl> | |
120 | </blockquote> | |
121 | <p> | |
122 | <a name="fn-findchildelements"></a> | |
123 | <a class="mochidef reference" href="#fn-findchildelements">findChildElements(element, expressions)</a>:</p> | |
124 | <blockquote> | |
125 | <p>Traverses the child nodes of <tt class="docutils literal"><span class="pre">element</span></tt> and returns the subset | |
126 | of those that match any of the selector expressions in <tt class="docutils literal"><span class="pre">expressions</span></tt>.</p> | |
127 | <p>Each expression can be a combination of simple expressions, by concatenating | |
128 | them with spaces or combinators. In that case, normal CSS rules apply, each | |
129 | simple expression is evaluated in turn and the results of that one is used | |
130 | as the scope for the succeeding expression (see <a class="mochiref reference" href="#fn-selector.findelements">Selector.findElements</a>). | |
131 | Finally, the results of the last simple expression is returned as the search result.</p> | |
132 | <dl class="docutils"> | |
133 | <dt><em>Availability</em>:</dt> | |
134 | <dd>Available in MochiKit 1.4+</dd> | |
135 | </dl> | |
136 | </blockquote> | |
137 | </div> | |
138 | <div class="section"> | |
139 | <h2><a id="constructors" name="constructors">Constructors</a></h2> | |
140 | <p> | |
141 | <a name="fn-selector"></a> | |
142 | <a class="mochidef reference" href="#fn-selector">Selector(simpleExpression)</a>:</p> | |
143 | <blockquote> | |
144 | <p>An object storing the parsed version of a simple CSS selector expression | |
145 | and providing functions for executing searches.</p> | |
146 | <p><em>Simple</em> means that the expression is not a combination of expressions, | |
147 | i.e. it does not contain any spaces.</p> | |
148 | <p>Usually the user would not instantiate or use this object directly, but | |
149 | heres how:</p> | |
150 | <pre class="literal-block"> | |
151 | var selector = MochiKit.Selector.Selector('#someelementid'); | |
152 | var searchResults = selector.findElements(rootElement); | |
153 | </pre> | |
154 | <dl class="docutils"> | |
155 | <dt><em>Availability</em>:</dt> | |
156 | <dd>Available in MochiKit 1.4+</dd> | |
157 | </dl> | |
158 | </blockquote> | |
159 | <p> | |
160 | <a name="fn-selector.findelements"></a> | |
161 | <a class="mochidef reference" href="#fn-selector.findelements">Selector.findElements(scope[, axis=""])</a>:</p> | |
162 | <blockquote> | |
163 | <p>Performs a search on <tt class="docutils literal"><span class="pre">scope</span></tt>. The value of axis controls what relatives | |
164 | of <tt class="docutils literal"><span class="pre">scope</span></tt> are considered.</p> | |
165 | <dl class="docutils"> | |
166 | <dt><tt class="docutils literal"><span class="pre">scope</span></tt>:</dt> | |
167 | <dd>A DOM node that acts as a starting point for the search.</dd> | |
168 | <dt><tt class="docutils literal"><span class="pre">axis</span></tt>:</dt> | |
169 | <dd>One of <tt class="docutils literal"><span class="pre">">"</span></tt>, <tt class="docutils literal"><span class="pre">"+"</span></tt>, <tt class="docutils literal"><span class="pre">"~"</span></tt> or the empty string (default). | |
170 | If the empty string, all descendant nodes of <tt class="docutils literal"><span class="pre">scope</span></tt> are tested against | |
171 | the expression. If <tt class="docutils literal"><span class="pre">></span></tt> only direct child nodes of <tt class="docutils literal"><span class="pre">scope</span></tt> are tested, | |
172 | if <tt class="docutils literal"><span class="pre">+</span></tt> only the next sibling (if any) of <tt class="docutils literal"><span class="pre">scope</span></tt> is tested and if | |
173 | <tt class="docutils literal"><span class="pre">~</span></tt> all succeeding siblings of <tt class="docutils literal"><span class="pre">scope</span></tt> are tested.</dd> | |
174 | <dt><em>Availability</em>:</dt> | |
175 | <dd>Available in MochiKit 1.4+</dd> | |
176 | </dl> | |
177 | </blockquote> | |
178 | </div> | |
179 | </div> | |
180 | <div class="section"> | |
181 | <h1><a id="see-also" name="see-also">See Also</a></h1> | |
182 | <table class="docutils footnote" frame="void" id="id3" rules="none"> | |
183 | <colgroup><col class="label" /><col /></colgroup> | |
184 | <tbody valign="top"> | |
185 | <tr><td class="label"><a name="id3">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>)</em> CSS Selectors Level 3 (Last Call, oct. 2006): | |
186 | <a class="reference" href="http://www.w3.org/TR/2005/WD-css3-selectors-20051215/">http://www.w3.org/TR/2005/WD-css3-selectors-20051215/</a></td></tr> | |
187 | </tbody> | |
188 | </table> | |
189 | </div> | |
190 | <div class="section"> | |
191 | <h1><a id="authors" name="authors">Authors</a></h1> | |
192 | <ul class="simple"> | |
193 | <li>Arnar Birgisson <<a class="reference" href="mailto:arnarbi@gmail.com">arnarbi@gmail.com</a>></li> | |
194 | <li>Thomas Herve <<a class="reference" href="mailto:therve@gmail.com">therve@gmail.com</a>></li> | |
195 | <li>Originally ported from Prototype <<a class="reference" href="http://prototype.conio.net/">http://prototype.conio.net/</a>></li> | |
196 | </ul> | |
197 | </div> | |
198 | <div class="section"> | |
199 | <h1><a id="copyright" name="copyright">Copyright</a></h1> | |
200 | <p>Copyright 2005 Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>>. This program is | |
201 | dual-licensed free software; you can redistribute it and/or modify it | |
202 | under the terms of the <a class="reference" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a> or the <a class="reference" href="http://www.opensource.org/licenses/afl-2.1.php">Academic Free License | |
203 | v2.1</a>.</p> | |
204 | <p>Based on Prototype, (c) 2005 Sam Stephenson, available under the <a class="reference" href="http://dev.rubyonrails.org/browser/spinoffs/prototype/LICENSE?rev=3362">Prototype | |
205 | license</a></p> | |
206 | </div> | |
207 | </div> | |
208 | ||
209 | </body> | |
210 | </html> |