| 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> |