Provide bookmark and history functionality with Really Simple History

The Really Simple History (RSH) framework allows you to provide features found in standard Web applications in your AJAX-enabled sites. A great feature of RSH is its simplicity, so it's easy to get it up and running in no time.

When you work with AJAX-based applications, you've probably noticed that you cannot bookmark pages within the application; this is due to its dynamic nature. This issue also introduces problems when users hit the Back button. One way to address the bookmarking and history navigation issues is with the Really Simple History (RSH) framework.

The need for RSH arose out of the inherent problems of dynamic Web sites and built-in browser navigation. Browsers were developed with multipage sites in mind and not the dynamic applications that use AJAX.

Problems occur when users navigate outside of an AJAX-enabled site. When the user returns to the site, the results will surprise them; that is, state will not be maintained between site visits.

To address this issue, an application needs a way to maintain state between page refreshes and wandering via browser navigation buttons. This allows the user to easily return to the site as well as bookmark it.

RSH was originally developed by Brad Neuberg in 2005 and now lives on the Google Code site. The latest version (0.6), which was released December 3, 2007, includes support for Internet Explorer 7, Safari, and Opera.

On the inside

One of the great features of RSH is that it is built entirely with standard JavaScript; there are no dependencies on other third-party libraries and such. RSH serializes application data in an internal JavaScript cache so that bookmarks and the Back button can be used to return your application to an earlier state.

The RSH framework consists of two JavaScript classes: dhtmlHistory and historyStorage. The dhtmlHistory class provides a history abstraction for AJAX applications. Pages are added to browser history using the current URL and an anchor hash. In addition, AJAX applications register themselves as history listeners. When a user navigates with the Back and Forward buttons, history events are fired that provide the browser's new location and any history data that previously persisted.

The historyStorage class allows you to store saved history data. The historyStorage class solves the problem of losing site data when a user leaves the site. The historyStorage class has methods for working with hash tables (remember that hashes were used to store browser history). This class allows you to store data when a user leaves a page. Data can be retrieved via the historyStorage class when the user returns to the site. This functionality takes advantage of a hidden form field as well.

Hashes are an important aspect of rsh. They are the portion of the URL at the end of the address prepended by the # symble. They are used to provide the browsing history feature provided by rsh.

Using RSH

Putting the RSH framework to use is a straightforward process. The first point is including the necessary files; the rs.js and json2007.js JavaScript files contain everything you need (or the compressed alternative). So, any page that uses the RSH framework must include references, as the following snippet demonstrates:

<script type="text/javascript" src=" RSH0.6FINAL/json2007.js"></script>
<script type="text/javascript" src="RSH0.6FINAL/rs.js" mce_src="RSH0.6FINAL/rs.js"></script>

The path to the files depends upon your installation. On my development machine, RSH is installed in the RSH0.6FINAL directory on the Web server. In addition to referencing the necessary script file, the blank.html file must be in the same directory as the script file as it is used with Internet Explorer.

To provide the history feature, the RSH framework creates a global object named dhtmlHistory. It is the entry point for manipulating the browser's history.

The first steps in working with the dhtmlHistory object is creating an instance and initializing it. The object is initialized in the page's onLoad event. You can accomplish initialization by calling the initialize method of the dhtmlHistory object. An event is added to the dhtmlHistory object to monitor any history activity.

The following code snippet provides a sample of how it is accomplished:

<script type="text/javascript">


var yourListener = function(newLocation, historyData) {

// listener code goes here


window.onload = function() {





Entries are added via the dhtmlHistory object's add method. For storage, the historyStorage object provides get and set methods to manipulate its contents. You can find more detailed information about the objects and how to put them to work at the RSH Web site.

Getting it

You can download RSH from the Google Code site. The download is contained within a single ZIP file. You can then decompress the files to a location on your Web server. The current version has the files in the RSH0.6FINAL folder.

The following list provides details on the more important files included in the download:

  • blank.html: This is needed for Internet Explorer's hidden iframe.
  • json2007.js: This is the default JSON parser shipped with RSH. It adds methods to Object.prototype, Function.prototype, Array.prototype, and other core JaveScript objects. A less intrusive version, json2005.js, is available as well.
  • rsh.js: The base JavaScript script file that provides RSH functionality.
  • rsh.compressed.js: A smaller version of rsh.js. It is suitable for production deployments by reducing the code footprint from 24K to 12K.
  • rshTestPage.html: A test page to demonstrate RSH is working.
  • rshTestPageTop100.opml: A test file for verifying RSH functionality.

There are also readme and license files in the download. The current version supports the following browsers: Internet Explorer 6/7 for Windows, all Gecko-based browsers since 2005 (Firefox/Mozilla/Netscape) for Mac/Windows/Linux, Opera 9.22-9.5 for Mac/Windows, and Safari 2.03/2.04/3.03 for Mac.

Add functionality

The RSH framework allows you to provide features found in standard Web applications in your AJAX-enabled sites. A great feature of RSH is its simplicity, so it's easy to get it up and running in no time.

Do you use RSH or any other frameworks? Have you run into problems with user expectations about AJAX-enabled applications? Share your experiences with the Web Developer community.

Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.

Check out the Web Development Zone archive, and catch up on the most recent editions of Tony Patton's column.


Get weekly development tips in your inbox Keep your developer skills sharp by signing up for TechRepublic's free Web Developer newsletter, delivered each Tuesday. Automatically subscribe today!


By Tony Patton

Tony Patton has worn many hats over his 15+ years in the IT industry while witnessing many technologies come and go. He currently focuses on .NET and Web Development while trying to grasp the many facets of supporting such technologies in a productio...