HashNav is a powerful AJAX-esque hash navigation (or "HashNav") class made in JavaScript. It is compatible with MooTools versions 1.3 and up.
Some of the nifty tools provided for developers include:
Be sure to read the full documentation to understand the full power of this class.
For a fun little HashNav sandbox to frolic around in, check out this GitHub page: http://xunnamius.github.com/HashNav
(playground is going to get a facelift soon, as well as a tutorial page)
Click here to jump to HashNav's method index.
If you're in a hurry and just need some decent hash navigation (or a little crash course in observer-oriented hash navigation), you could do something (verbose) like:
var hashNav = new HashNav(), observerName = 'helloworld', trigger = { page: true, params: {} }, callback = function(e){ console.log('event triggered:', e, arguments); }, arguments = [1, 2, 3, 4], bind = null, elementToScrollTo = 'scrollto'; hashNav.registerObserver(observerName, trigger, callback, arguments, bind, elementToScrollTo); hashNav.triggerEvent();
What this does is register an observer named helloworld with the hashNav object, which handles all the nitty-gritty details of hash navigation for you.
This observer will watch the URI hash and call the callback function
function(e){ console.log('event triggered:', e, arguments); }
with arguments [1, 2, 3, 4] bound to the default namespace (denoted by null) whenever it observes any legal hash URI page/state designator change that satisfies its trigger object. For example:
#!/home -- changing to --> #!/about #!/faq/entry/1 -- changing to --> #!/faq/entry/2
Now, the final line, hashNav.triggerEvent();, is equivalent to the gun shot at the horse races. It's the signal to go!
Note that, to save on http requests, one could consolidate the various module files shown below into one javascript file. This would probably be best for most people.
To use HashNav in its most conservative state, the HTML would look similar to the following:
<script type="text/javascript" src="mootools/mootools-core-1.4.5.js"></script> <script type="text/javascript" src="mootools/mootools-more-1.4.0.1.js"></script> <script type="text/javascript" src="HashNav/String.QueryStringImproved.js"></script> <script type="text/javascript" src="HashNav/Object.compare.js"></script> <script type="text/javascript" src="HashNav/HashNav.js"></script> <script type="text/javascript" src="myMainExternalScript.js"></script>
While a more holistic application of the HashNav library would require more or all of the modules to be imported after HashNav.js is included in your document. That would look a little something like this (with helpful newlines):
<script type="text/javascript" src="mootools/mootools-core-1.4.5.js"></script> <script type="text/javascript" src="mootools/mootools-more-1.4.0.1.js"></script> <script type="text/javascript" src="HashNav/String.QueryStringImproved.js"></script> <script type="text/javascript" src="HashNav/Object.compare.js"></script> <script type="text/javascript" src="HashNav/HashNav.js"></script> <script type="text/javascript" src="HashNav/more/parsers/parser.ampersand.js"></script> <script src="HashNav/HashNav.DOM.js" type="text/javascript"></script> <script src="HashNav/HashNav.Fx.js" type="text/javascript"></script> <script src="HashNav/HashNav.History.js" type="text/javascript"></script> <script src="HashNav/more/HashNav.serialize.js" type="text/javascript"></script> <script src="HashNav/more/HashNav.deserialize.js" type="text/javascript"></script> <script src="HashNav/more/HashNav.unserialize.js" type="text/javascript"></script> <script src="HashNav/more/HashNav.unregisterObservers.js" type="text/javascript"></script> <script src="HashNav/more/HashNav_T-QualifierLogic.js" type="text/javascript"></script> <script src="HashNav/more/HashNav_T-WildcardLogic.js" type="text/javascript"></script> <script type="text/javascript" src="myMainExternalScript.js"></script>
Note the general order. Scripts that come before the HashNav core (HashNav.js) should always come before, while scripts that come after should always come after.
Note that you can copy and paste all of the following examples into your browser's JS console in HashNav's sandbox. Don't forget to load the appropriate modules.
Loading data whenever the application's page/state designator changes:
hashNav.registerObserver( 'main', { page: true, params: {} }, function(){ load.ajax.data(); } );
Satisfying hash URI: #!/home2
Load different home pages based on a custom "type" parameter:
hashNav.registerObserver( 'home_loader', { page: true, /* The empty string in the params object roughly translates to "if the parameter is present with any value". Check out the documentation! */ params: { type:'' } }, function(){ load.a.custom.page(this.get('type')); } // You can use the event object that is passed to the function to achieve the same effect // function(e){ load.a.custom.page(e[1].pathParsed['type']); } );
Satisfying hash URI: #!/home3/type/5
Spawn a popunder box to warn a user not to leave the page or the data they typed will be lost. We'll be looking for the "composing" param to be present and orphaned, we're on the "emailer" page, and we'll pass their username in a "username" param. To top it all off, we want to see these parameters exclusively, meaning we only want to see what we listed in the params object and nothing else:
hashNav.registerObserver( 'warning', { page: 'emailer', params: { composing: true, username:'' }, qualifiers: { exclusive: true } }, function(){ warningPopup('Watch out '+ this.get('username')+ ', if you leave the '+ this.getCurrent()+ ' page before saving, everything you just typed will be lost!'); } // You can use the event object that is passed to the function to achieve a *similar* effect /* function(e){ warningPopup('Watch out '+ e[1].pathParsed['username']+ ', if you leave the ' + e[0] + ' page before saving, everything you just typed will be lost!'); }*/ );
Satisfying hash URI: #!/emailer/composing/username/Xunnamius
We want to store random data in both the key and value of a variable amount of parameters on the defaultHome page only:
hashNav.registerObserver( 'test', { page: '', params: { '*':'' } }, function(e){ store.that.data('Full Hash (test): ' + this.getStoredHashData()[0]); } // You can use the event object that is passed to the function to achieve the same effect // function(e){ store.that.data('Full Hash: ' + e[0]); } );
Satisfying hash URI: #!/home/var1/5/var2/6/var3/bcd/var4/var5/
Or we could do what we just did above, except add a limit to the amount of parameters:
hashNav.registerObserver( 'test', { page: '', params: { '*':'' }, qualifiers: { minparams: 3, maxparams: 10 } }, function(e){ store.that.data('Full Hash (test-limit): ' + e[0]); } );
Satisfying hash URI: #!/home/var1/5/var2/6/var3/zxy/var4/var5/
For some reason we want all the parameter values to be the same:
hashNav.registerObserver( 'helloworld', { page: 'somerandompage', params: { '*':'All params must equal this text!' } }, function(e){ store.that.data('Full Hash (helloworld): ' + this.getStoredHashData()[0]); } );
Satisfying hash URI: #!/somerandompage/var1/All params must equal this text!/var2/All params must equal this text!
How about a general trigger that observes every page change (even illegal ones) and doesn't use a params object at all (perhaps you want to filter params yourself using get()):
hashNav.registerObserver( 'foobartester', { page: false }, function(e){ console.log('Catch all:', e); } );
Satisfying hash URI: #!/foobartester/catch/all
For more information on how to use the observer/trigger system, read the documentation. Again, you may also be interested in a live demo of the whole class, available here: http://xunnamius.github.com/HashNav. Click here if you would like to view HashNav's method index.
var hashNav = new HashNav([options]);
Check the change log for more information on releases!
A note on comments here: These comments are moderated. No comments will show up until they are approved. Comments that are not productive (i.e. inflammatory, rude, etc) will not be approved.
Found a bug in this plugin? Please report it this repository's Github Issues.
blog comments powered by Disqus