Back Button

Dynamic web applications that use things like XMLHTTPRequest and DOM updates instead of page refreshes do not update the browser history, and they do not change the URL of the page. That means if the user clicks the Back button, they will likely jump all the way out of the web application, losing any state that they were in. It is also hard to allow a user to bookmark the web application at a certain state.

Dojo's dojo.back module introduces browser history so that it is possible for the user to click Back and Forward without leaving the web application, and the developer can get notification of these Back and Forward events and update the web application appropriately. Browser history is generated by using a hidden IFRAME and/or adding a unique value to the fragment identifier portion of the page URL. The fragment identifier is the #value thing in a URL. For example:

http://some.domain.com/my/path/to/page.html#fragmentIdentifier

Since changing the fragment identifier does not cause the page to refresh, it is ideal for maintaining the state of the application. The developer can specify a more meaningful value for the fragment identifier to allow bookmarking.

dojo.back allows setting a state object that represents the state of the page. This state object will get callbacks when the Back or Forward button is pressed.

Adding to Your Page

To use dojo.back:

  • Define preventBackButtonFix: false in your djConfig like this:. /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}
    <script type="text/javascript"  src="../dojo.js"
        djConfig="preventBackButtonFix: false">
    </script>
    This allows the hidden iframe to be added to the current page via a document.write(). If you do not do this, dojo.back will not work correctly.
  • Add the appropriate require statement: 
    dojo.require("dojo.back");

Register the initial state of the page by calling:

dojo.back.setInitialState(state);

This state object will be called when the user clicks Back all the way back to the start of the web application. If the user clicks Back once more, they will go back in the browser to wherever they were before loading the web application.

The state object should have the following functions defined:

  • For receiving Back notifications: back(), backButton() or handle(type), where type will either be the string "back" or "forward".
  • For receiving Forward notifications: forward(), forwardButton() or handle(type), where type will either be the string "back" or "forward".

Example of the a very simple state object:

var state = {
	back: function() { alert("Back was clicked!"); },
	forward: function() { alert("Forward was clicked!"); }
};

To register a state object that represents the result of a user action, use the following call:

dojo.back.addToHistory(state);

To change the URL in the browser's location bar, include a changeUrl property on the state object. If this property is set to true, dojo.back will generate a unique value for the fragment identifier. If it is set to any other value (except undefined, null, 0 or empty string), then that value will be used as the fragment identifier. This will allow users to bookmark the page.

Browser Compatability

  • Do not mix dojo.back.addToHistory() calls that use changeUrl with ones that do not use changeUrl. Always use one or the other. If you are using changeUrl, you don't always have to provide a string for the value, but at least set it to true to get an auto-generated URL hash.
  • Don't test this page using local disk for MSIE. MSIE will not create a history list for iframe_history.html if served from a file: URL. The XML served back from the XHR tests will also not be properly created if served from local disk. Serve the test pages from a web server to test in that browser.
  • Safari 2.0.3+ (and probably 1.3.2+): Only the back button works OK (not the forward button), and only if changeUrl is NOT used. When changeUrl is used, Safari jumps all the way back to whatever page was shown before the page that uses dojo.undo.browser support.
  • Opera 8.5.3: Does not work.
  • Konqueror: Unknown. The latest may have Safari's behavior.

For complete examples, see the unit tests in /dojo/tests/back.html.