Kick Backs - WP8 back button handling.

With the PhoneGap Windows Phone Porting Challenge well under way, I felt it would be a good time to take a deeper dive into the hardware back button mechanism that is implemented in Apache Cordova, and how to use it.

“A frequent cause of failing app certification is due to an inappropriate implementation of the back button behavior. ... Developers often forget to verify that their apps works accordingly, especially when porting from other platforms which have different behavior/hardware buttons."

 

- Jean-Christophe Cimetiere, @jccim

Developer Product Marketing, Windows Phone, Microsoft

The default behavior

Out of the box, Apache Cordova for Windows Phone 8 attempts to behave like a typical browser history back button.  If you have implemented multiple pages within your app, and navigated through them, then Cordova library will call window.history.back() automagically for you.  If the page indeed changes because of this action, then the event is cancelled and the WP8 OS does not do anything in response to the button.  If however the page does not change, then the event is not cancelled, and the WP8 OS takes over and performs its default action of exiting your app.  This allows applications built with jQuery Mobile and the like, to function without alteration.

 Providing your own handler

If you would like to override the default behavior of the backbutton in your app, you simply need to add an event listener to the document. Ideally you would do this after the deviceready event has fired, like this :

    document.addEventListener('deviceready',function(){
        document.addEventListener('backbutton',handleBackButton);
    });

    function handleBackButton() {
        // do something other than the default, like undo an operation, 
        // or step backwards through a multi-step operation
    }

The above code will effectively disable the back button.  In order to re-enable it, simply call removeEventListener :

    document.removeEventListener('backbutton',handleBackButton);

It is worth noting that you are responsible for keeping track of your handlers. If you are using inline functions, it will be difficult for you to remove them. You have been warned.

When the document does not contain any backbutton event handlers, it will perform the default behavior,  which is usually exiting your app.

More reading

You can read a bit more about PhoneGap back button handling and everything else at docs.phonegap.com.

http://docs.phonegap.com/en/2.7.0/cordova_events_events.md.html#backbutton

For more details on all Windows Phone Certification and the proper use of the back button, view Microsoft's technical certification requirements

I am excited to see apps get ported for the PhoneGap Windows Phone Porting Challenge If you have issues along the way, I am actively monitoring the phonegap mailing list and I look forward to helping you out if you need it.

As always, I welcome your comments, and questions here, and on twitter. Jesse aka @purplecabbage