If you are getting errors like “parser error : EntityRef: expecting ‘;’” when trying to parse some XML using SimpleXML, it could be because your XML file or string contains an & character. Do the following to remedy the situation:

$correct_xml = str_replace('&','&',$problem_xml);

Down with the browser refresh

I’ve just finished a project I’ve been working on over the last couple of months that was a jQuery-based ajax application without page refreshes. I thought I’d take this opportunity to share some of the problems I encountered whilst they were still fresh in my mind.

If you’re thinking of making your own jQuery online app I’d recommend trying out the ‘no refresh’ method. Once you’ve got it working, you’ll wonder how you’ve managed to cope so long with all these page refreshes, and each time somebody else’s site forces your browser to refresh, you’ll throw up a bit in your mouth.

In my humble opinion, asynchronous data transfer is the future and soon it will be very unusual to have your page refresh every time you want to see new content. Browser refreshes are clunky, ugly are an unnecessary interruption to the user experience flow.

With jQuery and ajax ruling your content you can have:

• Complete control over the user experience. While your user is waiting for a page to load, you can display a fancy loading graphic, or even a small film clip, or some music, or whatever you like. It makes for a much smoother page transition, which should have it’s own bullet . .
• Smooth page transitions. Okay, this is part of the user experience too, but such an important part I thought it deserved a special mention. Instead of content loading, then appearing in drips and drabs as and when it finishes, you can display your loading graphic until the whole page is ready, and then use a pretty jQuery effect to display the new content. You can have the page slide in, gradually fade in or just appear, the point is the page is ready instantly, and the user is aware that they can now click on things and type.

“But what about all the disadvantages!?” I hear you cry. Well, yes, you’re right there are problems too, but I’m going to try and address these with solutions and workarounds I’ve been using.

Problem #1 – You click on a link and your browser takes you straight to the content, but refreshes the page in the process. Bad browser! Bad!

If you’re building an ajax app, this is a big nono. Especially since it’s most likely that that page will have no layout, and just be some JSON/XML data.

The solution is to use a jQuery event handler to intercept the link and make it do what you want, overriding the default behaviour.

Tip: For my application, I added classes to each link element such as a.internal and a.external to distinguish between the two. If you don’t do this, external links will be loaded in your application instead of in a new tab/page. You can also add separate behaviour for external links then, such as displaying a popup informing the user they are leaving your site.

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

This bit of jQuery should go in the $(document).ready section of your code. It intercepts all links clicked of which have the class ‘internal’, sends their ‘href’ attribute to the historyLoad function, and then returns false to prevent the link from opening a new page.

But that’s not the only problem you’re likely to encounter.

empty browser

Problem #2 – You scroll halfway down the page, click on a link and the content loads above the point your looking at.

If you’re displaying a lot of content, that requires vertical scrolling, you might find that when you click on a link to a page displayer less content, this content gets injected above the browser’s viewport. In other words, the new page is shorter than the old one and you need to scroll up to view it.

If you’ve never heard of ajax or jQuery before, you’re probably not going to realise that simply scrolling up will solve this one, so it’s good practice to cater for these people.

There is a simple solution to this. Add the following code to your ajax ‘success’ function – the function that gets called when your ajax call returns with some data.

$('html, body').animate({scrollTop:0}, 'fast');

This will take the user back to the top of the page before the new content is injected.

Start again from the beginning

Problem #3 – going straight to a page deep in your application’s navigation structure.

So, you want to load up a bookmark you have from an article you read on the site six months ago? But wait! It just takes you to the home page and you need to wade through the navigation to get back to this article.

Because the page isn’t refreshing, neither is your browser registering the fact that you’ve changed pages. There is a workaround for this involving adding a unique hash code to the url using a nice little jQuery plugin. Please read my tutorial on the subject for more details, or google ‘jQuery history plugin’.

No room for overtaking here

Problem #4 – Ajax requests jumping the queue

I didn’t encounter this problem for quite a while, but if you’ve got a page running without refreshes, chances are you’ll experience the same problem.

In jQuery, there’s no “request stack” or “request queue” for ajax. When you send off an ajax request, it comes back after the data you are rquesting has loaded, and only then.

Consider what might happen if you first click on a link for a page with 1000 images listed in one big row, and then get bored of waiting for this to load and click on a link for a single image. When you click on the second link (the one for the single image), it will not cancel the first request. So now you have two requests being processed by your server. Naturally, the single image is going to come back first. Great! That’s what we wanted. But as soon as the 1000 images have loaded, the ‘success’ function will get called and you’ll find your viewing experience unexpectantly interrupted.

To fix this you need to cancel any previous ajax requests before you initiate a new one. To do this, first declare a global variable to hold the details of any ajax requests your application will make:

var ajax_request = null;

This makes a variable that we can reference lateron to see if an ajax request is under way. Once we’ve got this we can create our ajax request:

if (ajax_request) { // checks for an existing ajax request
ajax_request.abort(); // aborts request
}
ajax_request = $.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
//alert("success!");

// you can now inject the ajax response into any element you like witht the 'data' variable

});
});
},
error: function (XMLHttpRequest, textStatus, errorThrown) { // execute this if it all goes tits up
alert(textStatus + errorThrown);
return false;
}
});

In this example, the ajax request will be sent regardless, but jQuery will cancel any previous requests, to avoid the requests overtaking eachother.

Tip: If you would like more complex queue behaviour it might be worth checking out the jQuery Ajax Queue plugin.

Do you think this is all bullshit? That the browser refresh is here to stay? Or have you encountered other problems when ajaxifying your own website?

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();