MiracleBlue's Awesome Blog!

Photo by transCamOh, hello there!  I bet you thought you’d never see another blog post on here again, didn’t you?  Thought I had abandoned this blog for good?  Well, quite frankly, so did I for a little while.  The good news is, we were both wrong!

This is just a short example on the basic usage of the jQuery Address plugin by Asual, which provides AJAX applications with deep-linking and state/history management.  If you have ever come across this plugin and tried to figure it out, chances are you found the official documentation to be of little or no help.  You are not alone.  I had been wanting to integrate it into my personal website – for which I required deep linking and state management – for about a week.  Finally, yesterday, I became determined to figure out enough about how the plugin worked in order to get the functionality I needed out of it.

In my website, I wanted to use jQuery Address for deep-linking and history management, but I also wanted it to take advantage of HTML5′s new pushState method in browsers that support it, and only use location.hash as a fallback method for dynamically changing the displayed URL (jQuery Address supports both these methods).  The reason I want to avoid using hashed URLs for deep-linking when possible is because the only way to read any data contained in a hash segment is with Javascript.  This is because the hash segment of a URL is not visible to the server; only the browser can use it.  Therefore, having a hashed URL requires the user to have javascript enabled in order for the application to know what content the user is requesting.  I know some of you are probably asking why we should care about users who don’t enable javascript in their browsers, however that is not the point of this blog post.

What I wanted to achieve

I have a main navigation bar with a set of links which point to real URLs which I want to load dynamically via AJAX when clicked.  Since they are real URLs, they point to real content, and can be loaded directly without AJAX.  My server-side logic will return a full HTML page for normal requests, and JSON-encoded data containing only the dynamic content to be inserted into the page for AJAX requests.

Loading the plugin

In order to enable jQuery Address to use HTML5 pushState functionality, we need to set one of the plugin’s configuration parameters called “state”, which points to the base path of your website or application.  In this case, my base path is the webroot “/”.  You can set this and other configuration parameters in query-string format, like so:

<script type="text/javascript" src="jquery.address.js?state=/"></script>

The code that makes it happen

Here’s an edited snippet of the code that I wrote for my site that makes it all happen, explained step-by-step in the comments:

$(document).ready(function(){
	// Add jQuery Address functionality to the links in the navbar
	$("#nav a").address();
	// Our event responder that triggers whenever the address is changed (including on first load!)
	$.address.change(function(event) {
		// Set shortcut to URI value
		var uri = event.value;
		// Run ajax call and get JSON data
		$.getJSON(uri, function(data){
			// All parsing and processing of returned data should happen here
		});
	});
})

Voila!

You can see a live, working example of the code and how I have implemented it over on my main website.  Feel free to take a look at the full code, which is in the main.js file.

I hope this helps you to have a basic understanding of how to make this plugin Just Work™ so you can start using it.  As always, leave questions and feedback in the comments!