Managing the browser history for AJAX apps with dojo

AJAX web application (or any web app using client side scripting to modify the page) suffer from the "Back button problem": Users are used to hit the browser back button to return to a previous page, but there are no "pages" to go to in a AJAX app. Instead users will be taken to the page they visited before navigating to your web app - and probably lose all the state changes done in the app.

Fortunately there are some libraries out there that come to the rescue. I'll present a very simple example using dojo, which should get you started quickly.

For the example I chose a simple javascript app which converts inches into centimeters. For every new conversion there is a new entry stored in the browser history. Without history support the code looks like this:

<form>
 <input id="idInches" type="text"></input> inches
 <button onclick="onConvert(); return false;">Convert</button>
</form>
<div id="idOutput"></div>

<script language="javascript">
function onConvert()
{
  var input = document.getElementById('idInches').value;
  convert(input);
}

function convert(input)
{
  var cm = 2.54 * input;
  var msg = (input==null || input=="") ? 
    "" : (input + " inches = " + cm + " centimeters");
  document.getElementById("idOutput").innerHTML = msg;
}
</script>

Nothing unusual with that.
To enable the browser history we first add a function to restore a previous state. In our case we just restore the value of the input box and recalculate the result.

function restore(input)
{
  document.getElementById('idInches').value = input;
  convert(input);
}

Next we define a class which can store our state and restore it. It implements functions/properties that dojo will use:

function HistoryState(state)
{
    this.state = state;
    this.restoreState = function() { 
        restore(this.state); 
    };
    // back, forward and changeUrl are needed by dojo
    this.back = this.restoreState;
    this.forward = this.restoreState;
    this.changeUrl = true;
}

Then we add dojo and dojo.back, which includes the functionality for managing the browser history. First the dojo include (see details here):

<script type="text/javascript"  src="dojo.js"
    djConfig="preventBackButtonFix: false">
</script>

Load and initialize dojo.back:

dojo.require("dojo.back");
dojo.back.init();
dojo.back.setInitialState(new HistoryState(""));

The last line of this sets the state the page initially has. In our example the input text field is empty initially, so we just pass an empty string.

Now the only thing missing is to tell dojo when we reached a new state. We do this every time the convert button is pressed, so we add the following to onConvert:

dojo.back.addToHistory(new HistoryState(input));

That's it! See the example live here. Convert a few different values and then try the back/forward buttons of you browser.

Note: When trying yourself, always use a web server! Some things do not work when opening the file directly from the file system.

Note 2: You do not need all of dojo if you only want dojo.back. At the time of writing (dojo 1.3.2) only dojo.js, back.js and resources/iframe_history.html are needed.