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 API

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 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 (eg, 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

Method Example API

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