Update: Moo.Ajax has become deprecated since I originally wrote this article, as its functionality has been incorporated into the new mootools library. I’ve written a follow-up piece that explains this same basic principal using the more current library. I’d suggest checking that out if you’re interested in a dead-simple introduction to ajax.

This is a very basic tutorial which offers a glance at the moo.ajax class from Mad 4 Milk. It doesn’t expand too much on the tutorial that they provide, but I feel that it will help clarify a few things. Don’t let the length of this article frighten you, what you are about to learn is pretty simple. I just use a lot of words to explain it. By the time you’ve worked through this tutorial, you will be able to build a form that interacts with a PHP script and returns data, without refreshing the page. It’s a pretty simple process that can serve as the basis for some very cool applications.

This tutorial should serve as an introduction to using moo.ajax for remote scripting. If you are familiar with the technologies in use—XHTML, JavaScript, and PHP—you should be able to take these founding principals and run with them to create something interesting and perhaps even useful. As a bonus, I’ve thrown in a bit about unobtrusive JavaScript and graceful degradation. These are important principals in the new era of web scripting, and learning about them will help make you a rock star of web development and get you millions of dollars, or at least ensure that your applications are the best that they can be.

Requirements

To complete this tutorial you will need the following:

• Some way to run PHP scripts. Many web hosts offer this. You can also set up a web server on your personal computer, which will make the development process much more simple.
• Prototype.lite.js. This is a stripped down version of the Prototype JavaScript library. It is available from Mad 4 Milk, or in the example source file that I’ve included.
• moo.ajax.js This contains the ajax class that we will use. Along with prototype.lite.js, it does most of the actual work. It’s also available from Mad 4 Milk, or in the example source file that I’ve included.
• That’s about it.

I’ve packaged up the entire example, including the JavaScript files from Mad 4 Milk so that you can follow along at home. You should be able to upload the files to your web host unmodified, and everything should work. When we get to the code I’ll assume that you’ve downloaded it, or at least viewed the example and peeked at the source.

• View the example
• Download the source

The Example—What’s Going On?

Our example contains a form with one input. When you submit the form, moo.ajax magically submits the input value to a PHP script, which does a little processing and then returns a value to the web page. All this happens without refreshing the page, which is exciting to myself and probably to you as well.

This example expects that you input a number. If you don’t do so, it politely asks you to try again. That’s about all you need to know to use it, so without further delay I’ll teach you how to build it.

Getting Started

At the heart of this whole thing is a simple html page with a simple form on it. I’ll assume you know how (or can figure out how) to tackle that portion of it. If not, you can see mine in the source code. Moving on, we add the follwing to the head of the document:

<script type="text/javascript" src="prototype.lite.js"></script>
<script type="text/javascript" src="moo.ajax.js"></script>

Here we’ve include the scripts that perform the magic. You can look at their contents in your free time. For now, we’ll just include them and hope that they work (don’t worry, they do.)

Get To The Cool Stuff Already!

OK, get ready. The next code snippet is where we do our thing, which is to tell moo.ajax to do it’s thing. Check this action out:

function letsRock()
{
	var postString = "thevalue=" + document.getElementById("thevalue").value;
	new ajax('data.php', {postBody: postString, update: 'output1', onComplete: itsOver});
}

function itsOver(request)
{
	document.getElementById("output2").innerHTML = request.responseText;
}

Well that was anti-climactic. Something as cool as ajax should require impossibly complicated scripts that make your friends jealous, right? Perhaps it should, but fortunately for us, it doesn’t. The cool folks at Mad 4 Milk have made our work easy by providing their tools. So what’s exactly is going on in this little snippet of code?

First, there’s the function letsRock(). This gets called when you submit the form. The first line of the function declares a variable postString and builds a string to be passed to the PHP script. If you entered 3 in the input field, the variable would store “thevalue=3“. This string can store multiple fields; use & to separate them.

The second line of our function creates a new ajax object (defined in moo.ajax.js.) The first parameter is the URL of the script we want to access through ajax (you’ll get a look at that script in a moment.) Next comes a list of options. postBody tells the ajax gods that we want to pass data to our PHP script using the post method (vs. get, just like with a regular form.) postString is the variable we defined on the previous line. Building a string variable might have been overkill here, but if we decide to pass a lot of data to the script it could become quite messy. Using a variable helps us keep the script clean-looking.

The next option calls the update method, which comes from moo.ajax.js. Specify the an DOM object or the id of an element and the update method (optional) takes the output of your PHP script and dumps it into that element rather than outputting to a new page as is typically would. In this case the output goes to one of two paragraphs just below the form.

Finally, the onComplete method (also from moo.ajax.js, also optional) runs a function of our choosing when the request is complete. I’ve chosen to run a function called itsOver, which just duplicates what already happened with the update method. I just did this to demonstrate two different ways of handling output. update is a simple, prebuilt way to display the results of our script call, and onComplete offers an infinitely flexible way to handle the next step once a request has been completed. Pick whichever one suits your needs best when building your own scripts.

Lets just take a quick peek at itsOver, since we already know what it’s doing. When the request is complete, the function is fired. The output element of choice is filled with the responseText (once again, provided by moo.ajax.js) which is the regular screen output of our PHP script. InnerHTML is a pretty good way to display this text, but not the best.

What about that PHP script? Let’s See That.

The PHP script in this example is very simple. All it does is take the value that you enter and multiply it by another number, to prove that it’s interacting with the server. Any PHP script can be used with the ajax call that we’ve made. In our case, we have 1 piece of post data to handle, and we’d like to return some output to display on the example page. Here’s the PHP script in its entirety:

<?
$multiplier = 4;
if ($result = $multiplier * $_POST['thevalue'])
	print "The result is " . $result . ". The multiplier that we used was " . $multiplier;
else
	print "Please enter a number";
?>

The first line sets a multiplier variable, which will be multiplied by the number that is submitted to the script. The next line is a simple if statement that multiplies the submitted value by the multiplier. If the value is a number, the calculation will be performed successfully and it will return true. Otherwise, the calculation will fail and return false. Again, I’d like to mention that this is a very basic script used only for demonstrative purposes. The sky is really the limit as far as what you can do here. We’re passing post values just like any normal form, so you can do anything here that you would in a normal PHP application.

Executing The Ajax Call

Next, we have a bit of scripting to add this functionality to our form. If you’re already familiar with the concepts of unobtrusive JavaScript, addEvent, and graceful degradation, you can just skip the rest of this tutorial, smarty-pants. The rest of you, have a peek at the rest of the JavaScript:

function addEvent( obj, type, fn )
{
	if (obj.addEventListener)
		obj.addEventListener( type, fn, false );
	else if (obj.attachEvent)
	{
		obj["e"+type+fn] = fn;
		obj[type+fn] = function() { obj["e"+type+fn]( window.event ); }
		obj.attachEvent( "on"+type, obj[type+fn] );
	}
}
function initializer() {
var testForm = document.getElementById('testform');
	addEvent(testForm, 'submit', letsRock);
	testForm.onsubmit = function() { return false; }
}
addEvent(window, 'load',initializer);
</script>

The addEvent function is a pretty common one, that has been written in many different ways. Basically, it adds an event listener (e.g. onclick or onmouseover) to an html object. The version that I’m using was grabbed from this post at quirksmode.org. For now, just include it in the file. In the future, you might want to put it in a separate file with other common functions, because you’ll want to use it constantly. "Why not just add and onclick to the form code?" you might ask. The short answer is that it keeps your code clean and easy to maintain–it’s called unobtrusive JavaScript, and it’s the right way to do it. A longer answer can be found via the DOM Scripting Task Force.

After our addEvent function, we have a function called initializer. This uncreatively named function prepares the form to do it’s ajaxy thing. First, we declare a variable and store a reference to our form, for ease of use in the next two lines. Then we use addEvent to make the form to execute our letsRock function (defined above) when it is submitted. Then, we tell the form to return false when it is submitted. This prevents the form from bringing us directly to the PHP page when it the user presses "Submit", and instead allows letsRock to do it’s work.

Finally, we use another addEvent to attach our initializer function to the onload event handler for the web browser window. This means that once the window loads, and all the elements have been created, the other events will be attached. This prevents errors that can be caused by trying to modify a page element before it is created.

An interesting thing to note about all this JavaScript is that the form will work without it. Don’t believe me? Go ahead and try it with JavaScript turned off. The output isn’t as pretty, but you get the same information. This is what’s meant by “graceful degredation”–whenever possible, you should write applications that will work without JavaScript. This allows your application to be functional to the greatest number of users.

What’s Left?

Not much. All we have to do is build the HTML page. The tricky stuff is over. The rest of the code is available in the file download or the example source, so I won’t bother repeating it here.

In case you missed it before, here’s the example again.

Debriefing

I’d just like to state once more that this is pretty much the ground floor of using ajax. There are better and more complicated ways of doing most of what I’ve done here, and there is no upper limit to the impressive things that you can achieve with the technology and a bit of creativity.