Version: 1.2.1, Last updated: 2/17/2010
| jQuery BBQ: Back Button & Query Library | Version: 1.2.1, Last updated: 2/17/2010 |
| License | Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. |
| Examples | These working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used. |
| 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). |
| Release History | |
| Param (to string) | |
| Functions | |
| jQuery. | Retrieve the query string from a URL or if no arguments are passed, the current window.location. |
| jQuery. | 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. | Retrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location. |
| jQuery. | 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. | 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. |
| Deparam (from string) | |
| Functions | |
| jQuery. | 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. |
| jQuery. | Parse the query string from a URL or the current window.location, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values. |
| jQuery. | Parse the fragment (hash) from a URL or the current window.location, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values. |
| Element manipulation | |
| Functions | |
| jQuery. | Get the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient. |
| jQuery. | 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. |
| jQuery. | 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. |
| History, hashchange event | |
| Functions | |
| jQuery. | 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). |
| jQuery. | 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. |
| jQuery. | 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). |
| 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 event | Version: 1.2, Last updated: 2/11/2010 |
| License | Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. |
| Examples | This working example, complete with fully commented code, illustrate one way in which this plugin can be used. |
| 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). |
| 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. |
| Release History | |
| Properties | |
| jQuery. | The numeric interval (in milliseconds) at which the hashchange event polling loop executes. |
| Events | |
| hashchange event | Fired when location.hash changes. |
Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. http://benalman.com/about/license/
These working examples, complete with fully commented code, illustrate a few ways in which this plugin can be used.
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 Versions | 1.3.2, 1.4.1, 1.4.2 |
| Browsers Tested | Internet Explorer 6-8, Firefox 2-3.7, Safari 3-4, Chrome 4-5, Opera 9.6-10.1. |
| Unit Tests | http://benalman.com |
| 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 |
| Functions | |
| jQuery. | Retrieve the query string from a URL or if no arguments are passed, the current window.location. |
| jQuery. | 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. | Retrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location. |
| jQuery. | 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. | 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. |
Retrieve the query string from a URL or if no arguments are passed, the current window.location.
jQuery.param.querystring( [ url ] );
| url | (String) A URL containing query string params to be parsed. If url is not passed, the current window.location is used. |
(String) The parsed query string, with any leading “?” removed.
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.querystring( url, params [, merge_mode ] );
| 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: |
(String) Either a params string with urlencoded data or a URL with a urlencoded query string in the format ‘a=b&c=d&e=f’.
Retrieve the fragment (hash) from a URL or if no arguments are passed, the current window.location.
jQuery.param.fragment( [ url ] );
| url | (String) A URL containing fragment (hash) params to be parsed. If url is not passed, the current window.location is used. |
(String) The parsed fragment (hash) string, with any leading “#” removed.
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.fragment( url, params [, merge_mode ] );
| 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: |
(String) Either a params string with urlencoded data or a URL with a urlencoded fragment (hash) in the format ‘a=b&c=d&e=f’.
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.
jQuery.param.fragment.noEscape( [ chars ] );
| chars | (String) The characters to not escape in the fragment. If unspecified, defaults to empty string (escape all characters). |
Nothing.
| Functions | |
| jQuery. | 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. |
| jQuery. | Parse the query string from a URL or the current window.location, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values. |
| jQuery. | Parse the fragment (hash) from a URL or the current window.location, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values. |
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.
jQuery.deparam( params [, coerce ] );
| 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. |
(Object) An object representing the deserialized params string.
Parse the query string from a URL or the current window.location, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.
jQuery.deparam.querystring( [ url ] [, coerce ] );
| url | (String) An optional params string or URL containing query string params to be parsed. If url is omitted, the current window.location is used. |
| coerce | (Boolean) If true, coerces any numbers or true, false, null, and undefined to their actual value. Defaults to false if omitted. |
(Object) An object representing the deserialized params string.
Parse the fragment (hash) from a URL or the current window.location, deserializing it into an object, optionally coercing numbers, booleans, null and undefined values.
jQuery.deparam.fragment( [ url ] [, coerce ] );
| url | (String) An optional params string or URL containing fragment (hash) params to be parsed. If url is omitted, the current window.location is used. |
| coerce | (Boolean) If true, coerces any numbers or true, false, null, and undefined to their actual value. Defaults to false if omitted. |
(Object) An object representing the deserialized params string.
| Functions | |
| jQuery. | Get the internal “Default URL attribute per tag” list, or augment the list with additional tag-attribute pairs, in case the defaults are insufficient. |
| jQuery. | 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. |
| jQuery. | 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. |
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.
| a | href |
| base | href |
| iframe | src |
| img | src |
| input | src |
| form | action |
| link | href |
| script | src |
jQuery.elemUrlAttr( [ tag_attr ] );
| 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. |
(Object) An object containing all stored tag-attribute values.
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.
jQuery('selector').querystring( [ attr, ] params [, merge_mode ] );| 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: |
(jQuery) The initial jQuery collection of elements, but with modified URL attribute values.
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.
jQuery('selector').fragment( [ attr, ] params [, merge_mode ] );| 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: |
(jQuery) The initial jQuery collection of elements, but with modified URL attribute values.
| Functions | |
| jQuery. | 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). |
| jQuery. | 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. |
| jQuery. | 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). |
| 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 event | Version: 1.2, Last updated: 2/11/2010 |
| License | Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. |
| Examples | This working example, complete with fully commented code, illustrate one way in which this plugin can be used. |
| 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). |
| 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. |
| Release History | |
| Properties | |
| jQuery. | The numeric interval (in milliseconds) at which the hashchange event polling loop executes. |
| Events | |
| hashchange event | Fired when location.hash changes. |
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 ).
jQuery.bbq.pushState( [ params [, merge_mode ] ] );
| 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: |
Nothing.
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.
jQuery.bbq.getState( [ key ] [, coerce ] );
| 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. |
(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.
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 ).
jQuery.bbq.removeState( [ key [, key ... ] ] );
| 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. |
Nothing.
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 );
...
});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 );
...
});Version: 1.2, Last updated: 2/11/2010
Copyright © 2010 “Cowboy” Ben Alman, Dual licensed under the MIT and GPL licenses. http://benalman.com/about/license/
This working example, complete with fully commented code, illustrate one way in which this plugin can be used.
| hashchange event | http://benalman.com |
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 Versions | 1.3.2, 1.4.1, 1.4.2 |
| Browsers Tested | Internet Explorer 6-8, Firefox 2-3.7, Safari 3-4, Chrome, Opera 9.6-10.1. |
| Unit Tests | http://benalman.com |
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 Button | http://benalman.com |
| Firefox: Remote XMLHttpRequest | http://benalman.com |
| WebKit: Back Button in an Iframe | http://benalman.com |
| Safari: Back Button from a different domain | http://benalman.com |
| 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. |
The numeric interval (in milliseconds) at which the hashchange event polling loop executes. Defaults to 100.
Fired when location.hash changes. In browsers that support it, the native window.onhashchange event is used (IE8, FF3.6), otherwise a polling loop is initialized, running every jQuery.hashchangeDelay milliseconds to see if the hash has changed. In IE 6 and 7, a hidden Iframe is created to allow the back button and hash-based history to work.
$(window).bind( 'hashchange', function(e) {
var hash = location.hash;
...
});