Hashload JavaScript library (c) 2011 Ivan Kot, released under the MIT

The library allows to easily handle the hashchange event in multiple browsers, including IE7+, FF3.6+, Safari, Chrome 6+, Opera 10.6+. In a nutshell, the lib provides an API that may be used by a developer to assign callbacks to certain hash addresses by specifying a RegExp based rule for each of those. Additionally, the library is capable of performing AJAX calls for the corresponding (ajax-based) rules and passing received data to the associated callbacks. The library has no dependencies.

USAGE:

1. Download the source (either development or minified version)

2. Include the file into a page using the script tag:

3. After the inclusion Hashloads automatically registers itself within the window object and is accessible via the following calls:

   window.hashload window.Hashload window.hl

All of those are equivalent. 4. Once registered it is time to configure Hashload and setup rules for hash changes (see section below) 5. Finally, you need to call the init (or run) method to start Hashload

window.hashload.run()

CONFIGURATION: There are several options that may be configured:

1. Default handler - this is a function that will be called for all hash changes that are made while the page is opened, unless the skipDefaultHandler option is set to true (see below). To setup a custom default handler use:

   window.hashload.setDefaultHandler(function(event) {})

The callback receives the event object as the only argument. To reset the handler to its default value (a function that does nothing) use the following method:

window.hashload.resetDefaultHandler()

2. Skip default handler - it is possible to either skip the default handler once or disable it completely. In the first case, use:

   window.hashload.skipDefaultHandler()

In the other one:

window.hashload.setCallDefaultHeader(false)

3. Pre-dispatch callback - sometimes you may either need to alter parameters or process the input before an AJAX or simple-callback call is performed. For that purpose Hashload has the Pre-dispatch callback, in order to setup which you may need to call:

   window.hashload.setPreDispatchCallback(function(event) {})

This function receives the event object and has a unique opportunity to alter the params object that will then be passed to the AJAX call, to update the object simply put the new version to

event.params = {newParam: "newValue"}

IMPORTANT: make sure you return the event object in the Pre-dispatch callback or it will not work correctly other wise, so always include the following line

return event

into the callback. To reset the callback to its initial value call:

window.hashload.resetPreDispatchCallback()

RULES MANAGEMENT:

1. Adding a rule. In order to make Hashload work you may need to specify a set of rules, each based on a specific (RegExp) pattern that will be used to identify a hash change. There are two types of rules: AJAX-based rules; simple-callback-based rules.

AJAX-based rules mean that before a callback is executed an AJAX call needs to be performed, for that purpose Hashload has its own AjaxManager component or integrates with jQuery if it's available, i.e. if you don't need to handle that by yourself when creating you application. To add an AJAX-based call use:

window.hashload.addRule(/regexp pattern/i, callback, url, method, params)

method and params are optional, the defaults are: method: "get" params: {}

The callback function will receive the data as its only argument, so one may look like the following:

function(data) {console.log(data)}

Simple-callback-based rules are used when there is no need to make an AJAX call after a hash change or if a developer would like to execute it manually. To add a simple-callback rule you may need to call the same addRule method with the following parameters:

window.hashload.addRule(/regexp pattern/i, callback)

Please note that url in that case is NOT specified, that's how the library determines the type of a rule. The callback here will receive the event object as its only argument, so it may look like that:

function(event) {alert(event.hash)}

2. Removing a rule. Sometimes you may need to remove a previously created rule in the runtime, to do that you may use the following method:

   window.hashload.removeRule(/regexp pattern/i)

After that the library will remove all of the rules that match the pattern specified.

3. Replacing a rule, simple as it:

   window.hashload.replaceRule(pattern, callback, url, method, params)

This will replace all rules that match the pattern with a new one that has the same pattern but different parameters.

EVENT OBJECT: The event object that is used within the library and passed to the callbacks has several additional fields that contain some useful information, the list is:

hash - field that has the new hash stored in it;
params - the parameters object that may be altered in the Pre-dispatch 

callback.

AN EXAMPLE Below is a sample script that may be used to outline some of the basic features provided by the library:

<script type="text/javascript" src="js/hashload-1.1.0.min.js"></script>
<script type="text/javascript">
$(function(){
    window.hl.addRule(/photo\/cloud(\d)*$/i, function(data) {console.log(data)}, '/apc.php', 'get')
    window.hl.addRule(/test/i, function(event) {console.log(event.hash)})
    window.hl.run()
})
</script>

For additional information please see the sample folder.