jQuery.observeHashChange.js

Version 1.1 • 2010-01-25 • Gregor Schmidt Finn GmbH

Executive Summary

Want to get notified whenever the location.hash changes on your jQuery powered site. With the help of this plugin, reacting on this event becomes a piece-of-cake.


    jQuery(window).hashchange(function() {
      // location hash has been updated
      // ...
    });
        

... and your done — cross-browser, future-proof.

If you are already convinced, proceed to download.

Introduction

In the current JavaScript/DOM-Scripting world there is no built-in mechanism to observe changes to the document.location. In general, a change will imply a page reload so this is not a big deal, but when using anchors and in page link targets, a change in this location represents a browser history event, but your javascript application will not know.

Changes to the location.hash may be triggered, by clicking on page internal links, by setting the hash programmatically via JavaScript or by navigating within the browser's history. Especially the latter is hard to observe.

HTML 5 will most likely have a window.onhashchange method, IE8 already has it, FF 3.6 as well. The goal of this plugin is to provide a uniform, jQuery interface to register event handlers for this special event today.

Therefore two different implementation strategies are used. If the browser already supports, onhashchange, this event handling mechanism is used and a jQuery-like API is wrapped around it. If the browser does not support this functionality yet, a setInterval-based approach is used to simulate the desired behaviour.
So basically this plugin provides a future-proof, easy-to-use way, always using the most powerful technique available.

Usage

Simply include the jquery.observehashchange.js file into your jQuery powered site and you are ready to go. Each time, the document.location.hash is changed, a custom jQuery event is triggered. In order to get notifications, you should bind your custom event handlers to the window object:


    <script>
      jQuery(window).hashchange(function() {
        // location hash has been updated
        // ...
      });
    </script>
        

This site uses the plugin to show the current hash in the box on the right hand side. It works with the following piece of code:

        

Options

The event handler will receive additional information for your convenience. Namely it is an object containing the information about the actual change. The following code...

          

... might trigger the following output ...

  1. before change:
  2. after change (current value): #introduction
  3. before change: #introduction
  4. after change (current value): #download

Download

You may always find the current version of the jquery.observeHashChange.js-Plugin on GitHub Project Page.

Known Issues

If the browser does not natively support the window.onhashchange a workaround is used, to simulate the desired behavior. This workaround implies some disadvantages.

Computational Overhead

By constantly checking the current state, changes to the location.hash is detected. The polling interval is a compromise between computational overhead and accuracy. The default polling interval is 500 milliseconds. It may be adjusted to your specific needs by issuing the following code:


    <script>
      jQuery.observeHashChange({interval: 1000}); // seting the polling interval
                                                  // to 1 second.
    </script>
        

Lost events

When change events occur in a higher frequency than the polling interval, some change events may not be detected. This effect may be minimized, by reducing the polling interval while increasing the computational overhead. Please note, that the setInterval-based approach used in the plugin may never be as accurate as the built-in browser support.

License


    Copyright (c) 2009, Gregor Schmidt, Finn GmbH

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.