Name

MochiKit.Selector - Selecting elements by CSS selector syntax

Synopsis

MochiKit.Base.map(MochiKit.Visual.fade, $$('p.fademe'));

Description

MochiKit.Selector provides utilities to select elements by CSS selector syntax. In particular it provides the $$ function.

Dependencies

Overview

This module provides facilities to select childs of a DOM node by using CSS selector syntax. In particular, it provides the $$ function, which performs such a selection on the current document.

Many of CSS3 [1] selectors are supported:

Select by tag name (A)
Select by class (.theclass)
Select by id (#someid)
Combinators
- Descendant: E F
- Child: E > F
- Immediate following sibling: E + F
- Following sibling: E ~ F
Attribute selectors
- simple "has attribute" (without operator)
- = equal
- != not equal (not in CSS std.)
- ~= word containment
- ^= starts-with
- $= ends-with
- *= substring containment
- |= first part of hyphen deleimited (eg. lang|="en" matches lang="en-US")
Pseudo-classes
- :nth-child, :nth-last-child, :first-child, :last-child, :only-child, :empty, :enabled, :disabled, :checked, :not(<any other selector>)
Deprecated Pseudo-classes (to be removed in 1.5)
- :root, :nth-of-type, :nth-last-of-type, :first-of-type, :last-of-type, :only-of-type

Multiple selectors can be concatenated, like this: P.quote[author~='Torvalds'], in which case elements matching all the selectors are returned. Furthermore, such concatenations can be combined by joining them with spaces and combinators. This invokes the regular CSS behaviour of matching parts of the combination in sequence, starting off each part from the elements returned by the preceeding part.

For the :nth-* pseudoclasses, the an+b syntax is partially supported, specifically a and b must be non-negative and only a is optional (this differs from the CSS std.) Also, odd and even are supported, e.g. table tr:nth-child(odd) gives you every other row of table starting with the first one.

For further documentation of CSS selectors, refer to the W3C CSS standard. [1]

The original version of this module was ported from Prototype.

Note: This module is currently experimental and API stability cannot be fully guaranteed. The implementation is scheduled to be replaced with a new faster version (now in development) during the MochiKit 1.5 development cycle.

Note: Due to how Internet Explorer handles node attributes, some attribute selectors may not work as expected. In particular a[title] will not work as all A elements in the Internet Explorer DOM model have a title attribute regardless of whether it's specified in the markup or not.

API Reference

Functions

findDocElements(expression[, ...]):

Performs a selection on the active document. Equivalent to findChildElements(MochiKit.DOM.currentDocument(), [expression, ...])

Availability:

Available in MochiKit 1.4+

findChildElements(element, expressions):

Traverses the child nodes of element and returns the subset of those that match any of the selector expressions in expressions.

Each expression can be a combination of simple expressions, by concatenating them with spaces or combinators. In that case, normal CSS rules apply, each simple expression is evaluated in turn and the results of that one is used as the scope for the succeeding expression (see Selector.findElements). Finally, the results of the last simple expression is returned as the search result.

Availability:

Available in MochiKit 1.4+

$$(expression[, ...]):

An alias to findDocElements.

Availability:

Available in MochiKit 1.4+

Constructors

Selector(simpleExpression):

An object storing the parsed version of a simple CSS selector expression and providing functions for executing searches.

Simple means that the expression is not a combination of expressions, i.e. it does not contain any spaces.

Usually the user would not instantiate or use this object directly, but heres how:
var selector = new MochiKit.Selector.Selector('#someelementid');
var searchResults = selector.findElements(rootElement);
Deprecated:

Use findChildElements instead. The Selector class will be removed in version 1.5.

Availability:

Available in MochiKit 1.4+

Selector.findElements(scope[, axis=""]):

Performs a search on scope. The value of axis controls what relatives of scope are considered.

scope:

A DOM node that acts as a starting point for the search.

axis:

One of ">", "+", "~" or the empty string (default). If the empty string, all descendant nodes of scope are tested against the expression. If > only direct child nodes of scope are tested, if + only the next sibling (if any) of scope is tested and if ~ all succeeding siblings of scope are tested.

Deprecated:

Use findChildElements instead. The Selector class will be removed in version 1.5.

Availability:

Available in MochiKit 1.4+

Authors

Arnar Birgisson <arnarbi@gmail.com>
Thomas Herve <therve@gmail.com>
Originally ported from Prototype <http://prototype.conio.net/>

Copyright

Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is dual-licensed free software; you can redistribute it and/or modify it under the terms of the MIT License or the Academic Free License v2.1.