mochikit_v14/doc/html/MochiKit/Selector.html

   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">&gt;</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 &quot;has attribute&quot; (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|=&quot;en&quot; matches lang=&quot;en-US&quot;)</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(&lt;any</span> <span class="pre">other</span> <span class="pre">selector&gt;)</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=&quot;&quot;])</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">&quot;&gt;&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;+&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;~&quot;</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">&gt;</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 &lt;<a class="reference" href="mailto:arnarbi&#64;gmail.com">arnarbi&#64;gmail.com</a>&gt;</li>
 194 <li>Thomas Herve &lt;<a class="reference" href="mailto:therve&#64;gmail.com">therve&#64;gmail.com</a>&gt;</li>
 195 <li>Originally ported from Prototype &lt;<a class="reference" href="http://prototype.conio.net/">http://prototype.conio.net/</a>&gt;</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 &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;. 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>