This tutorial is something of a followup to one that I wrote some time ago, describing the same basic process using the moo.ajax class, a precursor to mootools. That article still gets a fair number of visits on my site, but since moo.ajax has been deprecated it isn’t very useful. This tutorial expands on that one a little, but is essentially an update. By now everyone has heard of ajax, so there’s no need to repeat the introduction. Let’s get started.

What You’ll Need

• 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.
• A copy of the mootools library. I’ll show you how to get a customized version that meets all of our requirements.

Downloading mootools

Go to the mootools download page to grab the required files. The core component will already be selected. Find the Ajax component under the Remote section and select that. It will automatically select a handful of other components that mootools needs to run the Ajax component. I’ve also checked Window.DomReady, which selects the event component and will allow us to add Ajax to a form unobtrusively (that is, without making a mess of the HTML.) Click on Choose Compression to select the preferred level of compression for your customized mootools library, which you can then download. I chose no compression because I’m creating a tutorial. You can choose whatever suits you. For live sites I’d recommend using the JavaScript Packer compression to decrease file size (from 90KB to 20KB in this case.) I’ve included the uncompressed version along with the example files. You can develop with the uncompressed version and then switch in the packed version when you make the code live. You won’t have to change any of your code to take advantage of the reduced file size.

You can follow along with this tutorial by either viewing source on the example page or downloading the full source below.

• View the example
• Download the source

The Example

The example is a super-simple application that accepts two numbers. When you submit the form it will send the values to a PHP script via ajax, multiply them on the server, and return them to the page without refreshing. It will show this value in two places; mootools has the ability to update the contents of an element with your PHP script response or define a custom function to handle the returned data; I’ve chosen to show both. If javascript has been disabled it will simply print the return value out on an unstyled page. Not everyone is browsing with javascript enabled, so it’s important to ensure that they can still use your application without it. I could have done much more to make the non-javascript version nicer to use, but for now it performs its basic function and that’s a good start.

How it works

If you’ve looked at the source, you’ll see a pretty standard HTML page. It has a head section that includes a stylesheet, the mootools javascript file, and the application logic. It also has a body with a form in it. The application logic is the part where the cool stuff happens. Unlike my previous tutorial, I’ve taken advantage of some cool aspects of mootools to make this code clean and compact. I’ll explain these lines along the way.

window.addEvent('domready', function(){
	…
});

This block wraps around the rest of our code and tells the script to run once the DOM has loaded. That means it will run as soon as the document has been read into memory (but before all the images have loaded.) This avoids the delay you get with most javascript solutions. Inside this block, you’ll see another block:

$('testform').addEvent('submit', function(e){
	// stop the default form submit event
	new Event(e).stop();
	…
});

This tells the form “When the user submits testform, don’t perform your normal form action.” $('testform') tells mootools that you’re adding the code to an element with an id of testform (our simple form, as it happens.) Inside this block, we’re going to add instructions for what should happen instead.

var postString = "value1=" + $('value1').value + "&value2=" + $('value2').value;

Here we’re creating a string of data to post to the PHP script. This grabs the data from our form and creates a string like value1=5&value2=6. This step isn’t strictly necessary, but the values will be passed as an option to the ajax request next, and I wanted to keep that request looking pretty clean.

var myAjax = new Ajax('data.php', {
	method: 'post',
	data: postString,
	update: $('output1'),
	onComplete: function(req){
		$('output2').innerHTML = req;
		$('output2').style.background = "#adf";
	}
}).request();

This is the last bit of the script. It creates a new Ajax object called myAjax and sets the URL for the file you want to submit to, assigning some options to the request. The first is a like a form method. Just like any html form, you can submit the data using post and get. If you don’t specify anything, it defaults to post. Next we pass the request data as a string. Here, I’ve used the variable that we set earlier. Next, we use the update option to specify the id of an element. Mootools will automatically update the content of that element with whatever the PHP script sends back. Finally, the onComplete option allows you to specify a function to run when the ajax request is complete. Here I’ve told it to update another element with the same information and to highlight that element, just to show that it’s actually my function and not the update option at work. Now that we’re done setting up the new Ajax object, we call it’s request method to automatically make the request.

So that’s it. Your first steps into the world of ajax. I’ve included the whole script below so you can see how short it really is. In case you missed it above, you can view the example and download the full source.

<script type="text/javascript">
//<![CDATA[
// this is our javascript application logic

	// This happens once the DOM has loaded.
	window.addEvent('domready', function(){
		$('testform').addEvent('submit', function(e){
			// stop the default form submit event
			new Event(e).stop();

			// create a string of the variables we want to post to the php script
			// this will look like like "value1=5&value2=6"
			var postString = "value1=" + $('value1').value + "&value2=" + $('value2').value;

			// set some parameters for the ajax request...
			var myAjax = new Ajax('data.php', {
				method: 'post',
				data: postString,
				update: $('output1'),
				onComplete: function(req){
					$('output2').innerHTML = req;
					$('output2').style.background = "#adf";
				}
			}).request(); // ...and automatically make the ajax request
		});
	});
	//]]>
</script>

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.