jBookmarker - create bookmarkable ajax apps

jBookmarker is a javascript library written by me, that allows you to save values in the window.location.hash string. This string represents the sequence of characters after the # sign in your URI. For example:

http://www.foo.com/bar.php#everything-happens-here

This script uses regular expressions to parse the window.location.hash string, in order to save, alter, delete or retrieve data, in the format

#key1=value1&key2=value2


…just like HTTP GET.

Both the key and the value are escaped using encodeURIComponent in order to prevent the script from breaking down when the “value” variable contains characters such as “&”, “#” or “=”.

The jBookmarker API

There’s only a handful of methods in this library:

• jBookmarker.set( key, value )

  Saves the «value» under the specified «key»;

• jBookmarker.get( key )

  Retrieves the value assigned to this key, it returns boolean false if the key does not exist;

• jBookmarker.remove( key )

  Removes this key along with its assigned value; It might act funny

• jBookmarker.addListener( pointer )

  Adds a function to be executed everytime the window.location.hash string changes; This feature is not tested, it’s still experimental :))

• jBookmarker.stopListener()

  Stops the listener; Again, “experimental”.

That’s about it. Not much, but it can prove quite useful. Just take a look at the following example:

A simple example

When you use AJAX to put some content on a page, also use jBookmarker to specify in the URI what information is being displayed. Like this:

/* dummy function that creates an ajax object */
xmlHttpRequest = createAjaxObject();
/* setting up the handler*/
xmlHttpRequest.onreadystatechange=function() {
if( xmlHttpRequest.readyState == 4 ) {
/* add the retrieved data to your DOM tree */
/* and save the current page */
jBookmarker.set( 'page', '1' );
}
}
xmlHttpRequest.open( "GET", "page_1.php", true );
xmlHttpRequest.send( null );

After the script is executed, your URI will look like:

http://www.example.com/foo.php#page=1


Thus, you have created a bookmarkable link. When the user returns to your site, all you have to do is use jBookmarker to find out what page he wants and display it to him. Like so:

window.onload = function() {
var page = jBookmarker.get( 'page' );
if ( page ) {
/* run the ajax script to display
the desired information */
}
}


Other uses

You can use this script to remember other changes the user made on your page. For instance, let’s pretend you have a div the user can display or hide. Like a news box or whatever. Wouldn’t be cool if the user closes the box and bookmarks the page, when he returns, to find the box as he has left it? A.k.a. closed?

With jBookmarker, this is pretty simple to achieve, just follow the example below. First the toggle function:

toggleDiv = function() {
var div = document.getElementById( 'foo' );
if ( div.style.display == 'block' ) {
div.style.display = 'none';
jBookmarker.set( 'state', 'hidden' );
}
else {
div.style.display = 'block';
jBookmarker.set( 'state', 'visible' );
}
}


…and the onload method…

window.onload = function() {
var state = jBookmarker.get( 'state' );
var div = document.getElementById( 'foo' );
if ( state == 'hidden' ) {
div.style.display = 'none';
}
else {
div.style.display = 'block';
}
}


This example can be downloaded as a gzip file here. Take it and test it in your browser, to see how it works. Any comments are welcomed.

Download, licence and warnings

You can download and use jBookmarker freely according to the terms of the MIT Licence. But note that this library was not fully tested, so it may have some (serious) flaws. Use it at your own risk, I can’t be held responsible if something goes wrong.

If you create a patch, please tell me about it. Thank you.