pagebeforechange eventversion added: 1.0, deprecated: 1.4.3

Description: Triggered twice during the page change cyle: First prior to any page loading or transition and next after page loading completes successfully, but before the browser history has been modified by the navigation process.

  • jQuery( ".selector" ).on( "pagebeforechange", function( event ) { ... } )

When received with data.toPage set to a string, the event indicates that navigation is about to commence. The value stored in data.toPage is the URL of the page that will be loaded.

When received with data.toPage set to a jQuery object, the event indicates that the destination page has been loaded and navigation will continue.

If the page change cycle was initiated programmatically, and, instead of a URL a jQuery object containing a page was given, then the event will be triggered both times with data.toPage set to the jQuery object containing the destination page.

The pagebeforechange event is triggered either by explicit navigation on the part of the user (e.g. by clicking on a link or by running code that results in a call to the pagecontainer change() method), or by implicit navigation caused by the user clicking the browser's "Back" or "Forward" buttons.

Explicit navigation results in both pagebeforechange events being triggered before a new entry is added to the browser's navigation history.

Implicit navigation results in both pagebeforechange events being triggered after the browser's navigation history has been updated.

In addition to the event parameter, handlers of this event will receive a second parameter, data. The second parameter is an object containing the following properties:

  • toPage (object or string)
    • This 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.
  • options (object)
    • This object contains the configuration options to be used for the current changePage() call.

It should be noted that callbacks can modify both the toPage and options properties to alter the behavior of the current changePage() call. So for example, the toPage can be mapped to a different url from within a callback to do a sort of redirect.

Note: The triggering of this event is deprecated as of jQuery Mobile 1.4.3. It will no longer be triggered in 1.6.0.

The replacement for pagebeforechange is the pagecontainer widget's pagecontainerbeforechange event. In jQuery Mobile >= 1.4.3, the two events are identical except for their name and the fact that pagecontainerbeforechange is triggered on the pagecontainer, whereas pagebeforechange is triggered on the page.