mochikit_v14/doc/rst/MochiKit/Selector.rst

   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