$$ :: Utility Methods

$$(cssRule...) -> [HTMLElement...] Takes an arbitrary number of CSS selectors (strings) and returns a document-order array of extended DOM elements that match any of them.

Sometimes the usual tools from your DOM arsenal – document.getElementById() encapsulated by $(), getElementsByTagName() and even Prototype’s very own getElementsByClassName() extensions – just aren’t enough to quickly find our elements or collections of elements. If you know the DOM tree structure, you can simply resort to CSS selectors to get the job done.

Performance: when better alternatives should be used instead of $$

Now, this function is powerful, but if misused, it will suffer performance issues. So here are a few guidelines:

· | If you’re just looking for elements with a specific CSS class name among their class name set, use Prototype’s document.getElementsByClassName() extension.

· | Better yet: if this search is constrained within a given container element, use the Element.getElementsByClassName() extension.

Those methods should be favored in the case of simple CSS-class-based lookups, because they’re, at any rate, faster than $$. On browsers supporting DOM Level 3 XPath, they’re potentially blazing fast.

Now, if you’re going for more complex stuff, indeed use $$. But use it well. The $$ function searches, by default, the whole document. So if you can, scope your CSS rules as early as you can, e.g. by having them start with ID selectors. That’ll help reduce the search tree as fast as possible, and speed up your operation.

Examples

$$('div')

// -> all DIVs in the document. Same as document.getElementsByTagName('div')!

$$('#contents')

// -> same as $('contents'), only it returns an array anyway.

$$('li.faux')

// -> all LI elements with class 'faux'

$$('#contents a[rel]')

// -> all links inside the element of ID "contents" with a rel attribute

$$('a[href="#"]')

// -> all links with a href attribute of value "#" (eyeew!)

$$('#navbar li', '#sidebar li')

// -> all links within the elements of ID "navbar" or "sidebar"

Supported CSS syntax

The $$ function does not rely on the browser’s internal CSS parsing capabilities (otherwise, we’d be in cross-browser trouble…), and therefore offers a consistent set of selectors across all supported browsers. The flip side is, it currently doesn’t support as many selectors as browsers that are very CSS-capable.

Here is the current set of supported selectors:

· | Type selector: tag names, as in div.

· | Descendant selector: the space(s) between other selectors, as in #a li.

· | Attribute selectors: the full CSS 2.1 set of [attr], [attr=value], [attr~=value] and [attr|=value]. It also supports [attr!=value].

If the value you’re matching against includes a space, be sure to enclose the value in quotation marks. ([title=&#8221;Hello World!&#8221;])

· | Class selector: CSS class names, as in .highlighted or .example.wrong.

· | ID selector: as in #item1.

However, it currently does not support child selectors (>), adjacent sibling selectors (+), pseudo-elements (e.g. :after) and pseudo-classes (e.g. :hover).

Prototype API 1.5.0 - prototypejs.org