How to Modify the Browser History in Complex HTML5 and JavaScript Applications

Don’t you love snappy titles?! Consider a sophisticated application such as webmail client. In essence, it’s a complex JavaScript program running on a single HTML page. The user loads the URL and is presented with a list of emails. They click a title and the email content is retrieved using Ajax and displayed. They now want to return to the email list; what do they do?… …click the browser’s back button. Bang. The application closes and returns to the page they were viewing prior to accessing the application. Or, if it’s a new browser tab, the back button is disabled and can’t be clicked. So we have a problem. Our webmail client doesn’t support the one browser control most users understand. There are solutions. Some involve changing the hash mark (#name) in the URL so the state can be retained. It’s not perfect, but works in all browsers. Fortunately, the problem has been addressed with the HTML5 history.pushState and history.replaceState methods in conjunction with the window.onpopstate event. Try the history.pushState() demonstration page… The technique is refreshingly simple:

1. When the state changes, e.g. the user opens an email, history.pushState() is passed state information and executed. This enables the back button but — importantly — does not move the user from the page.
2. You can run history.pushState() as many times as necessary, or modify the current state using history.replaceState().
3. When the user clicks back (or forward), the window.onpopstate event is fired. A handler function can retrieve the associated state and display the appropriate screen.

The downside? Forget IE compatibility until v10 arrives. If you need to support IE9 and below, there are a number of shims including History.js and HTML5-History-API. Let’s write some code. Assume you’ve just displayed the result of an Ajax request:

// Ajax request
...
// display result
...

// modify history
history.pushState(obj, title, url);

Where:

• obj is any JavaScript object. You could use this to retain state information, e.g. { “view”: “EMAILCONTENT”, “item”: 123 };
• title is an optional title
• url is an optional URL. The URL can be anything — the browser won’t jump to that page, but could if the user reloaded the page or restarted their browser. In most cases, you’ll want to use parameters or a hash name, e.g. ?view=EMAILCONTENT&item=123; your application could analyze these values on start-up and return to the same place.

history.replaceState() has identical arguments and is only used if you want to replace the current state with a new one. You now need a handler function which runs when the window popstate event fires following the browser’s back or next button being clicked:

window.addEventListener("popstate", function(e) {

	// URL location
	var location = document.location;

	// state
	var state = e.state;
	
	// return to last state
	if (state.view == "EMAILCONTENT") {
		...
	}

});

The URL location can be determined with document.location (document.location.search and document.location.hash return the parameters and hash name respectively). The historic state object set by pushState() or replaceState() is obtained from the event object’s state property. You can use the information to display the appropriate screen. Try the history.pushState() demonstration page… Click the history.pushState button a few times then hit back to see what happens in the log. Very useful. Have you encountered back and next button issues in your web application?

Frequently Asked Questions (FAQs) about JavaScript History PushState