YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Browser History Manager

YUI 2: Browser History Manager

Client-side changes to a web page's content and structure are not recorded by the browser's history engine. As a consequence, the navigation buttons (back/forward) we've learned to use as we traverse the World Wide Web of documents don't usually serve us well when we begin exploring the World Wide Web of applications. Bookmarking, too, is problematic in web applications, as the application can change state hundreds of times through the course of a session without any change to the original document's URL. These are significant problems in the current paradigm of web application development.

The YUI Browser History Manager is a utility designed to facilitate the creation of web applications in which the navigation buttons are fully functional and in which broad aspects of an application's state — what panels are open, what tabs are active, etc. — can be bookmarked.

Note: Opera is not supported by the Browser History Manager at this time. Please refer to the Known Limitations section for more information.

Getting Started

To use the Browser History Manager, include the following source files in your web page: 

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
  3. <script src="http://yui.yahooapis.com/2.9.0/build/event/event-min.js"></script>
  4.  
  5. <!-- Browser History Manager source file -->
  6. <script src="http://yui.yahooapis.com/2.9.0/build/history/history-min.js"></script>
  7.  
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/event/event-min.js"></script>
 
<!-- Browser History Manager source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/history/history-min.js"></script>
 

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is history. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Using the Browser History Manager

This section describes the most common use of the Browser History Manager. It contains the following subsections:

Required markup

The Browser History Manager requires the following in-page markup: 

  1. <iframe id="yui-history-iframe" src="path-to-existing-asset"></iframe>
  2. <input id="yui-history-field" type="hidden">
  3.  
<iframe id="yui-history-iframe" src="path-to-existing-asset"></iframe>
<input id="yui-history-field" type="hidden">
 

Notes:

  1. The IFrame is only used to support Internet Explorer. If the markup is dynamically generated on the server (as a result of running a PHP script for example), you may want to create the IFrame only for Internet Explorer (use server side user agent sniffing)
  2. The asset loaded in the IFrame must be retrieved from the same domain as your page (use a relative path for the src attribute to make sure of that)
  3. The asset loaded in the IFrame does not have to be an HTML document. It can be an image for example. This trick is useful to avoid an additional server round-trip, which would degrade the performance of your site.
  4. This markup should appear right after the opening <body> tag.

Don't forget to hide the IFrame using the following CSS code:

  1. #yui-history-iframe {
  2.   position: absolute;
  3.   top: 0;
  4.   left: 0;
  5.   width: 1px;
  6.   height: 1px;
  7.   visibility: hidden;
  8. }
  9.  
#yui-history-iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 1px;
  height: 1px;
  visibility: hidden;
}
 

Module registration

A user interface module is simply a visible item on your page with which the user can interact. As such, modules are not immutable and their state is subject to change over time. If you wish to record the history of states visited by a specific module during a single browser session, to allow the user to navigate through that history using the browser's back/forward button, and to bookmark the page with your module in a specific state, you must first register it with the Browser History Manager.

In order to register a module, simply call the YAHOO.util.History.register method, passing in the module identifier (a non-empty string that uniquely identifies your module), the initial state of your module (i.e. the state of your module corresponding to the earliest history entry within the current browser session) as a string, and a callback function that will be invoked by the Browser History Manager every time your module changes state (so you can update the UI of your module accordingly).

Getting the initial state of the module is the trickiest part of this process. Indeed, the user might have previously visited your page and bookmarked it with your module in a specific state. If the user later on goes to your page using the same bookmark, you will likely wish to restore your module in the same state it was in when the page was bookmarked. To retrieve this "bookmarked state", simply call YAHOO.util.History.getBookmarkedState, passing in your module identifier: 

  1. var myModuleBookmarkedState = YAHOO.util.History.getBookmarkedState("myModule");
  2.  
var myModuleBookmarkedState = YAHOO.util.History.getBookmarkedState("myModule");
 

Of course, you also need a "default state" for your module in case the user accessed the page without using a bookmark. Having determined whether there is a bookmarked state in the code example above (getBookmarkedState will have returned null if there was no bookmarked state), the initial state of your module can be assigned as follows: 

  1. // If there is no bookmarked state, assign the default state:
  2. var myModuleInitialState = myModuleBookmarkedState || "myModuleDefaultState";
  3.  
// If there is no bookmarked state, assign the default state:
var myModuleInitialState = myModuleBookmarkedState || "myModuleDefaultState";
 

The next step in configuring your module to use the YUI Browser History Manager is to define your module's onStateChange callback. This callback will be called every time the Browser History Manager has detected that the state of your module has changed (which may happen when the user triggers the browser's back/forward button, for example). 

  1. function myModuleStateChangeHandler (state) {
  2.     // Update the UI of your module according to the "state" parameter
  3.     //...
  4. }
  5.  
function myModuleStateChangeHandler (state) {
    // Update the UI of your module according to the "state" parameter
    //...
}
 

Finally, complete your module registration by calling YAHOO.util.History.register: 

  1. YAHOO.util.History.register("myModule", myModuleInitialState, myModuleStateChangeHandler);
  2.  
YAHOO.util.History.register("myModule", myModuleInitialState, myModuleStateChangeHandler);
 

Note: You may register as many modules as you want, but you must register at least one module before initializing the Browser History Manager. Modules cannot be registered once the Browser History Manager has been initialized.

Using the onReady method

The Browser History Manager will initialize itself asynchronously and some of its methods cannot be called until it is fully initialized. You may want to know when this event occurs. In order to do that, you could subscribe to the Browser History Manager's onLoad event. However, using this approach, and if the subscription happens after the Browser History Manager has been initialized, the event never fires. Therefore, it is recommended to use the onReady method instead.

One common task you'll find yourself executing in your Browser History Manager onReady callback is retrieving the current state of your module and updating its UI accordingly. Why would the current state of your module be different from its initial state? Remember that the "initial" state of your module corresponds to the earliest history entry. The Browser History Manager onLoad event will be fired every time the user visits the page. If the user comes back to the page using the browser's back button, the state of your module will correspond to the latest history entry — that is the last state of your module before the user left the page. You can retrieve the current state of your module using YAHOO.util.History.getCurrentState, passing in your module identifier: 

  1. YAHOO.util.History.onReady(function () {
  2.     //...
  3.     var myModuleCurrentState = YAHOO.util.History.getCurrentState("myModule");
  4.     // Update the UI of your module according to "myModuleCurrentState"
  5.     //...
  6. });
  7.  
YAHOO.util.History.onReady(function () {
    //...
    var myModuleCurrentState = YAHOO.util.History.getCurrentState("myModule");
    // Update the UI of your module according to "myModuleCurrentState"
    //...
});
 

Initializing the Browser History Manager

The last step is to initialize the Browser History Manager, passing in a reference — or the id — of the required HTML elements previously created: 

  1. YAHOO.util.History.initialize("yui-history-field", "yui-history-iframe");
  2.  
YAHOO.util.History.initialize("yui-history-field", "yui-history-iframe");
 

Note: An exception may be thrown when initializing the Browser History Manager if the browser is not officially supported. Therefore, you may want to wrap this call within a try...catch block.

Storing New History Entries

Call YAHOO.util.History.navigate to store a new state in the browser history, passing in the identifier of the module which state has changed, and a string representing the new state of the specified module: 

  1. YAHOO.util.History.navigate("myModule", "myModuleNewState");
  2.  
YAHOO.util.History.navigate("myModule", "myModuleNewState");
 

The corresponding module onStateChange callback, specified at the time of the module registration, will then be called asynchronously (up to 50 msec later), giving you the opportunity to update the UI of your module. Note: The same callback will be called when the state of your module has changed after the user triggered the browser's back/forward button. There is no way to discriminate between these two situations.

Application State Management

The Browser History Manager only provides a way of storing/retrieving the history of states visited by an application. It is up to the implementer to name and handle each state appropriately.

Known Limitations

  • The Browser History Manager uses the URL fragment identifier to store the history. This means that there is a limit to how long the name of a state can be. Indeed, each browser has a built-in limit to how long a URL can be and this limit is browser dependent. For example, on Internet Explorer, this limit is 2083 characters. Also, keep in mind that this limit applies to the entire URL, not just the fragment identifier.
  • A string is a one-dimensional way of saving state information. It is possible to save multi-dimension state information (such as the collapsed/expanded state of each node of a treeview) into a one-dimensional string. However, the maximum length of a state identifier limits this to comparatively simple cases.
  • Web browsers never send the URL fragment identifier to the server. This means that some client-side processing is required in order to handle bookmarks. It is important to keep this amount of processing to a minimum in order not to degrade user experience. However, if an additional HTTP request at startup is not an issue, it is possible to send the URL fragment identifier back to the server and have the server do some processing instead (such as generating the appropriate markup).
  • All browsers will forget part or all of the history if the page gets forcibly refreshed. This will happen on Internet Explorer by pressing F5 (sometimes several times repeatedly), and on Firefox by pressing Ctrl+F5 or Shift-Ctrl-R.
  • On Internet Explorer, the title of the documents added to the history, listed in the browser's history drop down menu, is not correct. Instead of showing the title of each document, it shows part of the URL of each page.
  • IE7's yellow 'Download File' bar doesn't preserve the hash fragment when reloading the page. This may cause the current history state to be lost. See ticket #2527731 for details.
  • Opera is not supported at this time. This is due to the fact that Opera does not update the location.hash property when using the back/forward buttons. We expect this regression to be corrected in a future version of the Opera web browser.
  • Safari 2.x seems to never stop loading a page that uses the Browser History Manager. This problem does not appear with later versions of the Safari web browser.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Browser History Manager Cheat Sheet:

Cheat Sheet for the Browser History Manager.

Download full set of cheat sheets.

Browser History Manager Examples:

Other YUI Examples That Make Use of the Browser History Manager:

More Reading about the YUI Browser History Manager:

More Reading about History/Bookmark Management in DHTML Applications:

YUI Browser History Manager on del.icio.us:

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings