1 .. title:: MochiKit.Selector - Selecting elements by CSS selector syntax
6 MochiKit.Selector - Selecting elements by CSS selector syntax
14 MochiKit.Base.map(MochiKit.Visual.fade, $$('p.fademe'));
20 MochiKit.Selector provides utilities to select elements by CSS
21 selector syntax. In particular it provides the :mochiref:`$$`
27 - :mochiref:`MochiKit.Base`
28 - :mochiref:`MochiKit.DOM`
29 - :mochiref:`MochiKit.Iter`
35 This module provides facilities to select childs of a DOM node by
36 using CSS selector syntax. In particular, it provides the
37 :mochiref:`$$` function, which performs such a selection on the
40 Many of CSS3 [1]_ selectors are supported:
42 - Select by tag name (``A``)
43 - Select by class (``.theclass``)
44 - Select by id (``#someid``)
48 - Immediate following sibling: ``E + F``
49 - Following sibling: ``E ~ F``
51 - simple "has attribute" (without operator)
53 - ``!=`` not equal (not in CSS std.)
54 - ``~=`` word containment
57 - ``*=`` substring containment
58 - ``|=`` first part of hyphen deleimited (eg. lang|="en" matches lang="en-US")
60 - ``:root``, ``:nth-child``, ``:nth-last-child``, ``:nth-of-type``, ``:nth-last-of-type``, ``:first-child``, ``:last-child``, ``:first-of-type``, ``:last-of-type``, ``:only-child``, ``:only-of-type``, ``:empty``, ``:enabled``, ``:disabled``, ``:checked``, ``:not(<any other selector>)``
62 Multiple selectors can be concatenated, like this: ``P.quote[author~='Torvalds']``,
63 in which case elements matching *all* the selectors are returned. Furthermore, such
64 concatenations can be *combined* by joining them with spaces and combinators.
65 This invokes the regular CSS behaviour of matching parts of the combination in
66 sequence, starting off each part from the elements returned by the preceeding part.
68 For the ``:nth-*`` pseudoclasses, the ``an+b`` syntax is partially
69 supported, specifically a and b must be non-negative and only a is
70 optional (this differs from the CSS std.) Also, ``odd`` and ``even``
71 are supported, e.g. ``table tr:nth-child(odd)`` gives you every
72 other row of table starting with the first one.
74 For further documentation of CSS selectors, refer to the W3C CSS standard. [1]_
76 The original version of this module was ported from Prototype.
78 **Note:** Due to how Internet Explorer handles node attributes, some attribute
79 selectors may not work as expected. In particular ``a[title]`` will not work
80 as all ``A`` elements in the Internet Explorer DOM model have a title attribute
81 regardless of whether it's specified in the markup or not.
90 :mochidef:`$$(expression[, ...])`:
92 Performs a selection on the active document. Equivalent
93 to ``findChildElements(MochiKit.DOM.currentDocument(), [expression, ...])``
96 Available in MochiKit 1.4+
99 :mochidef:`findChildElements(element, expressions)`:
101 Traverses the child nodes of ``element`` and returns the subset
102 of those that match any of the selector expressions in ``expressions``.
104 Each expression can be a combination of simple expressions, by concatenating
105 them with spaces or combinators. In that case, normal CSS rules apply, each
106 simple expression is evaluated in turn and the results of that one is used
107 as the scope for the succeeding expression (see :mochiref:`Selector.findElements`).
108 Finally, the results of the last simple expression is returned as the search result.
111 Available in MochiKit 1.4+
117 :mochidef:`Selector(simpleExpression)`:
119 An object storing the parsed version of a simple CSS selector expression
120 and providing functions for executing searches.
122 *Simple* means that the expression is not a combination of expressions,
123 i.e. it does not contain any spaces.
125 Usually the user would not instantiate or use this object directly, but
128 var selector = MochiKit.Selector.Selector('#someelementid');
129 var searchResults = selector.findElements(rootElement);
132 Available in MochiKit 1.4+
134 :mochidef:`Selector.findElements(scope[, axis=""])`:
136 Performs a search on ``scope``. The value of axis controls what relatives
137 of ``scope`` are considered.
140 A DOM node that acts as a starting point for the search.
143 One of ``">"``, ``"+"``, ``"~"`` or the empty string (default).
144 If the empty string, all descendant nodes of ``scope`` are tested against
145 the expression. If ``>`` only direct child nodes of ``scope`` are tested,
146 if ``+`` only the next sibling (if any) of ``scope`` is tested and if
147 ``~`` all succeeding siblings of ``scope`` are tested.
150 Available in MochiKit 1.4+
156 .. [1] CSS Selectors Level 3 (Last Call, oct. 2006):
157 http://www.w3.org/TR/2005/WD-css3-selectors-20051215/
163 - Arnar Birgisson <arnarbi@gmail.com>
164 - Thomas Herve <therve@gmail.com>
165 - Originally ported from Prototype <http://prototype.conio.net/>
171 Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
172 dual-licensed free software; you can redistribute it and/or modify it
173 under the terms of the `MIT License`_ or the `Academic Free License
176 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
177 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php
179 Based on Prototype, (c) 2005 Sam Stephenson, available under the `Prototype
182 .. _`Prototype license`: http://dev.rubyonrails.org/browser/spinoffs/prototype/LICENSE?rev=3362