The load() method

As described in the previous chapter, there are many ways to use AJAX with jQuery, and they should of course be used depending on the situation. One of the simplest and yet still powerful methods for loading data asynchronously is the load() method. You use it by selecting an element where you want the content loaded to and then call the load() method on it. It takes the URL that you wish to load, as a parameter. For this example, we need a an external file that we can load. We'll call it content.html and the content of it should look something like this:

<div id="divContent">
	<b>This is external content</b>
</div>
And there's more of it

Save it as content.html, in the same directory where you keep your other example files for this tutorial. We can load it as simple as this:

<div id="divTestArea1"></div>
<script type="text/javascript">
$(function()
{
	$("#divTestArea1").load("content.html");
});
</script>

If you have the content file in another directory, or if you have named it differently, you will have to change the parameter for the load method accordingly. This is all it takes to load content from an external file with jQuery and the load method. A pretty cool trick is that you can actually pass a selector along with the URL, to only get a part of the page. In the first example, we loaded the entire file, but in the following example, we will only use the div, which contains the first sentence:

<div id="divTestArea2"></div>
<script type="text/javascript">
$(function()
{
	$("#divTestArea2").load("content.html #divContent");
});
</script>

As you can see, we simply append a standard jQuery selector to the parameter, after the URL, separated with a space. This causes jQuery to select the content out and only pass the matched part(s) back to the container. You can use any jQuery selector type to pull off this trick, which makes it pretty powerful.

The load method can take two extra parameters: A set of querystring key/value pairs, and a callback function which will be executed when the load method finishes, no matter if it succeeds or fails. Here is an example where we use the callback function to inform about the result. Normally, you would likely only show a message if the method fails, but to illustrate how it works, we do it if the method fails as well. I make sure that it fails for the example, by requesting a file which doesn't exist:

<div id="divTestArea3"></div>
<script type="text/javascript">
$(function()
{
	$("#divTestArea3").load("no-content.html", function(responseText, statusText, xhr)
	{
		if(statusText == "success")
			alert("Successfully loaded the content!");
		if(statusText == "error")
			alert("An error occurred: " + xhr.status + " - " + xhr.statusText);
	});
});
</script>

As you can see, the callback function specifies 3 parameters, which jQuery will fill in for you. The first parameter will contain the resulting content if the call succeeds. The second parameter is a string which specifies the status of the call, e.g. "success" or "error". You can use it to see if the call was successful or not. The third parameter is the XMLHttpRequest object used to perform the AJAX call. It will contain properties which you can use to see what went wrong and many other things.