Prototype JavaScript framework - Utility Methods

document.getElementsByClassName

2007-01-15T23:15:00Z

document.getElementsByClassName(className[, element]) -> [HTMLElement...]

Retrieves (and extends) all the elements that have a CSS class name of className. The optional element parameter specifies a parent element to search under.

As of Prototype 1.6, document.getElementsByClassName has been deprecated since native implementations return a NodeList rather than an Array. Please use $$ or Element#select instead.

Note that each returned element has been extended.

Example

HTML


  <body>
    <div id="one" class="foo">Single class name</div>
    <div id="two" class="foo bar thud">Multiple class names</div>
    <ul id="list">
      <li id="item_one" class="thud">List item 1</li>
      <li>List item 2</li>
      <li id="item_two" class="thud">List item 3</li>
    </ul>
  </body>

JavaScript


  document.getElementsByClassName('foo');
  // -> [HTMLElement, HTMLElement] (div#one, div#two)

  document.getElementsByClassName('thud');
  // -> [HTMLElement, HTMLElement, HTMLElement] (div#two, li#item_one, li#item_two);

  document.getElementsByClassName('thud', $('list'));
  // -> [HTMLElement, HTMLElement] (li#item_one, li#item_two)

$w

2006-12-07T11:54:00Z

$w(String) -> Array

Splits a string into an Array, treating all whitespace as delimiters. Equivalent to Ruby's %w{foo bar} or Perl's qw(foo bar).

This is one of those life-savers for people who just hate commas in literal arrays :-)

Examples

$w('apples bananas kiwis')
// -> ['apples', 'bananas', 'kiwis']

This can slightly shorten code when writing simple iterations:

$w('apples bananas kiwis').each(function(fruit){
  var message = 'I like ' + fruit
  // do something with the message
})

This also becomes sweet when combined with Element functions:

$w('ads navbar funkyLinks').each(Element.hide);

Try.these

2006-12-06T18:27:00Z

Try.these(Function...) -> firstOKResult

Accepts an arbitrary number of functions and returns the result of the first one that doesn't throw an error.

This method provides a simple idiom for trying out blocks of code in sequence. Such a sequence of attempts usually represents a downgrading approach to obtaining a given feature.

In this example from Prototype's Ajax library, we want to get an XMLHttpRequest object. Internet Explorer 6 and earlier, however, does not provide it as a vanilla JavaScript object, and will throw an error if we attempt a simple instantiation. Also, over time, its proprietary way evolved, changing COM interface names.

Try.these will try several ways in sequence, from the best (and, theoretically, most widespread) one to the oldest and rarest way, returning the result of the first successful function.

If none of the blocks succeeded, Try.these will return undefined, which will cause the getTransport method in the example below to return false, provided as a fallback result value.

getTransport: function() {
  return Try.these(
    function() { return new XMLHttpRequest() },
    function() { return new ActiveXObject('Msxml2.XMLHTTP') },
    function() { return new ActiveXObject('Microsoft.XMLHTTP') }
  ) || false;
}

Utility Methods

2006-12-05T21:37:00Z

Prototype provides a number of “convenience” methods. Most are aliases of other Prototype methods, with the exception of the $ method, which wraps DOM nodes with additional functionality.

These utility methods all address scripting needs that are so common that their names were made as concise as can be. Hence the $-based convention.

The most commonly used utility method is without doubt $(), which is, for instance, used pervasively within Prototype’s code to let you pass either element IDs or actual DOM element references just about anywhere an element argument is possible. It actually goes way beyond a simple wrapper around document.getElementById; check it out to see just how useful it is.

These methods are one of the cornerstones of efficient Prototype-based JavaScript coding. Take the time to learn them well.

$H

2006-10-28T20:32:00Z

$H([obj]) -> Hash

Creates a Hash (which is synonymous to “map” or “associative array” for our purposes). A convenience wrapper around the Hash constructor, with a safeguard that lets you pass an existing Hash object and get it back untouched (instead of uselessly cloning it).

The $H function is the shorter way to obtain a hash (prior to 1.5 final, it was the only proper way of getting one).

$R

2006-10-28T20:32:00Z

$R(start, end[, exclusive = false]) -> ObjectRange

Creates a new ObjectRange object. This method is a convenience wrapper around the ObjectRange constructor, but $R is the preferred alias.

ObjectRange instances represent a range of consecutive values, be they numerical, textual, or of another type that semantically supports value ranges. See the type’s documentation for further details, and to discover how your own objects can support value ranges.

The $R function takes exactly the same arguments as the original constructor: the lower and upper bounds (value of the same, proper type), and whether the upper bound is exclusive or not. By default, the upper bound is inclusive.

Examples


$R(0, 10).include(10)
// -> true

$A($R(0, 5)).join(', ')
// -> '0, 1, 2, 3, 4, 5'

$A($R('aa', 'ah')).join(', ')
// -> 'aa, ab, ac, ad, ae, af, ag, ah'

$R(0, 10, true).include(10)
// -> false

$R(0, 10, true).each(function(value) {
  // invoked 10 times for value = 0 to 9
});

Note that ObjectRange mixes in the Enumerable module: this makes it easy to convert a range to an Array (Enumerable provides the toArray method, which makes the $A conversion straightforward), or to iterate through values. (Note, however, that getting the bounds back will be more efficiently done using the start and end properties than calling the min() and max() methods).

$A

2006-10-28T20:31:00Z

$A(iterable) -> actualArray

Accepts an array-like collection (anything with numeric indices) and returns its equivalent as an actual Array object. This method is a convenience alias of Array.from, but is the preferred way of casting to an Array.

The primary use of $A() is to obtain an actual Array object based on anything that could pass as an array (e.g. the NodeList or HTMLCollection objects returned by numerous DOM methods, or the predefined arguments reference within your functions).

The reason you would want an actual Array is simple: Prototype extends Array to equip it with numerous extra methods, and also mixes in the Enumerable module, which brings in another boatload of nifty methods. Therefore, in Prototype, actual Arrays trump any other collection type you might otherwise get.

The conversion performed is rather simple: null, undefined and false become an empty array; any object featuring an explicit toArray method (as many Prototype objects do) has it invoked; otherwise, we assume the argument "looks like an array" (e.g. features a length property and the [] operator), and iterate over its components in the usual way.

Examples

The well-known DOM method document.getElementsByTagName() doesn't return an Array, but a NodeList object that implements the basic array "interface." Internet Explorer does not allow us to extend Enumerable onto NodeList.prototype, so instead we cast the returned NodeList to an Array:


var paras = $A(document.getElementsByTagName('p'));
paras.each(Element.hide);
$(paras.last()).show();

Notice we had to use each and Element.hide because $A doesn't perform DOM extensions, since the array could contain anything (not just DOM elements). To use the hide instance method we first must make sure all the target elements are extended:


$A(document.getElementsByTagName('p')).map(Element.extend).invoke('hide');

Want to display your arguments easily? Array features a join method, but the arguments value that exists in all functions does not inherit from Array. So, the tough way, or the easy way?


// The hard way...
function showArgs() {
  alert(Array.prototype.join.call(arguments, ', '));
}

// The easy way...
function showArgs() {
  alert($A(arguments).join(', '));
}

$F

2006-10-28T20:29:00Z

$F(element) -> value

Returns the value of a form control. This is a convenience alias of Form.Element.getValue. Refer to it for full details.

$$

2006-10-28T20:28:00Z

$$(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.

Quick 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'

The $$ function searches the entire document. For selector queries on more specific sections of a document, use Element#getElementsBySelector.

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.

supported in v1.5.0

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="Hello World!"]).
Class selector: CSS class names, as in .highlighted or .example.wrong.
ID selector: as in #item1.

supported from v1.5.1

Virtually all of CSS3 is supported, with the exception of pseudo-elements (like ::first-letter) and some pseudo-classes (like :hover). Some examples of new selectors that can be used in 1.5.1:

Child selector: selects immediate descendants, as in #a > li.
Attribute selectors: all attribute operators are supported, including ~= (matches part of a space-delimited attribute value, like rel or class); ^= (matches the beginning of a value); $= (matches the end of a value); and *= (matches any part of the value).
The :not pseudo-class, as in #a *:not(li) (matches all descendants of #a that aren't LIs).
All the :nth, :first, and :last pseudo-classes. Examples include tr:nth-child(even) (all even table rows), li:first-child (the first item in any list), or p:nth-last-of-type(3) (the third-to-last paragraph on the page).
The :empty pseudo-class (for selecting elements without children or text content).
The :enabled, :disabled, and :checked pseudo-classes (for use with form controls).

Examples

$$('#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 a', '#sidebar a');
// -> all links within the elements of ID "navbar" or "sidebar"

With version 1.5.1 and above you can do various types of advanced selectors:

$$('a:not([rel~=nofollow])');
// -> all links, excluding those whose rel attribute contains the word "nofollow"

$$('table tbody > tr:nth-child(even)');
// -> all even rows within all table bodies

$$('div:empty');
// -> all DIVs without content (i.e., whitespace-only)

$

2006-10-28T20:23:00Z

$(id | element) -> HTMLElement
$((id | element)...) -> [HTMLElement...]

If provided with a string, returns the element in the document with matching ID; otherwise returns the passed element. Takes in an arbitrary number of arguments. All elements returned by the function are extended with Prototype DOM extensions.

The $ function is the cornerstone of Prototype, its Swiss Army knife. Not only does it provide a handy alias for document.getElementById, it also lets you pass indifferently IDs (strings) or DOM node references to your functions:


function foo(element) {
    element = $(element);
    /*  rest of the function... */
}

Code written this way is flexible — you can pass it the ID of the element or the element itself without any type sniffing.

Invoking it with only one argument returns the element, while invoking it with multiple arguments returns an array of elements (and this works recursively: if you're twisted, you could pass it an array containing some arrays, and so forth). As this is dependent on getElementById, W3C specs apply: nonexistent IDs will yield null and IDs present multiple times in the DOM will yield erratic results. If you're assigning the same ID to multiple elements, you're doing it wrong!

The function also extends every returned element with Element.extend so you can use Prototype's DOM extensions on it. In the following code, the two lines are equivalent. However, the second one feels significantly more object-oriented:


// Note quite OOP-like...
Element.hide('itemId');
// A cleaner feel, thanks to guaranted extension
$('itemId').hide();

However, when using iterators, leveraging the $ function makes for more elegant, more concise, and also more efficient code:


['item1', 'item2', 'item3'].each(Element.hide);
// The better way:
$('item1', 'item2', 'item3').invoke('hide');

See How Prototype extends the DOM for more info.