Page change events poorly documented/implemented

[deAtog]

The pagebeforechange, pagechange, and pagechangefailed events are fired on the page container element and not the currently active page. This is inconsistent with the pageinit, pagebeforehide, pagebeforeshow, pagehide, and pageshow events which all fire on the currently active page. These events should either be renamed, or modified to occur on the active page. Consider the following:

<div id="container">
   <div data-role="page" id="pg1">
      <p>This is page 1</p>
      <a href="#pg2" data-role="button">Next</a>
   </div>
   <div data-role="page" id="pg2">
      <p>This is page 2</p>
   </div>
</div>

<script>
$(document).delegate(
   "#pg1",
   "pagebeforechange",
   function(){
      // This code will never run
      alert("About to transition away from page 1");
   }
);

$(document).delegate(
   "#container",
   "pagebeforechange",
   function(){
      // This code will run
      alert("The page is about to change");
   }
);
</script>

Note: - If a container is not defined, these events will fire on the body element.

[jblas]

The reason the page change events are fired on the container is because at the time a change request is issued, the page we are going to change to may not even be loaded yet.

[deAtog]

I fully understand the reasons for the current implementation. The documentation however is not very clear in regards to how to properly capture these events. Every transition involves two pages, the "from" page and the "to" page. From the documentation, one would expect these events to be fired on the "from" page as the "to" page, provided in the data to the callback function, may not be loaded and can be changed. There are few cases where one would not expect to receive these events. IE, one would not expect to receive the pagebeforechange event upon loading the initial page or if the page has just been refreshed. In the example given, if the event were raised on #pg1, validation could be performed during the pagebeforechange event and the event could be canceled if errors are present. The way it's currently implemented, the currently active page needs to be determined before proceeding with validation.

Alternatively, it may be better to simply add additional events allowing for validation to occur on the active page. IE pagevalidating, and pagevalidated. The pagevalidating event could then be used to validate fields or report errors and the pagevalidated event could be used to save data from the current page. By canceling the pagevalidating event one could prevent the transition and possibly display an error to the user.

Nonetheless, the naming of these events suggest that they occur on the page and not the container. If the events are kept as they are, the documentation should be updated and examples of their use should be provided. Otherwise, the events should be renamed.

[deAtog]

Simply put, the information stated here: http://jquerymobile.com/demos/1.1.0-rc.2/docs/pages/page-dynamic.html should be added to here: http://jquerymobile.com/demos/1.1.0-rc.2/docs/api/events.html

After much investigation the following workaround can be used to add validating events to pages:

$(document).bind("pagebeforechange", function(event, options) {
    // This event is called twice, before the page is loaded and after.
    // options.toPage will be of type string during the first event and
    // and a jQuery enhanced object during the second.

    // We only handle the first event as it contains the actual page
    // identifier and occurs before the toPage is ever loaded.
    if (typeof(options.toPage) == "string") {
        if ($.mobile.activePage) {
            var e = new $.Event("pagevalidating");

            $.mobile.activePage.trigger(e, options);

            if (e.isDefaultPrevented()) {
                event.preventDefault();
            } else {
                $.mobile.activePage.trigger("pagevalidated", options);
            }
        }
    }
});

You can then use $(pageid).on("pagevalidating", function(){}) to handle page validation and potentially cancel the event.

[toddparker]

@deAtog - If you have suggestions on how to improve the docs for this, please send us a PR. We have a ticket to improve this part of the docs.

[jaspermdegroot]

Opened a ticket for this at the API documentation repo: jquery/api.jquerymobile.com#96

Closing it here.