jQuery BBQ: Back Button & Query Library

Version: 1.3pre, Last updated: 8/26/2010

Project Homehttp://benalman.com/projects/jquery-bbq-plugin/
GitHubhttp://github.com/cowboy/jquery-bbq/
Sourcehttp://github.com/cowboy/jquery-bbq/raw/master/jquery.ba-bbq.js
(Minified)http://github.com/cowboy/jquery-bbq/raw/master/jquery.ba-bbq.min.js (2.2kb gzipped)
Summary
jQuery BBQ: Back Button & Query LibraryVersion: 1.3pre, Last updated: 8/26/2010
LicenseCopyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.
ExamplesThese working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.
Support and TestingInformation about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).
Release History
Param (to string)
Functions
jQuery.param.querystringRetrieve the query string from a URL or if no arguments are passed, the current window.location.href.
jQuery.param.querystring (build url)Merge a URL, with or without pre-existing query string params, plus any object, params string or URL containing query string params into a new URL.
jQuery.param.fragmentRetrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location.href.
jQuery.param.fragment (build url)Merge a URL, with or without pre-existing fragment (hash) params, plus any object, params string or URL containing fragment (hash) params into a new URL.
jQuery.param.sortedReturns a params string equivalent to that returned by the internal jQuery.param method, but sorted, which makes it suitable for use as a cache key.
jQuery.param.fragment.noEscapeSpecify characters that will be left unescaped when fragments are created or merged using jQuery.param.fragment, or when the fragment is modified using jQuery.bbq.pushState.
jQuery.param.fragment.ajaxCrawlableTODO: DESCRIBE
Deparam (from string)
Functions
jQuery.deparamDeserialize a params string into an object, optionally coercing numbers, booleans, null and undefined values; this method is the counterpart to the internal jQuery.param method.
jQuery.deparam.querystringParse the query string from a URL or the current window.location.href, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.
jQuery.deparam.fragmentParse the fragment (hash) from a URL or the current window.location.href, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.
Element manipulation
Functions
jQuery.elemUrlAttrGet the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.
jQuery.fn.querystringUpdate URL attribute in one or more elements, merging the current URL (with or without pre-existing query string params) plus any params object or string into a new URL, which is then set into that attribute.
jQuery.fn.fragmentUpdate URL attribute in one or more elements, merging the current URL (with or without pre-existing fragment/hash params) plus any params object or string into a new URL, which is then set into that attribute.
History, hashchange event
Functions
jQuery.bbq.pushStateAdds a ‘state’ into the browser history at the current position, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).
jQuery.bbq.getStateRetrieves the current ‘state’ from the browser history, parsing location.hash for a specific key or returning an object containing the entire state, optionally coercing numbers, booleans, null and undefined values.
jQuery.bbq.removeStateRemove one or more keys from the current browser history ‘state’, creating a new state, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).
Events
hashchange event (BBQ)In jQuery 1.4 and newer, the event object passed into any hashchange event callback is augmented with a copy of the location.hash fragment at the time the event was triggered as its event.fragment property.
Files
jQuery hashchange eventVersion: 1.3, Last updated: 7/21/2010
LicenseCopyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.
ExamplesThese working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.
Support and TestingInformation about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).
Known issuesWhile this jQuery hashchange event implementation is quite stable and robust, there are a few unfortunate browser bugs surrounding expected hashchange event-based behaviors, independent of any JavaScript window.onhashchange abstraction.
Release History
Functions
jQuery.fn.hashchangeBind a handler to the window.onhashchange event or trigger all bound window.onhashchange event handlers.
Properties
jQuery.fn.hashchange.delayThe numeric interval (in milliseconds) at which the hashchange event polling loop executes.
jQuery.fn.hashchange.domainIf you’re setting document.domain in your JavaScript, and you want hash history to work in IE6/7, not only must this property be set, but you must also set document.domain BEFORE jQuery is loaded into the page.
jQuery.fn.hashchange.srcIf, for some reason, you need to specify an Iframe src file (for example, when setting document.domain as in jQuery.fn.hashchange.domain), you can do so using this property.
Events
hashchange eventFired when location.hash changes.

License

Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.  http://benalman.com/about/license/

Support and Testing

Information about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).

jQuery Versions1.2.6, 1.3.2, 1.4.1, 1.4.2
Browsers TestedInternet Explorer 6-8, Firefox 2-4, Chrome 5-6, Safari 3.2-5, Opera 9.6-10.60, iPhone 3.1, Android 1.6-2.2, BlackBerry 4.6-5.
Unit Testshttp://benalman.com/code/projects/jquery-bbq/unit/

Release History

1.3pre(8/26/2010) Integrated jQuery hashchange event v1.3, which adds document.title and document.domain support in IE6/7, BlackBerry support, better Iframe hiding for accessibility reasons, and the new jQuery.fn.hashchange “shortcut” method.  Added the jQuery.param.sorted method which reduces the possibility of extraneous hashchange event triggering.  Added the jQuery.param.fragment.ajaxCrawlable method which can be used to enable Google “AJAX Crawlable mode.”
1.2.1(2/17/2010) Actually fixed the stale window.location Safari bug from jQuery hashchange event in BBQ, which was the main reason for the previous release!
1.2(2/16/2010) Integrated jQuery hashchange event v1.2, which fixes a Safari bug, the event can now be bound before DOM ready, and IE6/7 page should no longer scroll when the event is first bound.  Also added the jQuery.param.fragment.noEscape method, and reworked the hashchange event (BBQ) internal “add” method to be compatible with changes made to the jQuery 1.4.2 special events API.
1.1.1(1/22/2010) Integrated jQuery hashchange event v1.1, which fixes an obscure IE8 EmulateIE7 meta tag compatibility mode bug.
1.1(1/9/2010) Broke out the jQuery BBQ event.special hashchange event functionality into a separate plugin for users who want just the basic event & back button support, without all the extra awesomeness that BBQ provides.  This plugin will be included as part of jQuery BBQ, but also be available separately.  See jQuery hashchange event plugin for more information.  Also added the jQuery.bbq.removeState method and added additional jQuery.deparam examples.
1.0.3(12/2/2009) Fixed an issue in IE 6 where location.search and location.hash would report incorrectly if the hash contained the ? character.  Also jQuery.param.querystring and jQuery.param.fragment will no longer parse params out of a URL that doesn’t contain ? or #, respectively.
1.0.2(10/10/2009) Fixed an issue in IE 6/7 where the hidden IFRAME caused a “This page contains both secure and nonsecure items.” warning when used on an https:// page.
1.0.1(10/7/2009) Fixed an issue in IE 8.  Since both “IE7” and “IE8 Compatibility View” modes erroneously report that the browser supports the native window.onhashchange event, a slightly more robust test needed to be added.
1.0(10/2/2009) Initial release

Param (to string)

Summary
Functions
jQuery.param.querystringRetrieve the query string from a URL or if no arguments are passed, the current window.location.href.
jQuery.param.querystring (build url)Merge a URL, with or without pre-existing query string params, plus any object, params string or URL containing query string params into a new URL.
jQuery.param.fragmentRetrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location.href.
jQuery.param.fragment (build url)Merge a URL, with or without pre-existing fragment (hash) params, plus any object, params string or URL containing fragment (hash) params into a new URL.
jQuery.param.sortedReturns a params string equivalent to that returned by the internal jQuery.param method, but sorted, which makes it suitable for use as a cache key.
jQuery.param.fragment.noEscapeSpecify characters that will be left unescaped when fragments are created or merged using jQuery.param.fragment, or when the fragment is modified using jQuery.bbq.pushState.
jQuery.param.fragment.ajaxCrawlableTODO: DESCRIBE

Functions

jQuery.param.querystring

Retrieve the query string from a URL or if no arguments are passed, the current window.location.href.

Usage

jQuery.param.querystring( [ url ] );

Arguments

url(String) A URL containing query string params to be parsed.  If url is not passed, the current window.location.href is used.

Returns

(String) The parsed query string, with any leading “?” removed.

jQuery.param.querystring (build url)

Merge a URL, with or without pre-existing query string params, plus any object, params string or URL containing query string params into a new URL.

Usage

jQuery.param.querystring( url, params [, merge_mode ] );

Arguments

url(String) A valid URL for params to be merged into.  This URL may contain a query string and/or fragment (hash).
params(String) A params string or URL containing query string params to be merged into url.
params(Object) A params object to be merged into url.
merge_mode(Number) Merge behavior defaults to 0 if merge_mode is not specified, and is as-follows:
  • 0: params in the params argument will override any query string params in url.
  • 1: any query string params in url will override params in the params argument.
  • 2: params argument will completely replace any query string in url.

Returns

(String) A URL with a urlencoded query string in the format ‘?a=b&c=d&e=f’.

jQuery.param.fragment

Retrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location.href.

Usage

jQuery.param.fragment( [ url ] );

Arguments

url(String) A URL containing fragment (hash) params to be parsed.  If url is not passed, the current window.location.href is used.

Returns

(String) The parsed fragment (hash) string, with any leading “#” removed.

jQuery.param.fragment (build url)

Merge a URL, with or without pre-existing fragment (hash) params, plus any object, params string or URL containing fragment (hash) params into a new URL.

Usage

jQuery.param.fragment( url, params [, merge_mode ] );

Arguments

url(String) A valid URL for params to be merged into.  This URL may contain a query string and/or fragment (hash).
params(String) A params string or URL containing fragment (hash) params to be merged into url.
params(Object) A params object to be merged into url.
merge_mode(Number) Merge behavior defaults to 0 if merge_mode is not specified, and is as-follows:
  • 0: params in the params argument will override any fragment (hash) params in url.
  • 1: any fragment (hash) params in url will override params in the params argument.
  • 2: params argument will completely replace any query string in url.

Returns

(String) A URL with a urlencoded fragment (hash) in the format ‘#a=b&c=d&e=f’.

jQuery.param.sorted

Returns a params string equivalent to that returned by the internal jQuery.param method, but sorted, which makes it suitable for use as a cache key.

For example, in most browsers jQuery.param({z:1,a:2}) returns “z=1&a=2” and jQuery.param({a:2,z:1}) returns “a=2&z=1”.  Even though both the objects being serialized and the resulting params strings are equivalent, if these params strings were set into the location.hash fragment sequentially, the hashchange event would be triggered unnecessarily, since the strings are different (even though the data described by them is the same).  By sorting the params string, unecessary hashchange event triggering can be avoided.

Usage

jQuery.param.sorted( obj [, traditional ] );

Arguments

obj(Object) An object to be serialized.
traditional(Boolean) Params deep/shallow serialization mode.  See the documentation at http://api.jquery.com/jQuery.param/ for more detail.

Returns

(String) A sorted params string.

jQuery.param.fragment.noEscape

Specify characters that will be left unescaped when fragments are created or merged using jQuery.param.fragment, or when the fragment is modified using jQuery.bbq.pushState.  This option only applies to serialized data object fragments, and not set-as-string fragments.  Does not affect the query string.  Defaults to “,/” (comma, forward slash).

Note that this is considered a purely aesthetic option, and will help to create URLs that “look pretty” in the address bar or bookmarks, without affecting functionality in any way.  That being said, be careful to not unescape characters that are used as delimiters or serve a special purpose, such as the “#?&=+” (octothorpe, question mark, ampersand, equals, plus) characters.

Usage

jQuery.param.fragment.noEscape( [ chars ] );

Arguments

chars(String) The characters to not escape in the fragment.  If unspecified, defaults to empty string (escape all characters).

Returns

Nothing.

jQuery.param.fragment.ajaxCrawlable

TODO: DESCRIBE

Usage

jQuery.param.fragment.ajaxCrawlable( [ state ] );

Arguments

state(Boolean) TODO: DESCRIBE

Returns

(Boolean) The current ajaxCrawlable state.

Deparam (from string)

Summary
Functions
jQuery.deparamDeserialize a params string into an object, optionally coercing numbers, booleans, null and undefined values; this method is the counterpart to the internal jQuery.param method.
jQuery.deparam.querystringParse the query string from a URL or the current window.location.href, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.
jQuery.deparam.fragmentParse the fragment (hash) from a URL or the current window.location.href, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.

Functions

jQuery.deparam

Deserialize a params string into an object, optionally coercing numbers, booleans, null and undefined values; this method is the counterpart to the internal jQuery.param method.

Usage

jQuery.deparam( params [, coerce ] );

Arguments

params(String) A params string to be parsed.
coerce(Boolean) If true, coerces any numbers or true, false, null, and undefined to their actual value.  Defaults to false if omitted.

Returns

(Object) An object representing the deserialized params string.

jQuery.deparam.querystring

Parse the query string from a URL or the current window.location.href, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.

Usage

jQuery.deparam.querystring( [ url ] [, coerce ] );

Arguments

url(String) An optional params string or URL containing query string params to be parsed.  If url is omitted, the current window.location.href is used.
coerce(Boolean) If true, coerces any numbers or true, false, null, and undefined to their actual value.  Defaults to false if omitted.

Returns

(Object) An object representing the deserialized params string.

jQuery.deparam.fragment

Parse the fragment (hash) from a URL or the current window.location.href, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.

Usage

jQuery.deparam.fragment( [ url ] [, coerce ] );

Arguments

url(String) An optional params string or URL containing fragment (hash) params to be parsed.  If url is omitted, the current window.location.href is used.
coerce(Boolean) If true, coerces any numbers or true, false, null, and undefined to their actual value.  Defaults to false if omitted.

Returns

(Object) An object representing the deserialized params string.

Element manipulation

Summary
Functions
jQuery.elemUrlAttrGet the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.
jQuery.fn.querystringUpdate URL attribute in one or more elements, merging the current URL (with or without pre-existing query string params) plus any params object or string into a new URL, which is then set into that attribute.
jQuery.fn.fragmentUpdate URL attribute in one or more elements, merging the current URL (with or without pre-existing fragment/hash params) plus any params object or string into a new URL, which is then set into that attribute.

Functions

jQuery.elemUrlAttr

Get the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.

In the jQuery.fn.querystring and jQuery.fn.fragment methods, this list is used to determine which attribute contains the URL to be modified, if an “attr” param is not specified.

Default Tag-Attribute List

ahref
basehref
iframesrc
imgsrc
inputsrc
formaction
linkhref
scriptsrc

Usage

jQuery.elemUrlAttr( [ tag_attr ] );

Arguments

tag_attr(Object) An object containing a list of tag names and their associated default attribute names in the format { tag: ‘attr’, ...  } to be merged into the internal tag-attribute list.

Returns

(Object) An object containing all stored tag-attribute values.

jQuery.fn.querystring

Update URL attribute in one or more elements, merging the current URL (with or without pre-existing query string params) plus any params object or string into a new URL, which is then set into that attribute.  Like jQuery.param.querystring (build url), but for all elements in a jQuery collection.

Usage

jQuery('selector').querystring( [ attr, ] params [, merge_mode ] );

Arguments

attr(String) Optional name of an attribute that will contain a URL to merge params or url into.  See jQuery.elemUrlAttr for a list of default attributes.
params(Object) A params object to be merged into the URL attribute.
params(String) A URL containing query string params, or params string to be merged into the URL attribute.
merge_mode(Number) Merge behavior defaults to 0 if merge_mode is not specified, and is as-follows:
  • 0: params in the params argument will override any params in attr URL.
  • 1: any params in attr URL will override params in the params argument.
  • 2: params argument will completely replace any query string in attr URL.

Returns

(jQuery) The initial jQuery collection of elements, but with modified URL attribute values.

jQuery.fn.fragment

Update URL attribute in one or more elements, merging the current URL (with or without pre-existing fragment/hash params) plus any params object or string into a new URL, which is then set into that attribute.  Like jQuery.param.fragment (build url), but for all elements in a jQuery collection.

Usage

jQuery('selector').fragment( [ attr, ] params [, merge_mode ] );

Arguments

attr(String) Optional name of an attribute that will contain a URL to merge params into.  See jQuery.elemUrlAttr for a list of default attributes.
params(Object) A params object to be merged into the URL attribute.
params(String) A URL containing fragment (hash) params, or params string to be merged into the URL attribute.
merge_mode(Number) Merge behavior defaults to 0 if merge_mode is not specified, and is as-follows:
  • 0: params in the params argument will override any params in attr URL.
  • 1: any params in attr URL will override params in the params argument.
  • 2: params argument will completely replace any fragment (hash) in attr URL.

Returns

(jQuery) The initial jQuery collection of elements, but with modified URL attribute values.

History, hashchange event

Summary
Functions
jQuery.bbq.pushStateAdds a ‘state’ into the browser history at the current position, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).
jQuery.bbq.getStateRetrieves the current ‘state’ from the browser history, parsing location.hash for a specific key or returning an object containing the entire state, optionally coercing numbers, booleans, null and undefined values.
jQuery.bbq.removeStateRemove one or more keys from the current browser history ‘state’, creating a new state, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).
Events
hashchange event (BBQ)In jQuery 1.4 and newer, the event object passed into any hashchange event callback is augmented with a copy of the location.hash fragment at the time the event was triggered as its event.fragment property.
Files
jQuery hashchange eventVersion: 1.3, Last updated: 7/21/2010
LicenseCopyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.
ExamplesThese working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.
Support and TestingInformation about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).
Known issuesWhile this jQuery hashchange event implementation is quite stable and robust, there are a few unfortunate browser bugs surrounding expected hashchange event-based behaviors, independent of any JavaScript window.onhashchange abstraction.
Release History
Functions
jQuery.fn.hashchangeBind a handler to the window.onhashchange event or trigger all bound window.onhashchange event handlers.
Properties
jQuery.fn.hashchange.delayThe numeric interval (in milliseconds) at which the hashchange event polling loop executes.
jQuery.fn.hashchange.domainIf you’re setting document.domain in your JavaScript, and you want hash history to work in IE6/7, not only must this property be set, but you must also set document.domain BEFORE jQuery is loaded into the page.
jQuery.fn.hashchange.srcIf, for some reason, you need to specify an Iframe src file (for example, when setting document.domain as in jQuery.fn.hashchange.domain), you can do so using this property.
Events
hashchange eventFired when location.hash changes.

Functions

jQuery.bbq.pushState

Adds a ‘state’ into the browser history at the current position, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).

If no arguments are passed, an empty state is created, which is just a shortcut for jQuery.bbq.pushState( {}, 2 ).

Usage

jQuery.bbq.pushState( [ params [, merge_mode ] ] );

Arguments

params(String) A serialized params string or a hash string beginning with # to merge into location.hash.
params(Object) A params object to merge into location.hash.
merge_mode(Number) Merge behavior defaults to 0 if merge_mode is not specified (unless a hash string beginning with # is specified, in which case merge behavior defaults to 2), and is as-follows:
  • 0: params in the params argument will override any params in the current state.
  • 1: any params in the current state will override params in the params argument.
  • 2: params argument will completely replace current state.

Returns

Nothing.

Additional Notes

  • Setting an empty state may cause the browser to scroll.
  • Unlike the fragment and querystring methods, if a hash string beginning with # is specified as the params agrument, merge_mode defaults to 2.

jQuery.bbq.getState

Retrieves the current ‘state’ from the browser history, parsing location.hash for a specific key or returning an object containing the entire state, optionally coercing numbers, booleans, null and undefined values.

Usage

jQuery.bbq.getState( [ key ] [, coerce ] );

Arguments

key(String) An optional state key for which to return a value.
coerce(Boolean) If true, coerces any numbers or true, false, null, and undefined to their actual value.  Defaults to false.

Returns

(Anything) If key is passed, returns the value corresponding with that key in the location.hash ‘state’, or undefined.  If not, an object representing the entire ‘state’ is returned.

jQuery.bbq.removeState

Remove one or more keys from the current browser history ‘state’, creating a new state, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).

If no arguments are passed, an empty state is created, which is just a shortcut for jQuery.bbq.pushState( {}, 2 ).

Usage

jQuery.bbq.removeState( [ key [, key ... ] ] );

Arguments

key(String) One or more key values to remove from the current state, passed as individual arguments.
key(Array) A single array argument that contains a list of key values to remove from the current state.

Returns

Nothing.

Additional Notes

  • Setting an empty state may cause the browser to scroll.

Events

hashchange event (BBQ)

Usage in jQuery 1.4 and newer

In jQuery 1.4 and newer, the event object passed into any hashchange event callback is augmented with a copy of the location.hash fragment at the time the event was triggered as its event.fragment property.  In addition, the event.getState method operates on this property (instead of location.hash) which allows this fragment-as-a-state to be referenced later, even after window.location may have changed.

Note that event.fragment and event.getState are not defined according to W3C (or any other) specification, but will still be available whether or not the hashchange event exists natively in the browser, because of the utility they provide.

The event.fragment property contains the output of jQuery.param.fragment and the event.getState method is equivalent to the jQuery.bbq.getState method.

$(window).bind( 'hashchange', function( event ) {
  var hash_str = event.fragment,
    param_obj = event.getState(),
    param_val = event.getState( 'param_name' ),
    param_val_coerced = event.getState( 'param_name', true );
  ...
});

Usage in jQuery 1.3.2

In jQuery 1.3.2, the event object cannot to be augmented as in jQuery 1.4+, so the fragment state isn’t bound to the event object and must instead be parsed using the jQuery.param.fragment and jQuery.bbq.getState methods.

$(window).bind( 'hashchange', function( event ) {
  var hash_str = $.param.fragment(),
    param_obj = $.bbq.getState(),
    param_val = $.bbq.getState( 'param_name' ),
    param_val_coerced = $.bbq.getState( 'param_name', true );
  ...
});

Additional Notes

  • Due to changes in the special events API, jQuery BBQ v1.2 or newer is required to enable the augmented event object in jQuery 1.4.2 and newer.
  • See jQuery hashchange event for more detailed information.

Files

License

Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses.  http://benalman.com/about/license/

Examples

These working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.

hashchange eventhttp://benalman.com/code/projects/jquery-hashchange/examples/hashchange/
document.domainhttp://benalman.com/code/projects/jquery-hashchange/examples/document_domain/

Support and Testing

Information about what version or versions of jQuery this plugin has been tested with, what browsers it has been tested in, and where the unit tests reside (so you can test it yourself).

jQuery Versions1.2.6, 1.3.2, 1.4.1, 1.4.2
Browsers TestedInternet Explorer 6-8, Firefox 2-4, Chrome 5-6, Safari 3.2-5, Opera 9.6-10.60, iPhone 3.1, Android 1.6-2.2, BlackBerry 4.6-5.
Unit Testshttp://benalman.com/code/projects/jquery-hashchange/unit/

Known issues

While this jQuery hashchange event implementation is quite stable and robust, there are a few unfortunate browser bugs surrounding expected hashchange event-based behaviors, independent of any JavaScript window.onhashchange abstraction.  See the following examples for more information:

Chrome: Back Buttonhttp://benalman.com/code/projects/jquery-hashchange/examples/bug-chrome-back-button/
Firefox: Remote XMLHttpRequesthttp://benalman.com/code/projects/jquery-hashchange/examples/bug-firefox-remote-xhr/
WebKit: Back Button in an Iframehttp://benalman.com/code/projects/jquery-hashchange/examples/bug-webkit-hash-iframe/
Safari: Back Button from a different domainhttp://benalman.com/code/projects/jquery-hashchange/examples/bug-safari-back-from-diff-domain/

Also note that should a browser natively support the window.onhashchange event, but not report that it does, the fallback polling loop will be used.

Release History

1.3(7/21/2010) Reorganized IE6/7 Iframe code to make it more “removable” for mobile-only development.  Added IE6/7 document.title support.  Attempted to make Iframe as hidden as possible by using techniques from http://www.paciellogroup.com/blog/?p=604.  Added support for the “shortcut” format $(window).hashchange( fn ) and $(window).hashchange() like jQuery provides for built-in events.  Renamed jQuery.hashchangeDelay to jQuery.fn.hashchange.delay and lowered its default value to 50.  Added jQuery.fn.hashchange.domain and jQuery.fn.hashchange.src properties plus document-domain.html file to address access denied issues when setting document.domain in IE6/7.
1.2(2/11/2010) Fixed a bug where coming back to a page using this plugin from a page on another domain would cause an error in Safari 4.  Also, IE6/7 Iframe is now inserted after the body (this actually works), which prevents the page from scrolling when the event is first bound.  Event can also now be bound before DOM ready, but it won’t be usable before then in IE6/7.
1.1(1/21/2010) Incorporated document.documentMode test to fix IE8 bug where browser version is incorrectly reported as 8.0, despite inclusion of the X-UA-Compatible IE=EmulateIE7 meta tag.
1.0(1/9/2010) Initial Release.  Broke out the jQuery BBQ event.special window.onhashchange functionality into a separate plugin for users who want just the basic event & back button support, without all the extra awesomeness that BBQ provides.  This plugin will be included as part of jQuery BBQ, but also be available separately.

Functions

jQuery.fn.hashchange

Bind a handler to the window.onhashchange event or trigger all bound window.onhashchange event handlers.  This behavior is consistent with jQuery’s built-in event handlers.

Usage

jQuery(window).hashchange( [ handler ] );

Arguments

handler(Function) Optional handler to be bound to the hashchange event.  This is a “shortcut” for the more verbose form: jQuery(window).bind( ‘hashchange’, handler ).  If handler is omitted, all bound window.onhashchange event handlers will be triggered.  This is a shortcut for the more verbose jQuery(window).trigger( ‘hashchange’ ).  These forms are described in the hashchange event section.

Returns

(jQuery) The initial jQuery collection of elements.

Properties

jQuery.fn.hashchange.delay

The numeric interval (in milliseconds) at which the hashchange event polling loop executes.  Defaults to 50.

jQuery.fn.hashchange.domain

If you’re setting document.domain in your JavaScript, and you want hash history to work in IE6/7, not only must this property be set, but you must also set document.domain BEFORE jQuery is loaded into the page.  This property is only applicable if you are supporting IE6/7 (or IE8 operating in “IE7 compatibility” mode).

In addition, the jQuery.fn.hashchange.src property must be set to the path of the included “document-domain.html” file, which can be renamed or modified if necessary (note that the document.domain specified must be the same in both your main JavaScript as well as in this file).

Usage

jQuery.fn.hashchange.domain = document.domain;

jQuery.fn.hashchange.src

If, for some reason, you need to specify an Iframe src file (for example, when setting document.domain as in jQuery.fn.hashchange.domain), you can do so using this property.  Note that when using this property, history won’t be recorded in IE6/7 until the Iframe src file loads.  This property is only applicable if you are supporting IE6/7 (or IE8 operating in “IE7 compatibility” mode).

Usage

jQuery.fn.hashchange.src = ‘path/to/file.html’;

Events

hashchange event

Fired when location.hash changes.  In browsers that support it, the native HTML5 window.onhashchange event is used, otherwise a polling loop is initialized, running every jQuery.fn.hashchange.delay milliseconds to see if the hash has changed.  In IE6/7 (and IE8 operating in “IE7 compatibility” mode), a hidden Iframe is created to allow the back button and hash-based history to work.

Usage as described in jQuery.fn.hashchange

// Bind an event handler.
jQuery(window).hashchange( function(e) {
  var hash = location.hash;
  ...
});

// Manually trigger the event handler.
jQuery(window).hashchange();

A more verbose usage that allows for event namespacing

// Bind an event handler.
jQuery(window).bind( 'hashchange', function(e) {
  var hash = location.hash;
  ...
});

// Manually trigger the event handler.
jQuery(window).trigger( 'hashchange' );

Additional Notes

  • The polling loop and Iframe are not created until at least one handler is actually bound to the ‘hashchange’ event.
  • If you need the bound handler(s) to execute immediately, in cases where a location.hash exists on page load, via bookmark or page refresh for example, use jQuery(window).hashchange() or the more verbose jQuery(window).trigger( ‘hashchange’ ).
  • The event can be bound before DOM ready, but since it won’t be usable before then in IE6/7 (due to the necessary Iframe), recommended usage is to bind it inside a DOM ready handler.
Retrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location.href.
Adds a ‘state’ into the browser history at the current position, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).
Fired when location.hash changes.
If you’re setting document.domain in your JavaScript, and you want hash history to work in IE6/7, not only must this property be set, but you must also set document.domain BEFORE jQuery is loaded into the page.
Version: 1.3, Last updated: 7/21/2010
Bind a handler to the window.onhashchange event or trigger all bound window.onhashchange event handlers.
Returns a params string equivalent to that returned by the internal jQuery.param method, but sorted, which makes it suitable for use as a cache key.
TODO: DESCRIBE
Specify characters that will be left unescaped when fragments are created or merged using jQuery.param.fragment, or when the fragment is modified using jQuery.bbq.pushState.
In jQuery 1.4 and newer, the event object passed into any hashchange event callback is augmented with a copy of the location.hash fragment at the time the event was triggered as its event.fragment property.
Remove one or more keys from the current browser history ‘state’, creating a new state, setting location.hash and triggering any bound hashchange event callbacks (provided the new state is different than the previous state).
Deserialize a params string into an object, optionally coercing numbers, booleans, null and undefined values; this method is the counterpart to the internal jQuery.param method.
Retrieve the query string from a URL or if no arguments are passed, the current window.location.href.
Update URL attribute in one or more elements, merging the current URL (with or without pre-existing query string params) plus any params object or string into a new URL, which is then set into that attribute.
Update URL attribute in one or more elements, merging the current URL (with or without pre-existing fragment/hash params) plus any params object or string into a new URL, which is then set into that attribute.
Merge a URL, with or without pre-existing query string params, plus any object, params string or URL containing query string params into a new URL.
Get the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient.
Merge a URL, with or without pre-existing fragment (hash) params, plus any object, params string or URL containing fragment (hash) params into a new URL.
Retrieves the current ‘state’ from the browser history, parsing location.hash for a specific key or returning an object containing the entire state, optionally coercing numbers, booleans, null and undefined values.
The numeric interval (in milliseconds) at which the hashchange event polling loop executes.
If, for some reason, you need to specify an Iframe src file (for example, when setting document.domain as in jQuery.fn.hashchange.domain), you can do so using this property.
Close