bstract backward movement in history, Fixes #4950

`window.history.back` doesn't work in phonegap applications
after a page refresh, though it does work under hashchange/replacestate.
The solution is to use their `navigator.app.backHistory` method
along with a configuration option. The reasoning for the option
is to prevent any corner cases popping up with existing phonegap
applications. Forward history movement for the same usecase is _not_
addressed but remains an even lower priority.

Author: johnbender

js/jquery.mobile.dialog.js

@@ -25,7 +25,7 @@ $.widget( "mobile.dialog", $.mobile.widget, {
 				});
 
 		$el.addClass( "ui-dialog ui-overlay-" + this.options.overlayTheme );
-		
+
 		// Class the markup for dialog styling
 		// Set aria role
 		$el
@@ -88,9 +88,8 @@ $.widget( "mobile.dialog", $.mobile.widget, {
 		if ( !this._isClosed ) {
 			this._isClosed = true;
 			if ( $.mobile.hashListeningEnabled ) {
-				window.history.back();
-			}
-			else {
+				$.mobile.back();
+			} else {
 				dst = $.mobile.urlHistory.getPrev().url;
 				if ( !$.mobile.path.isPath( dst ) ) {
 					dst = $.mobile.path.makeUrlAbsolute( "#" + dst );

js/jquery.mobile.forms.select.custom.js

@@ -321,7 +321,7 @@ define( [
 					// doesn't solve the possible issue with calling change page
 					// where the objects don't define data urls which prevents dialog key
 					// stripping - changePage has incoming refactor
-					window.history.back();
+					$.mobile.back();
 				} else {
 					self.screen.addClass( "ui-screen-hidden" );
 					self.listbox.addClass( "ui-selectmenu-hidden" ).removeAttr( "style" ).removeClass( "in" );

js/jquery.mobile.navigation.js

@@ -410,10 +410,27 @@ define( [
 
 		} : undefined;
 
-/*
-	internal utility functions
---------------------------------------*/
-
+	/* internal utility functions */
+
+	// NOTE Issue #4950 Android phonegap doesn't navigate back properly
+	//      when a full page refresh has taken place. It appears that hashchange
+	//      and replacestate history alterations work fine but we need to support
+	//      both forms of history traversal in our code that uses backward history
+	//      movement
+	$.mobile.back = function() {
+		var nav = window.navigator;
+
+		// if the setting is on and the navigator object is
+		// available use the phonegap navigation capability
+		if( this.phonegapNavigationEnabled &&
+			nav &&
+			nav.app &&
+			nav.app.backHistory ){
+			nav.app.backHistory();
+		} else {
+			window.history.back();
+		}
+	};
 
 	//direct focus to the page title, or otherwise first focusable element
 	$.mobile.focusPage = function ( page ) {
@@ -1319,8 +1336,8 @@ define( [
 			};
 
 			//if there's a data-rel=back attr, go back in history
-			if( $link.is( ":jqmData(rel='back')" ) ) {
-				window.history.back();
+			if ( $link.is( ":jqmData(rel='back')" ) ) {
+				$.mobile.back();
 				return false;
 			}
 
@@ -1445,7 +1462,7 @@ define( [
 					//the current dialog
 					urlHistory.directHashChange({
 						currentUrl: to,
-						isBack: function() { window.history.back(); },
+						isBack: function() { $.mobile.back(); },
 						isForward: function() { window.history.forward(); }
 					});
 

js/jquery.mobile.navigation.pushstate.js

@@ -95,7 +95,7 @@ define( [ "jquery", "./jquery.mobile.navigation", "../external/requirejs/depend!
 			// Note that in some cases we might be replacing an url with the
 			// same url. We do this anyways because we need to make sure that
 			// all of our history entries have a state object associated with
-			// them. This allows us to work around the case where window.history.back()
+			// them. This allows us to work around the case where $.mobile.back()
 			// is called to transition from an external page to an embedded page.
 			// In that particular case, a hashchange event is *NOT* generated by the browser.
 			// Ensuring each history entry has a state object means that onPopState()

tests/unit/navigation/navigation_helpers.js

@@ -249,4 +249,22 @@
 
 		equal( $.mobile.path.getLocation( allUriParts ), allUriParts.replace( "jblas:password@", "") );
 	});
+
+	test( "calling mobile back uses phonegap's navigator object when present", function() {
+		var previous = $.mobile.phonegapNavigationEnabled;
+
+		expect( 1 );
+
+		$.mobile.phonegapNavigationEnabled = true;
+		window.navigator = {
+			app: {
+				backHistory: function() {
+					ok( true, "history back called" );
+				}
+			}
+		};
+
+		$.mobile.back();
+		$.mobile.phonegapNavigationEnabled = previous;
+	});
 })(jQuery);