Observing Ajax requests

So with the Ajax.Responders object we can observe all kinds of events, fired by Ajax.Request, Ajax.Updater and Ajax.PeriodicalUpdater. These are the events that are observable by Ajax.Responders:

• onCreate
• onComplete
• onException
• onInteractive
• onLoaded
• onLoading
• onUninitialized

You can read more about these events on the Prototype API docs. With the Ajax.Responders object we can register callback functions on these events. In the following example I’ll show how to monitor Ajax requests using Google Analytics.

Ajax.Responders.register({
	onComplete: function(request){
		// Check if urchinTracker function is available.
		if(typeof(urchinTracker) == 'function' && request && request.url){
			// Notice Analytics about the completed request.
			urchinTracker(request.url);
		}
	}
});

You can also unregister callback functions. Read more about it at the Prototype API docs.

Observing events

Let’s start by looking at how we can observe events. Imagine we have a form with a button and we want to be noticed when someone clicks it. The id of the button will be ‘button’. The event we’ll be observing is the click event. In the old days, assigned observer function to DOM elements with the ‘onclick’ attribute:

<input type="button" onclick="javascript:buttonClick(event);" id="button"  value="Ok"/>
<script type="text/javascript">
	function buttonClick(event){
		alert(event);
	}
</script>

This shows a very important point: the DOM element you want to observe events from, must exist in the DOM.

With Prototype, we can do things more unobtrusive:

<input type="button" id="button" value="Ok"/>
<script type="text/javascript">
	// One way to observe the click event on the button
	Element.observe('button', 'click', buttonClick);

	// Another way, but has the same result
	$('button').observe('click', buttonClick);

	function buttonClick(event){
		alert(event);
	}
</script>

If you’re confused by all this, you’d better read more about the Event Class in the Prototype API. If you’re more like, ‘hey, let’s fire some events’, just read on.

Firing custom events

Most of the other well known Javascript Frameworks already had the functionality to fire custom events, and it took way too long (imo) before it appeared in Prototype. Anyway, firing events with Prototype is a bit different than other Frameworks. To fire an event, you must (!) add a namespace to the event name, otherwise it won’t fire. A custom event then would look like this: 'namespace:eventname'. This is what Sam has to say about it:

A small but important change was made to custom events in [7835]: all custom event names must now include a namespace. This is our solution to the problem of custom event names conflicting with non-standard native DOM events, such as “mousewheel” and “DOMMouseScroll.”

In the next example I’ll show how to fire the event ‘bar’ in the ‘foo’ namespace (so the event name will be ‘foo:bar’). Passed argument can be accessed by event.memo.

// Function that fires the 'bar' event in the 'foo'
// namespace. Note the second argument of the fire method.
setTimeout(function(){
	$('button').fire('foo:bar', 'foobarbaz');
}, 10000);	

// Let's listen for the 'foo:bar' event.
$('button').observe('foo:bar', function(evt){
	alert(evt.memo); // => foobarbaz
});

The Prototype custom ‘dom:loaded’ event

Prototype 1.6.0 final also comes with the 'dom:loaded' event which is fired by the document object. This event’s fired when the DOM tree is loaded, without waiting for images. This event fires somewhat faster than the window load event, depending on the number of images on the page. The following ‘bonus’ example shows the usage of the ‘dom:loaded’ event:

// This global variable is set when the dom finishes loading.
var domloaded;

// This custom event is fired when the DOM's finished loading.
// dom:loaded event fires before the window load event.
Element.observe(document, 'dom:loaded', function(){
	domloaded = new Date().getTime();
});

// Observing the plain old window load event.
Element.observe(window, 'load', function(){
	var load = new Date().getTime();
	alert(load - domloaded); // +-35 (ms)
});

Changing Array.each

The Array.each function can be used to loop through all elements of an Array. This functions is used by all Enumerable functions. Here’s the javascript to let you Mootools’ Array.each work with Enumerable functions:

//needed for adding breaks in Enumerable functions
$break = new Object();
//function that just returns it argument,
//needed in Enumerable functions
Class.ret = function(arg) {return arg};

Array.extend({
	//copy 'native' Mootools Array.each to Array._each
	_each: Array.prototype.each,

	//'overwrite' Array.each to handle a
	//$break thrown by Enumerable functions
	each: function(fn, bind){
		try{
			//try to iterate the Array
			this._each(fn,bind);
		}catch(e){
			//handling a break
			if(e != $break) return e;
		}
	},

	//return the last element of an Array (used in Array.zip())
	last: function() {
   		return this[this.length - 1];
  	}
});

This code enables us to add Prototype’s Enumerable functions to an Array. Actually the only thing we’ve done is enabling our Mootools Array.each to handle a Prototype $break thrown by Enumerable functions.

Adding Enumerable functionality

Let’s start adding some functions. The first function we’ll add is Enumerable.all().

/**
 * Calls an iterator function to test the values in a
 * list to see if they are all true.
 * @name Array.all()
 * @param {Function} iterator
 *  -Iterator function to call. Arguments elementValue, and elementIndex
 * @return {Boolean} Returns
 *  -true if the iterator returns true for all elements.
 */
Array.extend({
	all: function(iterator) {
	    var result = true;
	    this.each(function(value, index) {
	      result = result && !!(iterator || Class.ret)(value, index);
	      if (!result) throw $break;
	    });
	    return result;
  	}
});

Ok, great job, but what does it do? Here’s an example:

//our sample array containing three strings
var sample = ['foo','bar','baz'];

//an iterator function that returns false
//when it's argument is equal to 'bar'
var iterator = function(obj, index){
	if(obj == 'bar'){
		return false;
	}
	return true;
};

//iterate the sample array with the iterator function
sample.all(iterator); // => returns false

//iterate the sample array with an anonymous function
//that returns true when it's argument is a string
sample.all(function(obj, index){
	if(typeof obj != 'string'){
		return false;
	}
	return true;
});// => returns true

The only thing I changed in the Enumerable.all() code was replacing Prototype.K with Class.ret which are basically the same functions with different names. They bot return their arguments. To see how I added the rest of the Enumerable functions take a look at my EnumArray.js file. And if you want some examples using these functions you really have to take a look at the ‘Prototype Meets Ruby: A Look at Enumerable, Array and Hash’ article written by Justin Palmer. Eventually you can take a look at my ajax resource site for more Prototype related links.

Smaller filesize?

The EnumArray.js’s filesize is quite large (10.5 kb). I’m pretty sure you don’t need all the Enumerable functions for your arrays so you could remove the function you don’t need. Let’s say we only need the Array.findAll and Array.zip function, then our code will look something like this:

$break = new Object();
Class.ret = function(arg) {return arg};

Array.extend({
	//always include this function
	_each: Array.prototype.each,

	//always include this function
	each: function(fn, bind){
		try{
			this._each(fn,bind);
		}catch(e){
			if(e != $break) return e;
		}
	},

	//needed by Array.zip
	last: function() {
   		return this[this.length - 1];
  	},

	findAll: function(iterator) {
		var results = [];
		this.each(function(value, index) {
	    	if (iterator(value, index))
	        	results.push(value);
	    });
	    return results;
	},

	//zip needs Array.last
	zip: function() {
	    var iterator = Class.ret, args = $A(arguments);
	    if (typeof args.last() == 'function')
			iterator = args.pop();

	    var collections = [this].concat(args).map($A);
	    return this.map(function(value, index) {
	      	iterator(value = collections.pluck(index));
	      	return value;
	    });
	}
});

This is a lot less code than the full EnumArray.js. For further compression you should use Dean Edward’s packer tool.