Hasher is a set of JavaScript functions to control browser history for rich-media websites and applications. It works as an abstraction of browsers native methods plus some extra helper methods, it also has the advantage of dispatching Events when the history state change across multiple browsers (since this feature isn't supported by all of them).
location.hash
may still be the recommended solution for saving application state.location.hash
can't be updated.changed
signal at each hasher.setHash()
)Include JS-Signals and hasher to your HTML file:
<script type="text/javascript" src="signals.js"></script>
<script type="text/javascript" src="hasher.js"></script>
IMPORTANT: signals.js
should be included before hasher.js
.
//handle hash changes
function handleChanges(newHash, oldHash){
console.log(newHash);
}
hasher.changed.add(handleChanges); //add hash change listener
hasher.initialized.add(handleChanges); //add initialized listener (to grab initial value in case it is already set)
hasher.init(); //initialize hasher (start listening for history changes)
hasher.setHash('foo'); //change hash value (generates new history record)
Google have a proposal for making Ajax content crawlable by specifying that a certain hash value also have an static snapshot. Those hash values should start with an exclamation mark !
:
hasher.prependHash = '!'; //default value is "/"
hasher.setHash('foo'); //will update location.hash to "#!foo" -> htttp://example.com/#!foo
PS: Only use the hashbang if you are generating static snapshots for the hash.
One of the greatest benefits of Hasher over other solutions is that it uses JS-Signals for the event dispatch, which provides many advanced features. This can be useful when you are setting the hash value and your changed
handler doesn't need to be called (e.g. updating hash value during scroll). Use it with care.
function setHashSilently(hash){
hasher.changed.active = false; //disable changed signal
hasher.setHash(hash); //set hash without dispatching changed signal
hasher.changed.active = true; //re-enable signal
}
hasher.init(); //start listening for changes
hasher.changed.add(console.log, console); //log all changes
hasher.setHash('foo');
setHashSilently('lorem/ipsum'); //set hash value without dispatching changed event (will generate history record anyway)
hasher.setHash('bar');
Hasher also contains the method replaceHash()
. It works very similarly to the
setHash()
method (will also dispatch a changed
signal), the main difference
it that it won't keep the previous hash on the history record (similar to
location.replace()
). It's useful for redirections and any other change that
shouldn't be on the browser history.
function onHasherInit(curHash){
if (curHash == '') {
// redirect to "home" hash without keeping the empty hash on the history
hasher.replaceHash('home');
}
}
hasher.initialized.add(onHasherInit);
hasher.changed.add(console.log, console); // log all hashes
hasher.init();
Hasher is only focused on providing a reliable and clear API for setting hash values and listening to hash state change event. If you need an advanced routing system check crossroads.js. Both were designed to work together easily:
//setup crossroads
crossroads.addRoute('home');
crossroads.addRoute('lorem');
crossroads.addRoute('lorem/ipsum');
crossroads.routed.add(console.log, console); //log all routes
//setup hasher
function parseHash(newHash, oldHash){
crossroads.parse(newHash);
}
hasher.initialized.add(parseHash); // parse initial hash
hasher.changed.add(parseHash); //parse hash changes
hasher.init(); //start listening for history change
Hasher will listen for the browser onhashchange
event if it is supported (FF3.6+, IE8+, Chrome 5+, Safari 5+, Opera 10.6+)
or it will fallback to pooling the window.location
on an interval to check if
hash value changed. On IE 6-7 it also uses an hidden iframe to trigger
the history state changes (since updating the hash value won't do the trick).
This is the same method used by most of the other available solutions like swfaddress,
jQuery Address, YUI History, jqBBQ, Really Simple History, etc...
The main difference from the other solutions are the API, code structure and the fact that it doesn't require jQuery/YUI/dojo/moootools/etc to work. It also uses JS-Signals for the events which provides a sane way of handling events and some really useful advanced features.
Besides the fact of making history state work across multiple browsers it also normalizes and fixes many bugs, here are a few of the advantges:
location.hash
contains a "?" character and file is beinglocation.hash
to a value that containlocation.hash
isn't available, willchanged
signal at each hasher.setHash()
and applicationDocumentation can be found inside the dist/docs
folder or at http://millermedeiros.github.com/Hasher/docs/.
Hasher is usually tested on IE (6,7,8,9), FF (3.6, 4.0, 5.0+ - mac/pc), Chrome (latest stable - mac/pc), Safari Mac (4.3, 5.0) and Opera (latest - mac/pc).
You can also run the test by yourself at http://millermedeiros.github.com/Hasher/test/unit.html
dev -> development files
|- build -> files used on the build process
|- lib -> 3rd-party libraries
|- src -> source files
|- tests -> unit tests
dist -> distribution files
|- docs -> documentation
|- js -> javascript files
master -> always contain code from the latest stable version
release-** -> code canditate for the next stable version (alpha/beta)
dev -> main development branch (nightly)
gh-pages -> project page
**other** -> features/hotfixes/experimental, probably non-stable code
Files inside dist/js
folder.
Documentation is inside the dist/docs
folder.
This project uses Apache Ant for the build process. If for some reason you need to build a custom version install Ant and run:
ant compile
This will delete all JS files inside the dist
folder, merge/update/compress source files and copy the output to the dist
folder.
ant deploy
This will delete all files inside dist folder, is runs ant compile
and generate documentation files.
IMPORTANT: dist
folder always contain the latest version, regular users should not need to run build task.
Released under the MIT license.
changed
signal even if it can't update the browser location.hash
, so