Ajax Navigation
The $.mobile.navigate
method and the navigate
event form the foundation of jQuery Mobile's navigation infrastructure. As such, they can function outside the confines of jQuery Mobile as a clean and intuitive navigation/history API.
Introduction
jQuery Mobile includes a navigation system to load pages into the DOM via Ajax, enhance the new content, then display pages with a rich set of animated transitions. The navigation system uses progressive enhancement to automatically 'hijack' standard links and form submissions and route them as an Ajax request.
One of jQuery Mobile's core features is the ability to load and view content from disparate pages into the initial document with support for standard navigation methods like anchors and the back button. To accomplish this the library has progressive support for hashchange
and popstate
coupled with internal history tracking which can be used à la carte.
An example use case would be something like Twitter's web client. The first step is to hijack link clicks on the page and use the URL that represents that UI state to track history with $.mobile.navigate
. It's at this point that any additional information about the UI necessary for operation on return using the back button would be stored (see, foo
property of the object argument to the navigate method).
// Define a click binding for all anchors in the page
$( "a" ).on( "click", function( event ) {
// Prevent the usual navigation behavior
event.preventDefault();
// Alter the url according to the anchor's href attribute, and
// store the data-foo attribute information with the url
$.mobile.navigate( $(this).attr( "href" ), {
foo: $(this).attr("data-foo")
});
// Hypothetical content alteration based on the url. E.g, make
// an Ajax request for JSON data and render a template into the page.
alterContent( $(this).attr("href") );
});
Next, a navigate
event binding helps in responding to backward and forward navigation via the browsers history API. Here the alterContent
function can address the direction in which the browser is navigating as well as any additional information stored on the data object when $.mobile.navigate
was invoked to store the corresponding history entry.
// Respond to back/forward navigation
$( window ).on( "navigate", function( event, data ){
if ( data.state.foo ) {
// Make use of the arbitrary data stored
}
if ( data.state.direction == "back" ) {
// Make use of the directional information
}
// reset the content based on the url
alterContent( data.state.url );
});
Event Example
jQuery Mobile provides the navigate
event as a wrapper for both hashchange
and popstate
. That is, where a binding to both events would be required to support browsers with and without popstate
only one binding to navigate
is necessary. In this example, altering the hash will trigger the popstate
or hashchange
event depending on the browser, but only a single navigate
binding is necessary. Make sure to use the back button after alterting the hash to see that the event is fired in both cases.
Note: When viewing the console output, some browsers (e.g. Chrome) fire a popstate on the initial page load
// Bind to the navigate event
$( window ).on( "navigate", function() {
console.log( "navigated!" );
});
// Bind to the click of the example link
$( "#event-example" ).click(function( event ) {
event.preventDefault();
location.hash = "foo";
});
Event Example
See also the API documentation of the navigate
event.
Method Example
jQuery Mobile provides the $.mobile.navigate
method as a means to track history and receive additional information along with navigate
events. In this example, when the method example link is clicked, the url will be changed twice. The first time will it will store additional aribitrary information along with the URL and hash stored by the method. The second time it will simply change the url and store the URL and hash. When the browser moves backward through history the navigate
event is triggered as in the event example above but along with it comes information about the direction of history traversal, the url, the hash, and the arbitrary data stored with the first call to the navigate method.
Note: The arbitrary state properties must be chosen carefully to avoid the url, hash, and direction properties. This is a shortcoming that will be addressed in future releases.
// Bind to the click of the example link
$( "#method-example" ).click(function( event ) {
// Append #bar
$.mobile.navigate( "#bar", {
info: "info about the #bar hash"
});
// Replace #bar with #baz
$.mobile.navigate( "#baz" );
// Log the results of the navigate event
$( window ).on( "navigate", function( event, data ) {
console.log( data.state.info );
console.log( data.state.direction );
console.log( data.state.url );
console.log( data.state.hash );
});
// Go back to pop the state for #bar and log it
window.history.back();
});
Method Example
See also the API documentation of the $.mobile.navigate
method.