I’m not sure how, but my jQuery application suddenly got very complicated. One minute I was adding cool onmouseover effects and then BANG I’m inserting new elements all over the place and I have to look into heavy compression just to get the thing to download this side of the apocalypse.

Browsing through my application is a breeze. All the links are rewired to AJAX requests with smooth transitions and lots of slideUp-and-downs. There’s one glaring hole that might just bring this happy user experience down quicker than a Lehman brother wearing Iron Boots.

Whenever my lovely users click ‘back’ on their browser they get taken back to the obscenity that is the non-standards-compliant flashing gif-ridden site they came from, not the last thing they were viewing on my site. And if he or she clicks ‘refresh’ the application state goes back to the original and my user has to navigate back to the page he or she was viewing all over again. What a knightmare.

The browser navigation controls – back, forwards and refresh – are a staple of any user’s experience. Of course, being a web developer you will recognise the lack of page refreshes and the changing of page elements and automatically look for site-specific navigation links on the page itself. However, your average user is going to get very confused, thinking their browser buttons are broken or worse – your website is broken.

And it’s not only the user that’s going to encounter problems. If a Google Spider can’t see pages with unique URLs it’s not going to index them. So all I’m going to get on a Google search is whatever is on the landing page, which is just header information and a footer – not very useful. If my user wants to bookmark a page for later, he or she is going to have to start again, before all the AJAX fun began. The list goes on. It’s like building a vast palace with turrets and different wings but neglecting to build any doors. Your guests are going to walk over the drawbridge and marvel at the splendour of your architecture, the complete set of Power Ranger themed bedrooms, yet have no idea how to get there.

Anyway, here’s how I solved it:

Step 1: jQuery history plugin

First of all, I downloaded the Mikage’s jQuery history plugin. This is a bit of code that allows me to write to my browser’s history using a hash key. This hash can be pretty much anything that can uniquely describe your application’s state. I chose to make it the same as the resource I was loading into the main part of my application. So the plugin would add ‘www.mysite.com/page1#page2′ to my browser history when I clicked on the ‘Page 2′ link. Once I’d saved the plugin to my computer, I put this line in my head section of page1.html.

<script src='http://www.mysite.com/js/jquery.history.js' type='text/javascript'></script>

Now that jQuery knows I want to use this plugin, I need to initialise before I can start using it. I put this line just below the previous line, also in the $(document.ready()) section.

$(document).ready(function() {

$.historyInit(ajaxRender, 'http://www.mysite.com/page1');
};

Right, now it’s ready to use.

Step 2: The click event

Thinking about it, the page state always changes directly after the user clicks on a link (as it would on any other site I guess). So each of these state changes is tied to an <a> element. Therefore, I’m going to use jQuery’s live() function to tie a function to each link element’s ‘click’ event. So every time a user clicks a link some code will get executed. I used the live() function instead of the more common click() event handler because live() ties all future instances of an element to the function instead of just the ones initially in the DOM. This means I can happily insert new ‘a’ elements knowing that they’ll still respond in the same way. Here’s the click event code (this should also go in the $(document).ready so that it’s ready when the page loads):

$('a.internal').live('click',function() {
var post_url = $(this).attr('href');
//alert(post_url);
$.historyLoad(post_url);
return false;
});

You can see that I’m binding this function to the click events for each ‘a.internal’ element. I’ve given each internal link this class so that I can differentiate between internal and external links. If all links were treated the same, I’d get google.com loading inside my homepage. I extract the ‘href’ part of the link so that I know where the link is pointing. This is then assigned to the variable ‘post_url’. Then I call the historyLoad() method. This tells the jQuery plugin I just set up to add a new page to the browser history. It does this by adding a hash key to the end of the url. For example www.mysite.com/page1 would become www.mysite.com/page1#page2 in the address bar, and my application would then go about rendering the page2 on my page to reflect the change. The ‘return false;’ line is important, as this stops the browser executing it’s normal event handling for the element. If I didn’t include this line, all would be lost, as the browser would merrily redirect us to page2.html (thinking it was a regular link) and page1 would be lost to the wind.

Step 3: Rendering the page

Once historyLoad() has done it’s job and added a page to the browser history, it will then follow a callback function that we defined earlier with historyInit(). The callback function renderPage() is going to run the AJAX request and insert the new data into my page. The code for this is as follows (this can go anywhere in your javascript code):

function ajaxRender(post_url) {
$('body').css('cursor','wait'); // changes the cursor to a wait symbol
if($.browser.msie) { // if the browser is Internet Explorer
// jquery's $.load() function does't work when hash include special characters like åäö.
post_url = encodeURIComponent(post_url); // removes special characters
}
if (post_url) { // checks that a URL is present
$.ajax({ // start the AJAX request
type: 'POST', // I'm sending it via POST, you can use GET if you're feeling dangerous
url: post_url, // the URL we are retrieving
data: null, // in this case we are not sending any data
success: function(data) { // execute the below if the AJAX goes according to plan
$('#page_content').html(data); // put the data retrieved from the AJAX request into the div container
$('body').css('cursor','default'); // put the cursor back to normal
},
error: function (XMLHttpRequest, textStatus, errorThrown) { // execute this if it all goes tits up
$('body').css('cursor','default');
alert(textStatus + errorThrown);
return false;
}
});
} else { // if there is no post_url, i.e. it's the home page
$('body').css('cursor','default'); // put the cursor back to normal
}
};

This function executes the AJAX request and puts the data it retrieves into the #page_content div.

Once you’ve got these three components in your code you should be OK.

Note: If you’re just loading stuff from a file and not sending data it would be a better idea to use jQuery’s load() method.

Feel free to comment if there’s a bit you don’t understand or are having trouble with.

Edit: I just discovered that this process is called ‘deep linking’. Sounds like a bit of a serious term, but it is much shorter than ‘the restoration of conventional page navigation to an AJAX application’. Had I known this before I wrote this post I probably would’ve looked into using the jQuery Address deep linking plugin instead. But my method worked fine for me . . .

Update: you can see the finished version of my map here.

So I want to make a big map of europe that hilights the different countries when you move your mouse over them. Initially I thought this would be really easy using a bit of CSS and :hover . . . . no dice. But to my surprise I found out that it’s possible to use an ordinary HTML image map to define some pretty complex shapes, and let’s face it, shapes don’t get much more complex than this.

OK, so it’s possible to create clickable areas in HTML using an image map, but how do I add rollover effects to this? CSS didn’t seem to work so my next port of call was the wonderful jQuery. I found a plugin call mapHilight that takes an HTML image map, and adds some javascript hilighting wizardry to it. You can see a really cool example using a map of the states, this is almost exactly what I want but for Europe. I’m going to try and record everything I do, in the hope that someone else might find this useful, so here goes.

Step 1: Your image

First of all, you need to prepare the source image. In this example I’m going to be using a map of europe (see below).

Step 2: HTML Image Maps

Now that I have my image ready, I need to work out how to get the computer to recognise the individual areas. For my map each country is separated from other bordering countries by a white line, your image might not be so defined, in which case you should probably open the image up in Photoshop or something and separate the sections to make it easier.

I did a bit of research on Google and came across something quite interesting. Built into HTML there are <map> and <shape> tags. These are used to define image maps like the one I’m trying to make. An example of an HTML image map is this:

Here you can see four areas within a map. In this example each area is set as shape=’polygon’. This is because these shapes are complex and can’t be defined in simpler terms. However, if your image map is not so complicated, you could try using shape=’rect’ or shape=’circle’.

• More information on Creating HTML Image Maps

OK, so I know that the shape of each country on my map can probably be defined as a list of points (like a join-the-dots puzzle). I’m not sure exactly what the numbers will mean, but I guess they’re just coordinates on a fictional grid slapped on top of my image.

Next question: How do I get these coordinates for my own image?

Step 3: Download Inkscape

Well after a bit more digging I found an App called Inkscape.

Download Inkscape (free)

I think you can probably use some other apps too, like Illistrator or something else, but I don’t have the kind of money to splash out on such overpriced tripe, so I’ll be using Inkscape.

Right, while that’s downloading I’ll explain why I think Inkscape will do the job. To be honest I don’t really know that much about inkscape. What I do know is that you can open up any image you like and trace the edges. You can then save the image again (in a different format) and this will contain this list of coordinates that I’m after. Hopefully.

Step 4: Path Detection in Inkscape

Once you've finished downloading Inkscape you'll need to open it up. Then select File>Open and select the image you are working on.

Now here’s where it gets a bit more complicated. Inkscape is very good at detecting edges, but I found it needed a helping hand to make sure it knew that all of these countries were separate blobs, and not just one big blob. The first time I tried edge detection I managed to get a big polygon, but it was so big that it took up most of mainland europe. What I’d recommend you do is do a bit of experimentation to see how well Inkscape finds the borders in your image.

To give it a go, click on your image (so that there are black resizing dots around it), then select Path>Trace Bitmap. In the box that pops up, you can either select ‘Edge Detection’ or ‘Color Quantization’. As far as I can tell, you should use the first if there are very definitive edges already in the image and the second if the areas you’re trying to separate are different colours. I first tried ‘Edge Detection’ and this wasn’t really working for me. So I went back to Photoshop and coloured all my countries in different colours, opened Inkscape back up and selected ‘Color Quantization’ and it worked much better. Once you’ve selected your choice click ‘Update’ to get a preview of what it will look like and then ‘OK’ to start the magic.

Now if it’s worked, you should see a black line around each of the areas in your image. Inkscape should turn your image into several different shapes all with a black outline. If this doesn’t happen, or you get shapes in the wrong places, you’ll have to undo the path detection and try again. Once you’re happy you can move onto the next step.

Step 5: HTML Polygonization

In Inkscape, save the image as a .svg file. This is the format we’re going to use to extract the path information for our HTML polygon shapes. Open up your SVG file in your favourite text editor and scroll down until you find a list of numbers a bit like this one:

d=”M 662.5,1204 C 634.39954,1200.1136 558.02119,1154.3401 .. . .. .

Believe it or not, this is your image map. Unfortunately this data is in a format that isn’t very useful to us. Not only are the shape coordinates shrouded in a mysterious M and C characters, but they are also using lots of decimal places which HTML can’t understand. To sort this jumble of nonsense I decided to write a bit of Javascript. I call this my Polygonator. Go there and enter in the numbers and text within the “s just after d=”. So your bit of text will start M 662 . . .etc and should end with a single z. Then click ‘Process’ and you should be given some HTML code. Hooray!

A word of warning: depending on how acurate you want your area to be you may need to simplify your path a bit. If your SVG files contains millions of coordinates and you want something much simpler, then you can open it back up in Inkscape and select Path>Simplify. Then repeat this step.

Step 6: Add Your Image Area

Copy all of this HTML and paste it between the <map> </map> tags in your webpage. You should now have something that looks a bit like:

If you have more than one line in your SVG file starting with d=” then you’ll need to process each of these and convert them one at a time. Just repeat steps 5 and 6 for each of them and you should be OK.

Step 7: jQuery and mapHilight

Now we need to tie up the loose ends and get to the jQuery bit. If you haven’t already included jQuery at the top of your page then put this in your <head> section:

< ?= javascript_include_tag('jquery-1.3.2.min.js'); ?>

Now we need to add the MapHilight jQuery plugin. I don’t really understand what this plugin does, but it seemed to do wonders for my map, so you should give it a go too.  Download the mapHilight plugin and then include it just after you included jQuery.

< ?= javascript_include_tag('jquery.maphilight.min.js'); ?>

The second bit of script just initiates the plugin. It looks for an image with class=’map’, so if you’re using the same code make sure your image has this class. For example:

You’ll see my image also has usemap=”#testMap”. This is the bit that links the image to the <map>. So make sure you include the name of your map in this bit.

Good Work Team

Finished! Now when you look at your page you should see that different sections of your map light up when you move your mouse over them. Let me know if you have any problems and I’ll do my best to suggest something.

Simple code to grab the dimensions of any image on your page. Here’s an example:

Tell JQuery to find out how big this image is by using:

var width = $("#my_image").width();
var height = $("#my_image").height();