Introduction to HistoryManager

What is HistoryManager?

HistoryManager is actually made out of 2 classes:

HashListener - a class that supplies a cross-browser hashchange event listener.
HistoryManager - a class that supplies an Event-Based mechanism to manage the state of an application, using the browser's history (back/forward buttons, favorites etc).

HashListener

The browser hash is the part of a URL that comes after the # sign. There are 2 important attributes to the browser hash:

Changes to that part don't make the browser navigate out of the page.
Most browsers today supply back / forward functionality to hash changes.

This means that the hash is the perfect place for us to keep our app's state - changing it won't break our code, and some browsers will even support back/forward for us. On top of that - modern browsers (all but IE<8) supply a neat new event called onhashchange, which - as it's name implies - will fire whenever the hash is changed.

What this simple class does is to take the best from all browsers, and provide a cross-browser functionality that will work for all widely used browsers - IE6-8, Safari, Chrome, Firefox adn Opera.

HistoryManager

HistoryManager is a class that extends HashListener (the mootools way), to supply a very nice event based system to monitor the state of our application.

Use Case

Lets take this box for example:

I'm a box!

and these action:

click on the links to change the box's colors. use the back/forward button to navigate the state

What happened?

What we did is to keep the state of our box with HistoryManager.

First - Lets init our class:

var HM = new HistoryManager({blank_page:'http://blog.arieh.co.il/files/blank.html'});

Note the blank page - this is important for support for IE, as this is the key for it's back-forward funcs.

now - lets attach the link events:

$('color-blue').addEvent('click',function(){HM.set('color','blue')});
$('color-green').addEvent('click',function(){HM.set('color','green')});
$('color-red').addEvent('click',function(){HM.set('color','red')});

lastly - and this is the key - let's add some functionality to the box:

HM.addEvent('color-changed',function(value){$('ex-box').setStyle('background',value);});
HM.addEvent('color-removed',function(){$('ex-box').setStyle('background','none');});

//and let's fire it up:
HM.start();

note that whenever you press an anchor, the hash is changed. simple. clean. effective.

Event Magic

What happens on the back is that the class holds a list of keys set by the user. In this case, the only key that was set was color, but we can set as many as we like. this is extremely useful when you have many moving parts in your app - each class can be passed a unique key to play with, thus keeping its state.

For each key, the class supplies 4 sate events. added, updated, changed and removed.

The changed will fire whenever the key's state is changed - whether added or updated. All 3 will pass the new vaule to the callback function. The removed will pass the last value before removal.

1st - this class is actually a combination of a few other classes -

When i started this, i tried to convert this class, made by digitarald for Moo 1.1. I
than a very nice dude called Dave De Vos supplied me with a very solid method for monitoring the hash, which was also much simpler than digitarald's work. The core of HashListener is based mostly on his code.

also, if all you are looking for is a onhashchange event, there is a very cool one here that supplies this as a native mootools event.

Arieh.co.il