The $ function is a shortcut and extension of one of the most commonly used functions in all JavaScript browser programming: document.getElementByID. The name is so short because it is used so often, according to one of the main principles of effective API design.

You may pass $() one or more strings, to which it will return either one matching element or an array of them, assuming the supplied ID strings match elements present on the page. For convenience, $ will not blow up if you pass it an element instance rather than a string in its parameters. It will simply pass the element back to you or add it to its results list.

ID parameters without matching elements will result in undefined return values, just like with the underlying document.getElementByID function. Trying to retrieve more than one element with the same ID will probably not work, and is dependent on the browser implementation. It’s better to stick to well-formed markup and not have duplicate identifiers.

The $$ function takes one or more CSS selector strings and returns an array of matching elements from the DOM. The ability to find elements by CSS selector is one of the most powerful features of Prototype.

The $A function is an alias for Array.from. It converts its parameter into an Array object, including the functions of Enumerable. (See the section “Enumerable” in this chapter.)

Inside Prototype, $A is mostly used for converting lists of arguments and DOM nodes into arrays. Note that the latest versions of Prototype mix enumerable functions right into JavaScript’s native Array object, which makes this function of very little use.

The $F function is an alias for Form.Element.getValue. It returns the value of any form field on a page, by ID. It is a useful convenience method because it works regardless of whether you pass it a text input, a select input, or a text area.

The $H function extends a plain JavaScript object with the functions of Enumerable and Hash making it resemble a hash in Ruby. (See the section “Hash” in this chapter.)

The $R function is a shortcut for the ObjectRange constructor. (See the section “ObjectRange” in this chapter.)

This is not exactly a top-level function, but it made the most sense to me to include it in this section, since these is the only function of the Try object.

When doing cross-browser-compatible operations, it’s quite common to need to try a couple of different ways of doing something until one of them works. The Try object defines a these function, to which you pass a list of functions that should be attempted until one doesn’t throw an exception.

A classic example, taken right from the Prototype codebase, is the way that you grab a reference to the XMLHttpRequest object, which varies significantly between Firefox and Internet Explorer:

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

  activeRequestCount: 0
}

Returns a copy of the object supplied as a parameter, by using it to extend a new Object instance:

clone: function(object) {
  return Object.extend({}, object);
}

The extend static function literally loops through every property of the supplied source object and copies them over to the destination object, including functions, thereby serving as an inheritance and cloning mechanism. (JavaScript doesn’t have built-in support for inheritance.)

The source code is instructional and simple enough to include here:

Object.extend = function(destination, source) {
  for (var property in source) {
    destination[property] = source[property];
  }
  return destination;
}

Objects in JavaScript behave almost exactly like associative arrays (or hashes) in other languages, and they’re used extensively in that fashion in JavaScript code. The keys static function returns a list of the properties defined on an object. The values static function returns a list of property values.

If the parameter is undefined (which is different than null in JavaScript), the static inspect function returns the string 'undefined'. If the parameter is null, it returns 'null'. If an inspect() function is defined on the parameter, it is invoked; otherwise, toString() is called as a final resort.

Removes all elements from the array and returns it. Interestingly enough, the implementation of this method simply sets the length of the array to zero:

clear: function() {
  this.length = 0;
  return this;
}

Removes all null and undefined elements from the array and returns it. Notice the use of select in the implementation:

compact: function() {
  return this.select(function(value) {
    return value != undefined || value != null;
  });
}

Returns the first and last elements of an array, respectively.

Takes the array and recursively flattens its contents into a new array, which is returned. In other words, this function iterates over the elements of the source array, and for each element that is an array, it extracts its elements into the new array to be returned. Notice the use of inject in the implementation:

flatten: function() {
  return this.inject([], function(array, value) {
    return array.concat(value && value.constructor == Array ?
      value.flatten() : [value]);
  });
}

Returns the index of a particular element belonging to an array or returns -1 if the element is not found.

indexOf: function(object) {
  for (var i = 0; i < this.length; i++)
    if (this[i] == object) return i;
  return -1;
  });
}

Overrides the default inspect and prints out the elements of the array delimited by commas.

indexOf: function() {
  return '[' + this.map(Object.inspect).join(', ') + ']';
}

Reverses the order of the array. The inline argument, which defaults to true, specifies whether to modify the receiving array or leave it in its original state.

Removes the first element of the array and returns it, causing the size of the array to shrink by 1.

Removes (or subtracts) the elements specified as arguments from the receiver. Takes either an array or list of elements to be removed, which is easily accomplished by wrapping arguments in a call to $A. Notice the use of select in the implementation:

without: function() {
  var values = $A(arguments);
  return this.select(function(value) {
    return !values.include(value);
  });
}

Returns the element that originated the event.

Traverses the DOM tree upward, starting from the element that originated the event. Returns the first element it finds that matches the tagName parameter (case-insensitive). If no matching parent element is found, this function returns the element that originated the event by default instead of erroring out, which can cause some confusion.

Returns true if a click of the left mouse button caused the event to occur.

The observe function wraps the browser’s own addEventListener function, which is part of the DOM Level 2 specification. It establishes an observer relationship between the specified element and an observer function. The element parameter may refer to a string ID or the element itself, quite often document in the case of mouse and keyboard events.

The stopObserving function is essentially the same except that it disconnects the event handler, and wraps the removeEventListener method of the DOM.

The name parameter refers to a valid event name (as a string), as defined in the DOM specification for browsers (blur, click, and so on).^[2]

The observer parameter should be a function reference, meaning the name of a function without parentheses (often a source of confusion!). In almost all cases, you will want to use the bindAsEventListener function in conjunction with observe, so that the event-handler function executes in the correct context. (See “Extensions to JavaScript’s Function Class” in the next section.)

The useCapture option can be used to specify that the handler should be called in the capture phase instead of the bubbling phase, and defaults to false.

Here’s an example of Event.observe taken from Scriptaculous’ AutoCompleter object:

addObservers: function(element) {
  Event.observe(element, "mouseover",
this.onHover.bindAsEventListener(this));
  Event.observe(element, "click", 
this.onClick.bindAsEventListener(this));
}

Returns x and y coordinates of the mouse pointer on the page when the event occurred.

Halts propagation of an event and cancels its default behavior, whatever that might have been.

Used to bind a function into the context of the object passed as a parameter. That parameter is almost always inevitably the value this, the current object context, because the main use for bind is to take a function that was defined elsewhere and make sure that it will execute with the exact context where you want it to be executed.

For example, see the way that the registerCallback function of PeriodicalExecuter is implemented:

registerCallback: function() {
  setInterval(this.onTimerEvent.bind(this), this.frequency * 1000);
}

It is necessary to bind the onTimerEvent function to execute in the context of whatever object the callback is being registered on, rather than the prototype object of the PeriodicalExecuter object itself.

Use of bind is admittedly a difficult concept to grasp, unless you are an experienced JavaScript programmer or have an affinity for functional programming, so don’t fret if you don’t understand it immediately.

Used to attach a function as a DOM event handler in such a way that the event object will get passed to the function as its parameter. Used in similar fashion to bind where you want to make sure that some method gets executed in the context of a particular instance, rather than the prototype class where it is defined. This method is not used by the Prototype library itself, but it is used extensively in Scriptaculous and in custom application JavaScript, whenever you want to create observer-style classes to contain event handlers bound to elements on a page.

The following code example is a custom class designed to alert you to changes in an input field with a customizable message:

var InputObserver = Class.create();
InputObserver.prototype = {
  initialize: function(input, message) {
    this.input = $(input);
    this.message = message;
    this.input.onchange = this.alertMessage.bindAsEventListener(this);
  },

  alertMessage: function(e) {
    alert(this.message + ' (' + e.type + ')'),
  }
};

var o = new InputObserver('id_of_some_input_field', 'Input field'),

Returns the hexadecimal representation of an integer RGB value.

toColorPart: function() {
  var digits = this.toString(16);
  if (this < 16) return '0' + digits;
  return digits;
},

Remember that numbers in JavaScript are not automatically auto-boxed, so to speak. You have to assign the number to a variable, wrap the value in a Number instance yourself, or simply put it in plain parentheses in order to be able to invoke functions on it. Not convinced? You can figure it out interactively using the FireBug console:

>>> 12.toColorPart();
missing ; before statement 12.toColorPart();
>>> n = new Number(12)
12
>>> n.toColorPart();
"0c"
>>> n = 12
12
>>> n.toColorPart();
"0c"
>>> (12).toColorPart();
"0c"
>>> 12.toColorPart
missing ; before statement 12.toColorPart
>>> (12).toColorPart
function()

Simply returns the next number:

succ: function() {
  return this + 1;
},

Just like the times method available on numerics in Ruby, number.times() takes a block of code and invokes it a number of times (according to the value of the number it is called on). Notice the use of $R to easily create a range, and each to invoke the supplied iterator function.

times: function(iterator) {
   $R(0, this, true).each(iterator);
   return this;
 }

Here’s a simple example that will pop up an alert box five times. Remember that you can’t invoke a JavaScript function directly on a raw number because it will confuse the parser, hence the extra parentheses are needed:

>>> (5).times(new Function("alert('yeah')"))
5

Turns dash-separated strings into lowerCamelCase.

>>> "about-to-be-camelized".camelize()
"aboutToBeCamelized"

Turns underscore-separated strings into dash-separated-strings.

>>> "about_to_be_dasherized".dasherize()
"about-to-be-dasherized"

The escapeHTML instance function escapes all HTML and XML markup in the receiving string, by turning the angle brackets of tags into entities.

>>> '<script src="http://evil.org/bad.js"/>'.escapeHTML()
"&lt;script src="http://evil.org/bad.js"/&gt;"

The unescapeHTML function reverses the operation.

The evalScripts instance function executes any <script> tags found in the receiving string.

The extractScripts instance function returns an array of strings containing the text of all <script> tags found in the receiving string. Note that the opening and closing <script> tags themselves are omitted; only JavaScript code is extracted.

The gsub instance function returns a copy of the receiving string, with all occurrences of pattern replaced with the value supplied in replacement. The receiving string is not modified. Pattern should be a literal JavaScript regular expression, delimited with “/” characters.

The sub function is similar to gsub, but only makes as many replacements as specified in the count parameter, which defaults to 1.

The scan instance function is very similar to gsub, except that it takes an iterator function instead of a replacement value.

The strip instance function removes leading and trailing whitespace. Notice the chained calls to replace in the implementation:

strip: function() {
  return this.replace(/^s+/, '').replace(/s+$/, ''),
}

The stripScripts instance function removes <script> tags (including their content) from the receiving string. The stripTags instance function removes all HTML and XML tags from the receiving string.

Both functions turn a query string (URL request format) into a JavaScript object.

>>> "?foo=bar&da=da+do+la".toQueryParams()
Object foo=bar da=da+do+la

Returns the characters of the receiving string as an array.

Works just like the truncate method that Rails mixes into strings. If the receiving string is longer than length, it will be truncated and the last three characters will be the truncationString (defaults to an ellipse, “...”).

>>> "Mary had a little lamb".truncate(14)
"Mary had a ..."

Practically a direct port of the underscore method mixed into strings in Rails. Turns camelCase strings into underscored form. Changes :: to / to convert Ruby-style namespaces to paths.

>>> "ActiveRecord::Foo::BarCamp".underscore()
"active_record/foo/bar_camp"

Holds the number of Ajax requests executing at any given moment, and there may be more than one since they fire asynchronously. Primarily used when implementing activity indicators (a.k.a. “spinners”), those little animated icons let the user know when communication with the server is happening:

Ajax.Responders.register({
  onCreate: function() {
    if($('busy') && Ajax.activeRequestCount > 0)
      Effect.Appear('busy', { duration:0.5, queue:'end' });
  },

  onComplete: function() {
    if($('busy') && Ajax.activeRequestCount == 0)
      Effect.Fade('busy', {duration:0.5, queue:'end' });
  }
});

Returns a reference to the XMLHttpRequestObject implementation provided by the browser. You don’t normally have to use this function yourself—it’s used internally by the other Ajax functions.

Adds responder objects to the list of registered responders interested in receiving Ajax-related events. Responders are invoked in the order in which they were registered, and they should implement at least one of the following Ajax callbacks: onCreate, onComplete, or onException.

Removes a responder from the list of registered responders.

The each function takes a function reference as its iterator parameter and invokes that function for each of its elements. The individual element is passed as the parameter to the iterator function.

Let’s look at a simple example, which will alert three times:

function alerter(msg) {
  alert(msg);
}

["foo", "bar", "baz"].each(alerter)

The way to pass a function by reference in JavaScript is to simply refer to it by name, leaving off the parentheses.

Here are the rest of the enumerable functions. Most iterator are invoked with two parameters: value and index.

The all function passes each element of the Enumerable object to the iterator, and returns true if the iterator function never returns false. If the iterator parameter is omitted, each element itself is considered in a Boolean context. You can think of the all function as a big Boolean AND operation.

The any function passes each element of the Enumerable object to the iterator, and returns true if the iterator function ever returns true. If the iterator parameter is omitted, each element itself is considered in a Boolean context. You can think of the any function as a big Boolean OR operation.

The collect function (aliased as map) returns the results of running the iterator function for each of the elements in an Enumerable object.

>>> $R(1,4).collect(Prototype.K) // K returns whatever you pass it
[1, 2, 3, 4]
>>> $R(1,4).collect(function(){return "cat"})
["cat", "cat", "cat", "cat"]

The detect function (aliased as find) is used to find the first element of an enumerable that matches criteria defined in the iterator function.

>>> $R(1,100).detect(function(i){ return i % 5 == 0 && i % 6 == 0 })
30

The eachSlice function splits the elements of the array into a number of slices as specified by the number parameter. Then it returns the results of calling collect with the optional iterator function, on the list of resulting slices, which effectively flattens the result back down into a single-dimension array.

>>> $R(1,10).eachSlice(5)
[[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]

>>> $R(1,10).eachSlice(2, function(slice) { return slice.first() })
[1, 3, 5, 7, 9]

The findAll function (aliased as select) is used to find all of the elements of an enumerable that match the criteria defined in the iterator function.

>>> $R(1,100).findAll(function(i){ return i % 5 == 0 && i % 6 == 0 })
[30, 60, 90]

The grep function returns all elements of an enumerable for which the regular expression passed as the pattern parameter matches with a non-null result.

The optional iterator function is invoked for any values that matched.

>>> quote = "The truth does not change according to our ability to
stomach it"
"The truth does not change according to our ability to stomach it"

>>> quote.split(' ').grep(/w{5}/)
["truth", "change", "according", "ability", "stomach"]

>>> quote.split(' ').grep(/w{5}/, function(val, i){ return i + ":" +
val })
["1:truth", "4:change", "5:according", "8:ability", "10:stomach"]

The include function (aliased as member) returns true if any member of the enumerable equals the obj parameter. The comparison is made using the == function.

>>> ['a','b','c'].include('a')
true
>>> ['a','b','c'].include('x')
false

The inGroupsOf function is kind of like eachSlice, but does not take an iterator. It always returns a two-dimensional array containing equal-sized groups, composed of the enumerable’s elements. The optional filler parameter allows you to specify a value that should be used to fill out the remaining slots, if any, on the last group, and defaults to null.

>>> $R(1,10).inGroupsOf(3)
 [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, null, null]]
>>> $R(1,10).inGroupsOf(3, 0) // pad with zeros
[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 0, 0]]

The inject function combines the elements of the enumerable, applying the iterator function to the accumulator and each element, in turn. At each iteration, the value of accumulator is set to the value returned by the iterator function. Unlike the Ruby version, Prototype’s inject requires an initial value for accumulator.

>>> $R(1,5).inject(0, function(acc, e) { return acc + e })
15

The invoke function invokes the function named by functionName to each element of the enumerable and collects the results. The optional parameters will be passed as parameters to the invoked function.

>>> $R(1,5).inject(0, function(acc, e) { return acc + e })
15

The max and min functions are very similar to each other, and return the elements of the enumerable of the highest and least values, respectively. An optional iterator function can be supplied to transform the value of the element that is used for comparison.

>>> $R(1,5).min()
1
>>> ["1","2","3"].max(function(val) { return Number(val) })
3

The partition function returns a two-item array. The first is an array containing the enumerable’s elements for which the optional iterator function returned true, and the second contains those elements for which it returned false. If an iterator is not supplied, the Boolean value of the element itself will be used.

>>> ["1",null,"2",null,null].partition()
[["1", "2"], [null, null, null]]

The pluck function conveniently plucks a list of property values from an enumerable. This is essentially a convenience method similar to collect.

>>> $$('script').pluck('src')
["http://localhost:3000/javascripts/prototype.js?1165877878",
 "http://localhost:3000/javascripts/effects.js?1161572695",
"http://localhost:3000/javascripts/dragdrop.js?1161572695",
"http://localhost:3000/javascripts/controls.js?1161572695",
"http://localhost:3000/javascripts/application.js?1161572695", ""]

The reject function returns elements of the enumerable for which the required iterator function returns false.

The sortBy function returns the elements of Enumerable sorted according to the criteria returned by the required iterator function.

Incidentally, when I was coming up with an example for this function, I realized that because I’m used to coding Ruby, I quite often forget to say return in the body of the iterator function. Unfortunately, that won’t usually cause the script to fail, and can be very confusing. Don’t forget that JavaScript functions need an explicit return statement!

>>> linusQuote = "Software is like sex: It's better when it's free."
"Software is like sex: It's better when it's free."
>>> linusQuote.split(' ').sortBy(function(s,index) { return s.length })
["is", "it's", "sex:", "It's", "like", "when", "free.", "better",
"Software"]

The toArray function (aliased as entries) returns the elements of the enumerable as an array.

The interesting zip function is modeled after the Ruby iterator of the same name. It has nothing to do with compression; rather, think of the behavior of a zipper on your clothing. The zip function merges the elements of each enumerable supplied as a parameter, such that the returned list has the same number of elements as the receiving enumerable does.

If the last (optional) parameter is a function, it is used as an iterator and invoked on each array element that will be returned. The easiest way to explain is probably to illustrate with an example, similar to the one presented in the “Pickaxe” book (Programming Ruby):

>>> a = [4, 5, 6]
[4, 5, 6]
>>> b = [7, 8, 9]
[7, 8, 9]
>>> [1, 2, 3].zip(a, b)
[[1, 4, 7], [2, 5, 8], [3, 6, 9]]

The keys and values functions return lists of keys and values, accordingly.

The merge function merges values passed in from another hash into the receiver. If any keys exist in both the receiver and passed-in hash, the value of the receiver’s entry will be overwritten.

>>> $H({foo:'foo', bar:'bar'}).merge({foo:'F00', baz:'baz'})
Object foo=F00 bar=bar baz=baz

The toQueryString function formats the key/value pairs of a hash as a query string appropriate for appending to a URL. It comes in very handy, compared to trying to construct query strings yourself:

>>> $H(Prototype).toQueryString()
"Version=1.5.0_rc2&BrowserFeatures=%5Bobject%20Object%5D&ScriptFragment
=(%3F%3A%3Cscript.*%3F%3E)((%0A%7C%0D%7C.)*%3F)(%3F%3A%3C%2Fscript%3E)"