Smooth Navigation Between Pages
body
element. This limitation will be removed in future versions of jQuery Mobile.jQuery Mobile's central abstraction is the use of multiple pages inside a single HTML document. The children of the body
are all div
elements that have been enhanced into page widgets. These are jQuery Mobile pages.
Only one page is visible at a time. Upon navigation, the currently visible page is hidden, and another page is shown. Moving from one page to another is accomplished via a transition. This is not possible when navigating between HTML documents via HTTP, because the browser discards all state associated with the source page when navigating to the target page, making it impossible to perform this task via a smooth transition effect such as a fade or a slide.
Multipage Documents
In its simplest form, the HTML document retrieved by the browser has a body
consisting of several div
elements which are enhanced using the page
widget. Each such page has an id
attribute to distinguish it from other pages.
The pages can be interlinked using anchors. When the user clicks such an anchor, a new history entry is created, and the page to which the anchor refers is displayed by means of a smooth transition from the previous page. The example below illustrates a multipage setup. Note: If the example below animates using a fade transition instead of the slide transition requested in the anchor, it is because your browser does not support CSS 3D transforms.
<!doctype html> <html> <head> <title>Multipage example</title> <meta name="viewport" content="width=device-width, initial-scale=1" /> <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css" /> <script src="//code.jquery.com/jquery-1.10.2.min.js"></script> <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script> </head> <body> <div data-role="page" id="page1"> <div data-role="header"> <h1>Page 1</h1> </div> <div role="main" class="ui-content"> <a href="#page2" data-transition="slide" class="ui-btn ui-corner-all ui-btn-inline">Go To Page 2</a> </div> </div> <div data-role="page" id="page2"> <div data-role="header"> <h1>Page 2</h1> </div> <div role="main" class="ui-content"> <a href="#page1" data-rel="back" data-transition="slide" class="ui-btn ui-corner-all ui-btn-inline">Go Back To Page 1</a> </div> </div> </body> </html>
Ajax page navigation
jQuery Mobile allows you to replace the browser's standard HTTP navigation with Ajax-based navigation. It overrides the browser's default link handling behavior. It intercepts clicks on anchors containing links to other documents and upon each such click it checks whether the document can be retrieved via Ajax. A link has to meet the following criteria in order for the document to which it links to be retrieved via Ajax:
- The global configuration option
$.mobile.linkBindingEnabled
must betrue
. - The click event's default must not be prevented and it must be a left-click.
- The link must not have any of the following attributes:
data-rel="back"
data-rel="external
data-ajax="false"
- The
target
attribute must not be present
- The global configuration option
$.mobile.ajaxEnabled
must betrue
. - The link must be to the same domain or it must be to a permitted cross-domain-request destination.
If these criteria are met jQuery Mobile retrieves the document via Ajax. It is important to realize that, while the document is retrieved in its entirety, only the first jQuery Mobile page is displayed. The header and the rest of the body are discarded. Thus, it is not possible to retrieve a multi-page document via Ajax, nor is it possible to execute scripts located in the header.
After Ajax retrieval, jQuery Mobile displays the page via a transition. The transition can be specified on the link that opens the page using the data-transition
attribute. If no transition is specified, then $.mobile.defaultPageTransition
is used or, if the incoming page is a dialog, then $.mobile.defaultDialogTransition
is used.
If the browser supports the replaceState
API the location bar is updated such that it displays the URL of the document that was retrieved via Ajax. This latter step has the following implications for site/application design:
- Since the user can copy the URL of a page other than the start page, the application must be designed such that it can start from any of its pages. The best way to achieve this is to include jQuery Mobile and your application code in the header for all the pages of the site/application, and ensure initial state consistency during the
pagecreate
event. - If your application includes widgets shared by multiple pages, such as a global navigation menu contained in a popup, then you must make sure that each page contains a copy of the popup's markup, so that the first page that is loaded defines the popup and makes it available to subsequent pages loaded into the DOM via Ajax.
false
true
indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time. This option is also exposed as a data attribute: data-defaults="true"
.
Code examples:
Initialize the pagecontainer with the defaults
option specified:
$( ".selector" ).pagecontainer({ defaults: true });
Get or set the defaults
option, after initialization:
// Getter var defaults = $( ".selector" ).pagecontainer( "option", "defaults" ); // Setter $( ".selector" ).pagecontainer( "option", "defaults", true );
false
true
. This option is also exposed as a data attribute: data-disabled="true"
.
Code examples:
Initialize the pagecontainer with the disabled
option specified:
$( ".selector" ).pagecontainer({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).pagecontainer( "option", "disabled" ); // Setter $( ".selector" ).pagecontainer( "option", "disabled", true );
a
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Code examples:
Initialize the pagecontainer with the theme
option specified:
$( ".selector" ).pagecontainer({ theme: "b" });
Get or set the theme
option, after initialization:
// Getter var theme = $( ".selector" ).pagecontainer( "option", "theme" ); // Setter $( ".selector" ).pagecontainer( "option", "theme", "b" );
- toThe URL to which to navigate. This can be specified either as a string, or as a jQuery collection object containing the page DOM element.
- optionsType: Object
- allowSamePageTransition (default:
false
)Type: BooleanBy default,change()
ignores requests to change to the current active page. Setting this option totrue
allows the request to execute. Developers should note that some of the page transitions assume that the fromPage and toPage of achange()
request are different, so they may not animate as expected. Developers are responsible for either providing a proper transition, or turning it off for this specific case. - changeHash (default:
true
)Type: BooleanWhether to create a new browser history entry as part of the navigation sequence. Possible values:true The pagecontainer will create a browser history entry as part of moving to the desired page. Thus, the user can use the browser's "Back" and "Forward" buttons to navigate between the source page and the destination page. false The pagecontainer will navigate to the desired page without creating a new browser history entry. The desired page replaces the current page, and the browser's "Back" and "Forward" buttons cannot be used to navigate between the source page and the destination page. - data (default:
undefined
)The data to send with an Ajax page request. - dataUrl (default:
undefined
)Type: StringThe URL to use when updating the browser location uponchange()
completion. If not specified, the value of the data-url attribute of the page element is used. - loadMsgDelay (default:
50
)Type: NumberThe number of milliseconds by which to delay the appearance of the loading message. If the load completes within this time, no loading message is displayed. - reloadPage (default:
false
)Type: BooleanNote: This property is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use property
reload
instead.Whether to force a reload of the page even when it is already in the DOM. Used only when the 'url' argument is a URL.
(version deprecated: 1.4.0) - reload (default:
false
)Type: BooleanWhether to force a reload of the page even when it is already in the DOM. Used only when the 'url' argument is a URL. - reverse (default:
false
)Type: BooleanWhether the transition shall be applied in reverse. By setting this value totrue
you can simulate returning to a previous page, even when the actual navigation sequence is in a forward direction. - role (default:
undefined
)Type: StringThe data-role value to be used when displaying the page. By default this isundefined
which means rely on the value of the @data-role attribute defined on the element. - showLoadMsg (default:
false
)Type: BooleanWhether to display a message indicating that the page is loading. - transition (default:
undefined
)Type: StringThe transition that should be used for the page change. If the value isundefined
, the value of$.mobile.defaultPageTransition
(currently"fade"
) will be used for pages, and$.mobile.defaultDialogTransition
(currently"pop"
) will be used for dialogs.Default value:
undefined
- type (default:
"get"
)Type: StringThe type of HTTP request to use ("get", "post", etc.). Used only when the 'to' argument is a URL.
-
Invoke the change method:
$( ".selector" ).pagecontainer( "change" );
Programmatically change from one page to another.
$( ":mobile-pagecontainer" ).pagecontainer( "change", "confirm.html", { role: "dialog" } );
- This method does not accept any arguments.
Invoke the getActivePage method:
$( ".selector" ).pagecontainer( "getActivePage" );
- urlType: StringThe URL from which to load the page. This can be an absolute or a relative URL (e.g. "about/us.html").
- optionsType: ObjectA hash containing options that affect the behavior of the method.
- type (default:
"get"
)Type: StringThe type of HTTP request to use ("get", "post", etc.). - data (default:
undefined
)The data to send with an Ajax page request. - reloadPage (default:
false
)Type: BooleanNote: This property is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Use property
reload
instead.Whether to force a reload of the page even when it is already in the DOM. Used only when the 'url' argument is a URL.
(version deprecated: 1.4.0) - reload (default:
false
)Type: BooleanWhether to force a reload of the page even when it is already in the DOM. Used only when the 'url' argument is a URL. - role (default:
undefined
)Type: StringThe data-role value to be used when displaying the page. By default this isundefined
which means rely on the value of the @data-role attribute defined on the element. - showLoadMsg (default:
true
)Type: BooleanWhether to display a message indicating that the page is loading. - loadMsgDelay (default:
50
)Type: NumberThe number of milliseconds by which to delay the appearance of the loading message. If the load completes within this time, no loading message is displayed.
-
Invoke the load method:
$( ".selector" ).pagecontainer( "load" );
Load an external page, enhance its content, and insert it into the DOM.
$( ":mobile-pagecontainer" ).pagecontainer( "load", "confirm.html", { role: "dialog" } );
pagecontainerbeforechange
- eventType: Event
- uiType: Object
- toPageThis property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.
- prevPageType: jQueryA jQuery collection object that contains the from page DOM element.
- optionsType: jQueryThe configuration options to be used for the current
change()
call
-
Initialize the pagecontainer with the beforechange callback specified:
$( ".selector" ).pagecontainer({ beforechange: function( event, ui ) {} });
Bind an event listener to the pagecontainerbeforechange event:
$( ".selector" ).on( "pagecontainerbeforechange", function( event, ui ) {} );
pagecontainerbeforehide
Initialize the pagecontainer with the beforehide callback specified:
$( ".selector" ).pagecontainer({ beforehide: function( event, ui ) {} });
Bind an event listener to the pagecontainerbeforehide event:
$( ".selector" ).on( "pagecontainerbeforehide", function( event, ui ) {} );
pagecontainerbeforeload
Callbacks bound to this event can call preventDefault()
on the event to indicate that they are handling the load request. Callbacks that do this MUST make sure they call resolve()
or reject()
on the deferred object reference contained in the object passed to the callback via its ui
parameter.
- eventType: Event
- uiType: Object
- urlType: StringThe absolute or relative URL that was passed into load() by the caller.
- absUrlType: StringThe absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.
- dataUrlType: StringThe filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.
- toPageType: StringA string containing the url being loaded
- prevPageType: jQueryA jQuery collection object that contains the from page DOM element.
- deferredType: DeferredDeferred to be resolved or rejected upon completion of content load. Callbacks that call
preventDefault()
on the event MUST callresolve()
orreject()
on this object so thatchange()
requests resume processing. Deferred object observers expect the deferred object to be resolved like this:$( document ).on( "pagecontainerbeforeload", function( event, data ) { // Let the framework know we're going to handle the load. event.preventDefault(); // ... load the document then insert it into the DOM ... // at some point, either in this callback, or through // some other async means, call resolve, passing in // the following args, plus a jQuery collection object // containing the DOM element for the page. data.deferred.resolve( data.absUrl, data.options, page ); });
or rejected like this:
$( document ).on( "pagecontainerbeforeload", function( event, data ) { // Let the framework know we're going to handle the load. event.preventDefault(); // ... load the document then insert it into the DOM ... // at some point, if the load fails, either in this // callback, or through some other async means, call // reject like this: data.deferred.reject( data.absUrl, data.options ); });
- optionsType: ObjectThis object contains the options that were passed into load().
-
Initialize the pagecontainer with the beforeload callback specified:
$( ".selector" ).pagecontainer({ beforeload: function( event, ui ) {} });
Bind an event listener to the pagecontainerbeforeload event:
$( ".selector" ).on( "pagecontainerbeforeload", function( event, ui ) {} );
pagecontainerbeforeshow
Initialize the pagecontainer with the beforeshow callback specified:
$( ".selector" ).pagecontainer({ beforeshow: function( event, ui ) {} });
Bind an event listener to the pagecontainerbeforeshow event:
$( ".selector" ).on( "pagecontainerbeforeshow", function( event, ui ) {} );
pagecontainerbeforetransition
- eventType: Event
- uiType: Object
- absUrlType: StringThe absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.
- optionsType: ObjectThe configuration options to be used for the current
change()
call. - originalHrefType: StringThe href from the link that started the page change process.
- toPageType: jQueryA jQuery collection object that contains the destination page DOM element.
- prevPageType: jQueryA jQuery collection object that contains the from page DOM element.
-
Initialize the pagecontainer with the beforetransition callback specified:
$( ".selector" ).pagecontainer({ beforetransition: function( event, ui ) {} });
Bind an event listener to the pagecontainerbeforetransition event:
$( ".selector" ).on( "pagecontainerbeforetransition", function( event, ui ) {} );
pagecontainerchange
Initialize the pagecontainer with the change callback specified:
$( ".selector" ).pagecontainer({ change: function( event, ui ) {} });
Bind an event listener to the pagecontainerchange event:
$( ".selector" ).on( "pagecontainerchange", function( event, ui ) {} );
pagecontainerchangefailed
change()
request fails to load the page.- eventType: Event
- uiType: Object
- toPageThis property represents the page the caller wishes to make active. It may be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page, in which case the value exactly matches the first argument to the
change()
call that triggered the event. - optionsType: ObjectThe configuration options to be used for the current
change()
call. - prevPageType: jQueryA jQuery collection object that contains the from page DOM element.
-
Initialize the pagecontainer with the changefailed callback specified:
$( ".selector" ).pagecontainer({ changefailed: function( event, ui ) {} });
Bind an event listener to the pagecontainerchangefailed event:
$( ".selector" ).on( "pagecontainerchangefailed", function( event, ui ) {} );
pagecontainercreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the pagecontainer with the create callback specified:
$( ".selector" ).pagecontainer({ create: function( event, ui ) {} });
Bind an event listener to the pagecontainercreate event:
$( ".selector" ).on( "pagecontainercreate", function( event, ui ) {} );
pagecontainerhide
pagehide
event, this event is not triggered on the "fromPage" but the pagecontainer widget's element. Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.
You can access the nextPage
properties via the second argument of a bound callback function. For example:
$( ":mobile-pagecontainer" ).on( "pagecontainerhide", function( event, ui ) { alert( "This page was just shown: " + ui.nextPage ); });
For these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the mobileinit
handler, as described on the global config page.
Initialize the pagecontainer with the hide callback specified:
$( ".selector" ).pagecontainer({ hide: function( event, ui ) {} });
Bind an event listener to the pagecontainerhide event:
$( ".selector" ).on( "pagecontainerhide", function( event, ui ) {} );
pagecontainerload
- eventType: Event
- uiType: Object
- urlType: StringThe absolute or relative URL that was passed into load() by the caller.
- absUrlType: StringThe absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.
- dataUrlType: StringThe filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.
- optionsType: ObjectThis object contains the options that were passed into load().
- xhrType: XMLHttpRequestThe jQuery XMLHttpRequest object used when attempting to load the page. This is what gets passed as the 3rd argument to the framework's
$.ajax()
success callback. - textStatusType: StringAccording to the jQuery Core documentation, this will be a string describing the status. This is what gets passed as the 2nd argument to the framework's
$.ajax()
error callback. It may also benull
. - toPageType: jQueryA jQuery collection object that contains the destination page DOM element.
- prevPageType: jQueryA jQuery collection object that contains the from page DOM element in a detached state.
-
Initialize the pagecontainer with the load callback specified:
$( ".selector" ).pagecontainer({ load: function( event, ui ) {} });
Bind an event listener to the pagecontainerload event:
$( ".selector" ).on( "pagecontainerload", function( event, ui ) {} );
pagecontainerloadfailed
By default, after dispatching this event, the framework will display a page failed message and call reject() on the deferred object contained within the event's ui
parameter. Callbacks can prevent this default behavior from executing by calling preventDefault()
on the event.
- eventType: Event
- uiType: Object
- urlType: StringThe absolute or relative URL that was passed into load() by the caller.
- absUrlType: StringThe absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.
- dataUrlType: StringThe filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.
- toPageType: StringA string containing the url the was attempted to be loaded.
- prevPageType: jQueryA jQuery collection object that contains the from page DOM element.
- deferredType: DeferredCallbacks that call
preventDefault()
on the event, MUST callresolve()
orreject()
on this object so thatchange()
requests resume processing. Deferred object observers expect the deferred object to be resolved like this:$( document ).on( "pageloadfailed", function( event, data ) { // Let the framework know we're going to handle things. event.preventDefault(); // ... attempt to load some other page ... // at some point, either in this callback, or through // some other async means, call resolve, passing in // the following args, plus a jQuery collection object // containing the DOM element for the page. data.deferred.resolve( data.absUrl, data.options, page ); });
or rejected like this:
$( document ).on( "pageloadfailed", function( event, data ) { // Let the framework know we're going to handle things. event.preventDefault(); // ... attempt to load some other page ... // at some point, if the load fails, either in this // callback, or through some other async means, call // reject like this: data.deferred.reject( data.absUrl, data.options ); });
- optionsType: ObjectThis object contains the options that were passed into load().
- xhrType: XMLHttpRequestThe jQuery XMLHttpRequest object used when attempting to load the page. This is what gets passed as the first argument to the framework's
$.ajax()
error callback. - textStatusType: StringAccording to the jQuery Core documentation, possible values for this property, aside from
null
, are "timeout", "error", "abort", and "parsererror". This is what gets passed as the 2nd argument to the framework's$.ajax()
error callback. - errorThrownAccording to the jQuery Core documentation, this property may be an exception object if one occurred, or if an HTTP error occurred this will be set to the textual portion of the HTTP status. Otherwise it will be
null
. This is what gets passed as the 3rd argument to the framework's$.ajax()
error callback.
-
Initialize the pagecontainer with the loadfailed callback specified:
$( ".selector" ).pagecontainer({ loadfailed: function( event, ui ) {} });
Bind an event listener to the pagecontainerloadfailed event:
$( ".selector" ).on( "pagecontainerloadfailed", function( event, ui ) {} );
pagecontainerremove
Initialize the pagecontainer with the remove callback specified:
$( ".selector" ).pagecontainer({ remove: function( event, ui ) {} });
Bind an event listener to the pagecontainerremove event:
$( ".selector" ).on( "pagecontainerremove", function( event, ui ) {} );
pagecontainershow
pageshow
event, this event is not triggered on the "toPage" but the pagecontainer widget's element. You can access the prevPage
properties via the second argument of a bound callback function. For example:
$( ":mobile-pagecontainer" ).on( "pagecontainershow", function( event, ui ) { alert( "This page was just hidden: " + ui.prevPage ); });
For these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the mobileinit
handler, as described on the global config page.
- eventType: Event
- uiType: Object
- toPageType: jQueryA jQuery collection object that contains the destination page DOM element.
- prevPageType: jQueryA jQuery collection object that contains the page DOM element that we just transitioned away from. Note that this collection is empty when the first page is transitioned in during application startup.
-
Initialize the pagecontainer with the show callback specified:
$( ".selector" ).pagecontainer({ show: function( event, ui ) {} });
Bind an event listener to the pagecontainershow event:
$( ".selector" ).on( "pagecontainershow", function( event, ui ) {} );
pagecontainertransition
- eventType: Event
- uiType: Object
- absUrlType: StringThe absolute version of the url of the destination page. If url was relative, it is resolved against the url used to load the current active page.
- optionsType: ObjectThis object contains the options that were passed into load().
- originalHrefType: StringThe href from the link that started the page change process.
- toPageType: jQueryThis property represents the page to which the caller has transitioned. It is a jQuery collection object containing the page DOM element.
- prevPageType: jQueryA jQuery collection object that contains the from page DOM element.
-
Initialize the pagecontainer with the transition callback specified:
$( ".selector" ).pagecontainer({ transition: function( event, ui ) {} });
Bind an event listener to the pagecontainertransition event:
$( ".selector" ).on( "pagecontainertransition", function( event, ui ) {} );
Please login to continue.