feat($location): add support for state and title in pushState

Adds $location pushState & replaceState methods acting as proxies to history
pushState & replaceState methods. This allows using pushState to change state
and title as well as URL. Note that these methods are not compatible with
browsers not supporting the HTML5 History API, e.g. IE 9.

Closes #9027

Author: mgol

src/ng/browser.js

@@ -123,6 +123,7 @@ function Browser(window, document, $log, $sniffer) {
   //////////////////////////////////////////////////////////////
 
   var lastBrowserUrl = location.href,
+      lastBrowserState = history.state,
       baseElement = document.find('base'),
       newLocation = null;
 
@@ -143,23 +144,31 @@ function Browser(window, document, $log, $sniffer) {
    * {@link ng.$location $location service} to change url.
    *
    * @param {string} url New url (when used as setter)
-   * @param {boolean=} replace Should new url replace current history record ?
+   * @param {boolean=} replace Should new url replace current history record?
+   * @param {object=} state object to use with pushState/replaceState
+   * @param {string=} title to use with pushState/replaceState
    */
-  self.url = function(url, replace) {
+  self.url = function(url, replace, state, title) {
     // Android Browser BFCache causes location, history reference to become stale.
     if (location !== window.location) location = window.location;
     if (history !== window.history) history = window.history;
 
     // setter
     if (url) {
-      if (lastBrowserUrl == url) return;
+      if (lastBrowserUrl == url && (!$sniffer.history || equals(lastBrowserState, state))) {
+        return;
+      }
       lastBrowserUrl = url;
+      lastBrowserState = copy(state);
       if ($sniffer.history) {
-        if (replace) history.replaceState(null, '', url);
-        else {
-          history.pushState(null, '', url);
-          // Crazy Opera Bug: http://my.opera.com/community/forums/topic.dml?id=1185462
-          baseElement.attr('href', baseElement.attr('href'));
+        title = title || '';
+        state = state || null;
+        try {
+          history[replace ? 'replaceState' : 'pushState'](state, title, url);
+        } catch (e) {
+          throw minErr('$browser')('pstterr', 'pushState or replaceState failed; ' +
+            'most likely the passed state object is too complex',
+            e.stack || e.message || e);
         }
       } else {
         newLocation = url;
@@ -188,7 +197,7 @@ function Browser(window, document, $log, $sniffer) {
 
     lastBrowserUrl = self.url();
     forEach(urlChangeListeners, function(listener) {
-      listener(self.url());
+      listener(self.url(), history.state, rawDocument.title);
     });
   }
 

src/ng/location.js

@@ -303,9 +303,7 @@ function LocationHashbangInHtml5Url(appBase, hashPrefix) {
 }
 
 
-LocationHashbangInHtml5Url.prototype =
-  LocationHashbangUrl.prototype =
-  LocationHtml5Url.prototype = {
+var locationPrototype = {
 
   /**
    * Are we in html5 mode?
@@ -314,7 +312,7 @@ LocationHashbangInHtml5Url.prototype =
   $$html5: false,
 
   /**
-   * Has any change been replacing ?
+   * Has any change been replacing?
    * @private
    */
   $$replace: false,
@@ -530,6 +528,100 @@ LocationHashbangInHtml5Url.prototype =
   }
 };
 
+forEach([LocationHashbangInHtml5Url, LocationHashbangUrl, LocationHtml5Url], function (Location) {
+  extend(Location.prototype = {}, locationPrototype);
+});
+
+/**
+ * @name $location#$$state
+ *
+ * Current History API state.
+ * @private
+ */
+LocationHtml5Url.prototype.$$state = null;
+
+/**
+ * @name $location#$$title
+ *
+ * Current History API title.
+ * @private
+ */
+LocationHtml5Url.prototype.$$title = '';
+
+/**
+ * @ngdoc method
+ * @name $location#state.
+ *
+ * @description
+ * Return current history state.
+ *
+ * NOTE: this method is available only in HTML5 mode and only in browsers supporting
+ * HTML5 History API. If you need to support older browsers (like IE9), don't use this
+ * method!
+ *
+ * @return {object} state
+ */
+LocationHtml5Url.prototype.state = function() {
+  return this.$$state;
+};
+
+/**
+ * @ngdoc method
+ * @name $location#pushState
+ *
+ * @description
+ * Invokes history.pushState. Changes url, state and title.
+ *
+ * NOTE: this method is available only in HTML5 mode and only in browsers supporting
+ * HTML5 History API. If you need to support older browsers (like IE9), don't use this
+ * method!
+ *
+ * @param {object=} state object for pushState
+ * @param {string=} title for pushState (ignored by most browsers)
+ * @param {string=} url New url without base prefix (e.g. `/path?a=b#hash`)
+ * @return {object} $location
+ */
+LocationHtml5Url.prototype.pushState = function(state, title, url, replace) {
+  this.$$state = copy(state);
+  this.$$title = title;
+  this.$$replace = replace;
+  this.url(url, replace);
+  return this;
+};
+
+/**
+ * @ngdoc method
+ * @name $location#replaceState.
+ *
+ * @description
+ * Invokes history.replaceState. Changes url, state and title.
+ *
+ * NOTE: this method is available only in HTML5 mode and only in browsers supporting
+ * HTML5 History API. If you need to support older browsers (like IE9), don't use this
+ * method!
+ *
+ * @param {object=} state object for replaceState
+ * @param {string=} title for replaceState (ignored by most browsers)
+ * @param {string=} url New url without base prefix (e.g. `/path?a=b#hash`)
+ * @return {object} $location
+ */
+LocationHtml5Url.prototype.replaceState = function(state, title, url) {
+  this.pushState(state, title, url, true);
+  return this;
+};
+
+
+LocationHashbangInHtml5Url.prototype.state =
+  LocationHashbangInHtml5Url.prototype.pushState =
+  LocationHashbangInHtml5Url.prototype.replaceState =
+  LocationHashbangUrl.prototype.state =
+  LocationHashbangUrl.prototype.pushState =
+  LocationHashbangUrl.prototype.replaceState = function() {
+  throw $locationMinErr('psthtml4', 'History API state-related methods are available only ' +
+    'in HTML5 mode and only in browsers supporting HTML5 History API');
+};
+
+
 function locationGetter(property) {
   return function() {
     return this[property];
@@ -717,7 +809,7 @@ function $LocationProvider(){
     }
 
     // update $location when $browser url changes
-    $browser.onUrlChange(function(newUrl) {
+    $browser.onUrlChange(function(newUrl, state, title) {
       if ($location.absUrl() != newUrl) {
         $rootScope.$evalAsync(function() {
           var oldUrl = $location.absUrl();
@@ -726,9 +818,9 @@ function $LocationProvider(){
           if ($rootScope.$broadcast('$locationChangeStart', newUrl,
                                     oldUrl).defaultPrevented) {
             $location.$$parse(oldUrl);
-            $browser.url(oldUrl);
+            $browser.url($location.absUrl(), false, state, title);
           } else {
-            afterLocationChange(oldUrl);
+            afterLocationChange(oldUrl, state, title);
           }
         });
         if (!$rootScope.$$phase) $rootScope.$digest();
@@ -740,28 +832,32 @@ function $LocationProvider(){
     $rootScope.$watch(function $locationWatch() {
       var oldUrl = $browser.url();
       var currentReplace = $location.$$replace;
+      var currentState = $location.$$state;
+      var currentTitle = $location.$$title;
 
       if (!changeCounter || oldUrl != $location.absUrl()) {
         changeCounter++;
         $rootScope.$evalAsync(function() {
-          if ($rootScope.$broadcast('$locationChangeStart', $location.absUrl(), oldUrl).
+          if ($rootScope.$broadcast('$locationChangeStart', $location.absUrl(), oldUrl, currentState, currentTitle).
               defaultPrevented) {
             $location.$$parse(oldUrl);
           } else {
-            $browser.url($location.absUrl(), currentReplace);
-            afterLocationChange(oldUrl);
+            $browser.url($location.absUrl(), currentReplace, currentState, currentTitle);
+            afterLocationChange(oldUrl, currentState, currentTitle);
           }
         });
       }
       $location.$$replace = false;
+      delete $location.$$state;
+      delete $location.$$title;
 
       return changeCounter;
     });
 
     return $location;
 
-    function afterLocationChange(oldUrl) {
-      $rootScope.$broadcast('$locationChangeSuccess', $location.absUrl(), oldUrl);
+    function afterLocationChange(oldUrl, state, title) {
+      $rootScope.$broadcast('$locationChangeSuccess', $location.absUrl(), oldUrl, state, title);
     }
 }];
 }

src/ngMock/angular-mocks.js

@@ -144,9 +144,11 @@ angular.mock.$Browser.prototype = {
     return pollFn;
   },
 
-  url: function(url, replace) {
+  url: function(url, replace, state, title) {
     if (url) {
       this.$$url = url;
+      this.$$state = state;
+      this.$$title = title;
       return this;
     }