0.2.2 Compatibility

The behavior described in this document is different from the 0.2.2 Dojo release. In that release, it was not very easy to track the state that corresponded to a "page", but it was possible to register callbacks for Back and Forward through a dojo.io.bind() call. For 0.3 and later, the Back/Forward/Bookmarking support was moved to a new module, dojo.undo.browser. As a result of the changes, you may see slightly different behavior as compared with 0.2.2. The main difference is the need to call dojo.undo.browser.setInitialState(state) to set the state for the page as it is first loaded by the browser.

Theory

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.undo.browser module will introduce 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.undo.browser 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. In addition to registering state objects with dojo.undo.browser directly, the state object can be passed to dojo.io.bind() and it will be added to dojo.undo.browser for you.

Implementation

The following prerequisites are needed to use dojo.undo.browser:

• Define preventBackButtonFix: false in your djConfig. This allows the hidden iframe to be added to the current page via a document.write(). If you do not do this, dojo.undo.browser will not work correctly.
• Add the appropriate require statement: dojo.require("dojo.undo.browser");

Register the initial state of the page by calling:

dojo.undo.browser.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.undo.browser.addToHistory(state);

or, if you are using dojo.io.bind(), if the object contains the function back() or backButton() or the property changeUrl, then dojo.io.bind() will call dojo.undo.browser for you (only works with XMLHTTPTransport and ScriptSrcTransport).

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.undo.browser 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 Compatibility and Usage Notes

• Do not mix dojo.undo.browser.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.

Complete Example

There are test pages that shows how to use all of the pieces together:

http://archive.dojotoolkit.org/dojo-2007-05-15/ajax/tests/undo/test_brow...

http://archive.dojotoolkit.org/dojo-2007-05-15/ajax/tests/undo/test_brow...