Commit | Line | Data |
---|---|---|
6a1aa64f DV |
1 | .. title:: MochiKit.Selector - Selecting elements by CSS selector syntax |
2 | ||
3 | Name | |
4 | ==== | |
5 | ||
6 | MochiKit.Selector - Selecting elements by CSS selector syntax | |
7 | ||
8 | ||
9 | Synopsis | |
10 | ======== | |
11 | ||
12 | :: | |
13 | ||
14 | MochiKit.Base.map(MochiKit.Visual.fade, $$('p.fademe')); | |
15 | ||
16 | ||
17 | Description | |
18 | =========== | |
19 | ||
20 | MochiKit.Selector provides utilities to select elements by CSS | |
21 | selector syntax. In particular it provides the :mochiref:`$$` | |
22 | function. | |
23 | ||
24 | Dependencies | |
25 | ============ | |
26 | ||
27 | - :mochiref:`MochiKit.Base` | |
28 | - :mochiref:`MochiKit.DOM` | |
29 | - :mochiref:`MochiKit.Iter` | |
30 | ||
31 | ||
32 | Overview | |
33 | ======== | |
34 | ||
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 | |
38 | current document. | |
39 | ||
40 | Many of CSS3 [1]_ selectors are supported: | |
41 | ||
42 | - Select by tag name (``A``) | |
43 | - Select by class (``.theclass``) | |
44 | - Select by id (``#someid``) | |
45 | - Combinators | |
46 | - Descendant: ``E F`` | |
47 | - Child: ``E > F`` | |
48 | - Immediate following sibling: ``E + F`` | |
49 | - Following sibling: ``E ~ F`` | |
50 | - Attribute selectors | |
51 | - simple "has attribute" (without operator) | |
52 | - ``=`` equal | |
53 | - ``!=`` not equal (not in CSS std.) | |
54 | - ``~=`` word containment | |
55 | - ``^=`` starts-with | |
56 | - ``$=`` ends-with | |
57 | - ``*=`` substring containment | |
58 | - ``|=`` first part of hyphen deleimited (eg. lang|="en" matches lang="en-US") | |
59 | - Pseudo-classes | |
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>)`` | |
61 | ||
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. | |
67 | ||
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. | |
73 | ||
74 | For further documentation of CSS selectors, refer to the W3C CSS standard. [1]_ | |
75 | ||
76 | The original version of this module was ported from Prototype. | |
77 | ||
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. | |
82 | ||
83 | ||
84 | API Reference | |
85 | ============= | |
86 | ||
87 | Functions | |
88 | --------- | |
89 | ||
90 | :mochidef:`$$(expression[, ...])`: | |
91 | ||
92 | Performs a selection on the active document. Equivalent | |
93 | to ``findChildElements(MochiKit.DOM.currentDocument(), [expression, ...])`` | |
94 | ||
95 | *Availability*: | |
96 | Available in MochiKit 1.4+ | |
97 | ||
98 | ||
99 | :mochidef:`findChildElements(element, expressions)`: | |
100 | ||
101 | Traverses the child nodes of ``element`` and returns the subset | |
102 | of those that match any of the selector expressions in ``expressions``. | |
103 | ||
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. | |
109 | ||
110 | *Availability*: | |
111 | Available in MochiKit 1.4+ | |
112 | ||
113 | ||
114 | Constructors | |
115 | ------------- | |
116 | ||
117 | :mochidef:`Selector(simpleExpression)`: | |
118 | ||
119 | An object storing the parsed version of a simple CSS selector expression | |
120 | and providing functions for executing searches. | |
121 | ||
122 | *Simple* means that the expression is not a combination of expressions, | |
123 | i.e. it does not contain any spaces. | |
124 | ||
125 | Usually the user would not instantiate or use this object directly, but | |
126 | heres how:: | |
127 | ||
128 | var selector = MochiKit.Selector.Selector('#someelementid'); | |
129 | var searchResults = selector.findElements(rootElement); | |
130 | ||
131 | *Availability*: | |
132 | Available in MochiKit 1.4+ | |
133 | ||
134 | :mochidef:`Selector.findElements(scope[, axis=""])`: | |
135 | ||
136 | Performs a search on ``scope``. The value of axis controls what relatives | |
137 | of ``scope`` are considered. | |
138 | ||
139 | ``scope``: | |
140 | A DOM node that acts as a starting point for the search. | |
141 | ||
142 | ``axis``: | |
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. | |
148 | ||
149 | *Availability*: | |
150 | Available in MochiKit 1.4+ | |
151 | ||
152 | ||
153 | See Also | |
154 | ======== | |
155 | ||
156 | .. [1] CSS Selectors Level 3 (Last Call, oct. 2006): | |
157 | http://www.w3.org/TR/2005/WD-css3-selectors-20051215/ | |
158 | ||
159 | ||
160 | Authors | |
161 | ======= | |
162 | ||
163 | - Arnar Birgisson <arnarbi@gmail.com> | |
164 | - Thomas Herve <therve@gmail.com> | |
165 | - Originally ported from Prototype <http://prototype.conio.net/> | |
166 | ||
167 | ||
168 | Copyright | |
169 | ========= | |
170 | ||
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 | |
174 | v2.1`_. | |
175 | ||
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 | |
178 | ||
179 | Based on Prototype, (c) 2005 Sam Stephenson, available under the `Prototype | |
180 | license`_ | |
181 | ||
182 | .. _`Prototype license`: http://dev.rubyonrails.org/browser/spinoffs/prototype/LICENSE?rev=3362 |