Image preloading

Most of the times you’ll need preloading when there are elements in the DOM that are hidden, but have an image background. On the moment the elements are shown and the images are not found in cache, the images are loaded from the server. This action has a small delay, so your element first shows up without the image background. That might confuse the visitor.

Note that there are other possible scenario’s that need image preloading, but this case is a nice introduction.

Delaying image preloading

Why in the world would we like to delay the preloading of the images? Well, most browsers only allow two concurrent requests at the same time to the same domain (correct me if I’m wrong). When we do the image preloading on domready, it might hold up other resources that need to be loaded. Because we preload images that are not shown when the page loads, we can delay the preloading.

The javascript

Let’s say we have a total of five images that need to be preloaded. Here’s how I would preload the image, 3 seconds after the dom is ready:

Array.each.delay(3000,this,[
	['foo.gif', 'bar.png','moo.png','tools.png', 'mootools.png'],
	function(src){var img = new Image();img.src = src;}
]);

Easy huh? It delays a call to Array.each by 3000 ms. Then it passes the array of images as the first argument, and the function as the second. You can read more about delay at the Mootools Docs.

My tiny feed reader

The Feed Reader

This feed reader polls the COLOURlovers.com Palettes feed and Colours feed every 20 seconds for new items. New items are highlighted with the MooTools Element.highlight() function. The Google AJAX Feed API passes JSON to a callback function, which adds the new ‘colour’ or ‘palette’ entries to the list. Below you can see the uncommented code. The feed reader example contains a commented version.

var Site = {
	entries: [],
	timer: 0,
	init: function(){
		this.paletteFeed = new google.feeds.Feed('http://feeds.feedburner.com/ColourloversCoup0Palettes/New');
		this.colourFeed = new google.feeds.Feed('http://feeds.feedburner.com/ColourloversCoup0Colours/New');
		this.poll.periodical(1000, this);
	},
	poll: function(){
		if (--this.timer <= 0) {
			this.colourFeed.load(this.onLoadCallback.bind(this));
			this.paletteFeed.load(this.onLoadCallback.bind(this));
			this.timer = 20;
		}
		$('refresh').set('html','Refreshing feeds in ' + this.timer + ' second(s)...');
	},
	onLoadCallback:function(json){
		if (json.error) return;
		for (var i = json.feed.entries.length - 1; i >= 0; i--) {
			var entry = json.feed.entries[i];
			if (!this.entries.contains(entry.title)) {
				this.entries.push(entry.title);
				$('feeds').innerHTML = ('<li class="entry"><a href="{link}" title="{title}">{content}</a></li>').substitute(entry) + $('feeds').innerHTML;
			}
		}
		$$('.entry').set('tween',{duration:2000}).highlight().removeClass('entry');
	}
};
google.load('feeds', '1');
window.addEvent('domready', Site.init.bind(Site));

What’s next?

• Google AJAX Feed API
• MooTools Docs

Mootools Powered Scrollbar

Update: making it work with Mootools 1.11

It’s easy to get his working under Mootools 1.11. The syntax for getting the scrollsizes and sizes in Mootools 1.2b2 has changed a bit:

// => Mootools 1.2b2, elements' size and vertical scrollsize
var size = element.getSize().y;
var scrollSize = element.getScrollSize().y;
// => Mootools 1.11, elements' size and vertical scrollsize
var size = element.getSize().size.y;
var scrollSize = element.getSize().scrollSize.y;

For the scrollbars, I’ve used the size and scrollsize of the content element. So to get the scrollbars working under Mootools 1.11, you have to change only one line per scrollbar (see the steps option):

// => For vertical scrollbars
...
new Slider(scrollbar, handle, {
	steps: content.getSize().scrollSize.y - content3.getSize().size.y,
	mode: 'vertical',
...
// => For horizontol scrollbars
...
new Slider(scrollbar, handle, {
	steps: content.getSize().scrollSize.x - content3.getSize().size.x,
	mode: 'vertical',
...

Where to start

I assume you’re familiar with SVN, for those not, the SVN Book is a good place to start. My development environment looks like this:

• Eclipse IDE for Java Developers
• Downloaded Aptana as an Eclipse plugin
• Subclipse, Eclipse SVN plugin

Of course you don’t need all this, you can also use the Turtoise SVN Browser and use the IDE of your choice. Next step, is to checkout the Mootools SVN trunk, by pointing your SVN browser to http://svn.mootools.net/trunk. The trunk holds the latest development version of Mootools. In Aptana, you can do the following: File › New › Other › SVN › Checkout Projects from SVN › Create new repository location. The rest you can figure out yourself.

Zillions of files

Once you have downloaded the trunk, you can see a few folders, which are containing a lot of files. Now, what to do if you want to test your own code with the SVN trunk version of Mootools, and you don’t like to use the download builder? Very easy if you ask me. Just do the following:

• Create a new folder in the trunk root (ex. MyFolder)
• Create a new HTML file (ex. index.html)

Your filestructure should look something like this:

Example Mootools File structure

Now we need some code that includes all trunk javascript files from the Source folder into the document. This can easily be done by the following piece of code:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
		<title>Untitled Document</title>
		<script type="text/javascript" src="../Specs/Builder.js"></script>
		<script type="text/javascript">
			// This code includes all js files from the Source folder
			Builder.includeType('source');
		</script>
	</head>
	<body>
		<script type="text/javascript">
			window.addEvent('load', function(){
				alert('Version: ' + MooTools.version);
			});
			window.addEvent('domready', function(){
				alert('This alert won\'t show up!');
			});
		</script>
	</body>
</html>

When the page has loaded it alerts the Mootools version.

Important

As you can see in the code above I added an event handler to the load event of the window. Of course this is a bad practice, I should use the ‘domready’ event, which is fired sooner because it doesn’t wait on images to load. In this case I have to use the load event, because we include the javascript code for the ‘domready’ event when the page is already loading. So the ‘domready’ event doesn’t even fire.

So now you can test like a real pro and use the SVN trunk code to stay ahead of version changes. How did you test before? Share it by leaving a comment.

The Mootools Download Builder

Bookmarklets

Wikipedia has the following to say about bookmarklets:

A bookmarklet is an applet, a small computer application, stored as the URL of a bookmark in a web browser or as a hyperlink on a web page.

So it’s a small piece of javascript, that can be saved as a bookmark, and executed when the bookmark is pressed.

For the Mootools Download Builder I wrote a bookmarklet that toggles all checkboxes. It looks like this:

// Name of the Download Builder function to execute ('none' or 'all').
var function_name;	

// Boolean: true when all checkboxes are checked, false otherwise.
var checked_all = Download.chks.every(function(chk){
	return chk.hasClass('selected')
});

// Determine which function to execute.
if(checked_all){
	// All checkboxes are checked, so execute Download.none().
	function_name =  'none';
}else{
	// No checkboxes are checked, so execute Download.all().
	function_name =  'all';
} 

// Toggle all checkboxes.
Download[function_name]();

Because bookmarklets can have to be on a single line, I wrote a compact version of the code above:

// Compact version of the bookmarklet.
Download[Download.chks.every(function(chk){return chk.hasClass('selected')})?'none':'all']();

The HTML for the bookmarklet looks like this:

// HTML for the bookmarklet
<a href="javascript:Download[Download.chks.every(function(chk){return chk.hasClass('selected')})?'none':'all']();">Toggle Mootools Components</a>

To test it, bookmark the following link: Toggle Mootools Components. Then go to the Mootools Download Builder, and press the bookmarklet. You can see all components are toggled.

Mootools Download Builders

No, it’s not a typo, there are several download builder around. They’re all different.

• http://mootools.net/download/: Build Mootools using the latest stable components.
• http://mootools.net/download/tags/1-2b1: Build Mootools using the 1.2 beta1 components.
• http://mootools.net/download/trunk: Build Mootools using the latest svn revision.

The $ (dollar) function

Most people think this is just a shortcut for document.getElementById(), but actually it’s not. The $() takes one argument. This argument is called mixed in php terms, because it can be a string, or a dom element. Whenever the argument is a string s, it returns the element with id s with all Element methods applied. When the argument is a dom element, it just applies all Element methods to the element, and returns it. Here’s how it works:

var w3cEl = document.getElementById('myDiv'); // w3cEl => W3C dom element
var mooEl = $('myDiv'); // mooEl => Mootools Element
var mooEl2 = $(w3cRef); // mooEl2 => Mootools Element
var mooEl3 = $(mooEl2); // mooEl3 => mooEl2

So the $ function applies the Element methods to it’s argument. When passing a Mootools Element to $ it ‘ll be detected and no methods are applied, because the argument already has those methods (see example above mooEl3).

The $$ (double dollar) function

The double dollar function is more like document.getElementsByTagName() on steroids, both will return an array with multiple elements.

var w3cArr = document.getElementsByTagName('div'); // w3cArr => Array of W3C dom elements
var mooArr = $$('div'); // mooArr => Array of Mootools Elements

But $$ can do more. It’ll accept one or more css selectors (or elements) and return an array of elements matching those selectors:

$$('a.external'); // => Array of links with class 'external'
$$('a[href=#]'); // => Array of links with href="#"
$$('form input[disabled]'); // Array of input elements inside a form with a disabled attribute
$$('form input[disabled=disabled]'); // Array of disabled input elements inside a form (valid XHTML)
$$('div[class^=foo]'); // => Array of divs with classname starting with 'foo'
$$('[class$=bar]'); // => Array of elements with classname ending with 'bar'
$$('*[class$=bar]'); // => Returns the same as the previous selector

Want to know more about the css3 selectors? Read the W3C css3 selector specification. Keep in mind the Mootools $$ function doesn’t support all selectors.

The $E function

This function is very much like the $ function. The first argument of $E is a css selector string and it returns the first found element found with the selector. The second element is the filter (id string or DOM element). See it like a scope, when the filter is passed, the selector is executed inside the filter element. So instead of passing an id to the dollar function, you can pass a css selector to $E.

$E('div#foo'); // => Same as $('foo')
$E('ul#bar li'); // => The first list item of the unordered list with id 'bar'
$E('form input[type=checkbox]'); // => First checkbox of the first form
$E('input[type=checkbox]', 'myForm'); // => First checkbox of the element with id 'myForm'

The $ES (Element.getElements) function

The $ES function is very much the same as the $$ and the $E functions. The first argument is the css selector, and the second argument is the filter. $ES returns an array of elements found with the css selector, which is executed inside the filter element. It’s pretty straightforward:

$ES('a.external'); // => Same as $$('a.external')
$ES('a.external', document); // => Same as $ES('a.external')
$ES('input', 'myForm'); // => Array of input elements within the element with id 'myForm'
$ES('input[type=text]', 'myForm'); // => Array of textbox elements within the element with id 'myForm'

Bonus: other $ functions

There are some more dollar function that come with Mootools:

• $chk: Returns true if the passed in value/object exists or is 0, otherwise returns false.
• $clear: Clears a timeout or an Interval.
• $defined: Returns true if the passed in value/object is defined, that means is not null or undefined.
• $extend: Copies all the properties from the second passed object to the first passed Object.
• $merge: Merges a number of objects recursively without referencing them or their sub-objects.
• $native: Will add a .extend method to the objects passed as a parameter, but the property passed in will be copied to the object’s prototype only if non previously existent.
• $pick: Returns the first object if defined, otherwise returns the second.
• $random: Returns a random integer number between the two passed in values.
• $time: Returns the current timestamp.
• $type: Returns the type of object that matches the element passed in.
• $A: Returns a copy of the passed Array.
• $each: Use to iterate through iterables that are not regular arrays, such as builtin getElementsByTagName calls, arguments of a function, or an object.
• $H: Shortcut to create a Hash from an Object.
• $RGB: Shortcut to create a new color, based on red, green, blue values.
• $HSV: Shortcut to create a new color, based on hue, saturation, brightness values.

Setting up the form

First, we need a form. So let’s make a simple comment form:

<form id=\"myForm\" action=\"script.php\">
	<table cellpadding=\"0\" cellspacing=\"0\">
		<col width=\"100\">
		<col width=\"200\">
		<tr>
			<td>Name:</td>
			<td><input type=\"text\" name=\"author\" value=\"\" /></td>
		</tr>
		<tr>
			<td>Email:</td>
			<td><input type=\"text\" name=\"email\" value=\"\" /></td>
		</tr>
		<tr>
			<td>Comment:</td>
			<td><textarea name=\"comment\"></textarea></td>
		</tr>
		<tr>
			<td colspan=\"2\"><input type=\"submit\" id=\"submit\" value=\"submit\" /></td>
		</tr>
	</table>
</form>

This form consists of four controls. Two textboxes for the authors name and email address, a textarea for the comment text and a submit button. In the next part I’ll explain how to submit the form asynchronously using Mootools.

Submit the form using Ajax

It’s surprising how easy it is to submit the form using ajax. Basically we need to do three things:

1. Listen for the ‘click’ event on the submit button.
2. Stop the event from submitting the form.
3. Send the form using $(formElement).send()

A solution could look something like this:

$('submit').addEvent( 'click', function(evt){
	// Stops the submission of the form.
	new Event(evt).stop();

	// Sends the form to the action path,
	// which is 'script.php'
	$('myForm').send();
} );

Ok, that’s cool, we can submit a form asynchronously in about three lines of code. But this is not all, when using ajax for form submission, you need to let the user know what is happening/has happened. In the next part I’ll tell how to do that.

Show progress to the user

When you’re using ajax to submit a form, you need to show the user that something is going on in the background. A way to do that is to show an animated ajax loader gif. At ajaxload.info you can generate pretty sweet ajax loaders. First choose from around 20 different animated gifs, and specify the back and foreground color. In the article ‘Mootools: Ajax & XHR classes’ I explained how to show and hide the loader gif. To give you a quick example, here’s how to do it, with GMail style progress indicators:

// Variable that holds the effects.
var fx = {
	'loading': new Fx.Style( 'loading', 'opacity',{ duration: 200 } ),
	'success': new Fx.Style( 'success', 'opacity',{ duration: 200 } ),
	'fail': new Fx.Style( 'fail', 'opacity',{ duration: 200 } )
};

// Hides the loading div, and shows the el div for
// a period of four seconds.
var showHide = function( el ){
	fx.loading.set(0);
	(fx[ el ]).start(0,1);
	(function(){ (fx[ el ]).start(1,0); }).delay( 4000 );
}

// Listen for click events on the submit button.
$('submit').addEvent( 'click', function(evt){
	// Stops the submission of the form.
	new Event(evt).stop();

	// Sends the form to the action path,
	// which is 'script.php'.
	$('myForm').send({
		onRequest: function(){
			// Show loading div.
			fx.loading.start( 0,1 );
		},
		onSuccess: function(){
			// Hide loading and show success for 3 seconds.
			showHide( 'success' );
		},
		onFailure: function(){
			// Hide loading and show fail for 3 seconds.
			showHide( 'fail' );
		}
	});
} );

Putting this all together, and style things a bit, we get a responsive form which submission is asynchronous. You can go see the example, or you can download the zipped example code.

Using th XHR class

The XHR class is new since Mootools 1.0. It’s a basic wrapper for the XMLHTTPRequest. To have a better understanding of the options of the XHR class let’s take a look at it’s source.

var XHR = new Class({

	options: {
		method: 'post',
		async: true,
		onRequest: Class.empty,
		onStateChange: Class.empty,
		onSuccess: Class.empty,
		onFailure: Class.empty,
		headers: {}
	},

	initialize: function(options){
	...

So you can see the default values for the options. The meaning of each options is described in the Mootools docs. As you can see an XHR object is initialized by new XHR({options object}). No url is set when making a new XHR object. Here’s a basic example of an ajax call to 'location/myscript.php' and when the call’s successfull it let shows you the response in an alert box.

var showSuccess = new function(req){
	alert(req);
};

//a GET request
new XHR({method: 'get', onSucces: showSuccess}).send('location/myscript.php', 'answerme=1&q=test');

//this does the same, but using POST
new XHR({onSuccess: showSucces}).send('location/myscript.php', 'answerme=1&q=test');

Using the Ajax class

In the old Mootools there where two constructors for the Ajax class. New Ajax objects were created by new ajax(...) and new Ajax(...). In version 1.0 it’s only possible to use new Ajax(...).

The Ajax class is a very simple way to make requests to server-side scripts. Now, check the following code, it’s a small part of the Ajax class I took from SVN lately.

var Ajax = XHR.extend({

	options: {
		postBody: null,
		update: null,
		onComplete: Class.empty,
		evalScripts: false,
		evalResponse: false,
		encoding: 'utf-8'
	},

	initialize: function(url, options){

What exactly can we learn from this code? We can see the the Ajax class extend the XHR object, so it depends on the XHR class. We can also see that the Ajax class is initialized by new Ajax(url,options) where url is a string containing the location of a server-side script. The second argument is the options object, of which we can see the default in the default options object of the Ajax class. The options shown in are not the complete set of options. Because Ajax extends the XHR class, the options of the XHR class can also be set. Here’s an example of how to make a POST request to a script located at 'location/myscript.php', the response will be shown when the call fails.

var showFailure = function(){
	alert('Call failed!');
}

new Ajax('location/myscript.php', {postBody:'answerme=1&q=2', onFailure: showFailure}).request();

As you can see the onFailure option isn’t set in the default options of the Ajax class. The Ajax class takes the onFailure option from the XHR class because it extends it.

Which one should I use?

Ok, Mootools provides two classes for making ajax calls, which should you use? If, you’re sending forms by the use of asynchronous requests, you should use the Ajax class. In the Mootools docs is described how to send a form through ajax. In most other ways you won’t need it and you’ll be good with the XHR class.

A more advanced example

Here’s an example that shows an ajax loader image when the request is being processed:

//element with the ajax loader image
var loadingImg = $('ajaxLoader');

//function that switches visibility of loadingImg
var showLoad = new function(show){
	if(show){
		loadingImg.style.display = 'block';
	}else{
		loadingImg.style.display = 'none';
	}
};

//request function
var xhrFunc = new function(){
	//show loader image
	showLoad(true);

	new XHR({
		onSuccess: function(req){
			//hide image
			showLoad(false);
			//alert request
			alert(req);
		}}).send('location/myscript.php','answerme=1');
};

This should get you started, for further reading I refer to my older article about the ajax class.