One of my favorite new APIs in HTML5 is the History API. This API can be difficult to understand, and often it’s nearly impossible to tell that it’s being used. But when it’s used correctly, it makes websites a lot more usable.
What is the History API For?
The History API is an API to give you control over the browser history. In other words, you can add, delete, and change titles and URLs in the browser history field so that when your readers click the back button, they go to a URL that you have specified.
This may seem like a minor thing, but with more and more Ajax and other dynamic sites being built on the web, it comes in handy. For example, without the History API, the following scenario happens a lot:
- You visit a photo gallery website written dynamically.
- As you click through the images to view them, the only thing on the page that changes is the photo itself.
- Halfway through the gallery, you get called away, so you bookmark the page to return later and view the rest.
- When you return to the gallery, your bookmark takes you back to the beginning. You can’t bookmark the exact image you were on because it’s on the same page.
This type of photo gallery is very pleasant to view while you’re there, but trying to view it later is more difficult as the Ajax doesn’t remember where you were and so takes you back to the starting point.
The History API can help fix that. With the History API you can change the URI to reflect the exact photo. Then when the reader bookmarks the page, they are bookmarking it exactly where they are.
What Browsers Support the History API
The History API has spotty support from many modern browsers and mobile browsers.
- Android 2.2 and 2.3 support the History API, but versions 3 and 4 do not. There is no word on whether it will be put back in.
- Chrome has supported it fully since version 5.
- Firefox has supported History API since version 4.
- Internet Explorer is expected to get support in version 10.
- Opera added support in 11.5 and in 11.1 in Opera Mobile. Opera Mini does not support it yet.
- Safari 5.0 has buggy support on desktop browsers and iOS has buggy support in 4.2 and full support in 5.0.
This varied support will make some people want to avoid the History API. But there is a script you can use as a fallback even with browsers that don’t support it at all: history.js. With this project you can manipulate the browser history in nearly any browser.
How to Use the History API
The History API includes some of the JavaScript methods you can already use to manipulate the browser history.
history.back()—Step back one page in the history.history.forward()—Step forward one page in the history.history.go(number)—Move forward (positive numbers) or backward (negative numbers) in the history.history.go(0)is the current page.
There are also two new methods to control the history:
pushState(state object, title, url)—Changes the URI in the browser window.replaceState(state object, title, url)—Replaces the current URI in the history with a new one.
Finally there are three objects you can use to manipulate the history:
history.length—The number of entries in the history for this browser window.history.state—The current state object.window.onpopstate—This object is changed when the history changes.
In order to use these methods and objects, you need to first make sure that the History API is supported by the browser. You can then provide fallback options for older browsers that don’t support the History API. Check for the History API with the following script:
if (hasHistoryApi()) {
// scripts to update the history
} else {
// fallback scripts
}
function hasHistoryApi() {
return !!(window.history && history.pushStae);
}
Once you know the History API is supported, you can add a URL to the history or change the current URL using the pushState() and replaceState() methods.
You can then fix the photo gallery problem above by changing the URL when the photo changes. You use the pushState() method. There are three values for the pushState() method: state object, title, and URL. The state object is mostly ignored by browsers. Firefox stores the state object to disk in case the browser crashes to restore the state. The title is not used by any browsers. So, to change the URL, you should write:
history.pushState(null, null, "http://webdesign.about.com/");
Replace my URL (http://webdesign.about.com) with your own.
Use the replaceState() method in the same way.
The History API Does Not Create Web Pages
One tricky part of the History API is that it does not create new web pages. It just adds locations to the history list. In other words, if you added a URL into the history of the photo gallery application I describe above, then you also need to add scripting or HTML to display that page when a customer views the URL directly.
I usually do this with JavaScript. The main page has a URL like this:
http://www.webpage.com/index.html
And then to change the URL, I add a parameter to then end to reflect the photo:
http://www.webpage.com/index.html?photo=14
Then I just need to write a script that reads the parameter and updates the page with the photo that corresponds to that number.
You can see a working example of a photo gallery that uses History API in just this way, on the HTML5 in 24 Hours site. This site might look like any other photo gallery site with separate HTML pages. But the whole thing is created in one web page and the only things that change are the photo, the links, and the URL.
When the History API is Working, Your Customers Won’t Even Know
The reason I like the History API so much is that it’s a way of making your websites more usable, without your readers even knowing you’re doing anything. It’s not about being flashy or creating fancy animations. It’s about making websites that people can use without any problems.
Using the History API won’t get your website any special attention, but your readers would thank you if they knew you were using it.
