feat($location): add support for History API state handling

Adds $location state method allowing to get/set a History API state via
pushState & replaceState methods.

Note that:
- Angular treats states undefined and null as the same; trying to change
one to the other without touching the URL won't do anything. This is necessary
to prevent infinite digest loops when setting the URL to itself in IE<10 in
the HTML5 hash fallback mode.
- The state() method is not compatible with browsers not supporting
the HTML5 History API, e.g. IE 9 or Android < 4.0.

Closes angular#9027

Author: mgol

docs/content/error/$location/nostate.ngdoc

@@ -0,0 +1,8 @@
+@ngdoc error
+@name $location:nostate
+@fullName History API state support is available only in HTML5 mode and only in browsers supporting HTML5 History API
+@description
+
+This error occurs when the {@link ng.$location#state $location.state} method is used when {@link ng.$locationProvider#html5Mode $locationProvider.html5Mode} is not turned on or the browser used doesn't support the HTML5 History API (for example, IE9 or Android 2.3).
+
+To avoid this error, either drop support for those older browsers or avoid using this method.

src/ng/browser.js

@@ -124,6 +124,7 @@ function Browser(window, document, $log, $sniffer) {
   //////////////////////////////////////////////////////////////
 
   var lastBrowserUrl = location.href,
+      lastHistoryState = history.state,
       baseElement = document.find('base'),
       newLocation = null;
 
@@ -144,27 +145,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
    */
-  self.url = function(url, replace) {
+  self.url = function(url, replace, state) {
     // 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;
+      // Prevent IE<10 from getting into redirect loop when in LocationHashbangInHtml5Url mode.
+      // See https://github.com/angular/angular.js/commit/ffb2701
+      if (lastBrowserUrl === url && history.state == null && state == null) return;
+      if (isUndefined(state)) {
+        state = null;
+      }
       var sameBase = lastBrowserUrl && stripHash(lastBrowserUrl) === stripHash(url);
       lastBrowserUrl = url;
       // Don't use history API if only the hash changed
       // due to a bug in IE10/IE11 which leads
       // to not firing a `hashchange` nor `popstate` event
       // in some cases (see #9143).
-      if (!sameBase && $sniffer.history) {
-        if (replace) history.replaceState(null, '', url);
-        else {
-          history.pushState(null, '', url);
-        }
+      if ($sniffer.history && (!sameBase || state !== null)) {
+        history[replace ? 'replaceState' : 'pushState'](state, '', url);
+        lastHistoryState = history.state;
       } else {
         newLocation = url;
         if (replace) {
@@ -183,6 +188,20 @@ function Browser(window, document, $log, $sniffer) {
     }
   };
 
+  /**
+   * @name $browser#state
+   *
+   * @description
+   * This method is a getter.
+   *
+   * Return history.state.
+   *
+   * @returns {object} state
+   */
+  self.state = function() {
+    return history.state;
+  };
+
   var urlChangeListeners = [],
       urlChangeInit = false;
 
@@ -192,11 +211,13 @@ function Browser(window, document, $log, $sniffer) {
   }
 
   function checkUrlChange() {
-    if (lastBrowserUrl == self.url()) return;
+    if (lastBrowserUrl === self.url() && lastHistoryState === history.state) {
+      return;
+    }
 
     lastBrowserUrl = self.url();
     forEach(urlChangeListeners, function(listener) {
-      listener(self.url());
+      listener(self.url(), history.state);
     });
   }
 

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,43 @@ LocationHashbangInHtml5Url.prototype =
   }
 };
 
+forEach([LocationHashbangInHtml5Url, LocationHashbangUrl, LocationHtml5Url], function (Location) {
+  Location.prototype = Object.create(locationPrototype);
+
+  /**
+   * @ngdoc method
+   * @name $location#state
+   *
+   * @description
+   * This method is getter / setter.
+   *
+   * Return the history state object when called without any parameter.
+   *
+   * Change the history state object when called with one parameter and return `$location`.
+   * The state object is later passed to `pushState` or `replaceState`.
+   *
+   * NOTE: This method is supported only in HTML5 mode and only in browsers supporting
+   * the HTML5 History API (i.e. methods `pushState` and `replaceState`). If you need to support
+   * older browsers (like IE9 or Android < 4.0), don't use this method.
+   *
+   * @param {object=} state State object for pushState or replaceState
+   * @return {object} state
+   */
+  Location.prototype.state = function(state) {
+    if (!arguments.length)
+      return this.$$state;
+
+    if (Location !== LocationHtml5Url || !this.$$html5) {
+      throw $locationMinErr('nostate', 'History API state support is available only ' +
+        'in HTML5 mode and only in browsers supporting HTML5 History API');
+    }
+    this.$$state = copy(state);
+
+    return this;
+  };
+});
+
+
 function locationGetter(property) {
   return function() {
     return this[property];
@@ -649,9 +684,14 @@ function $LocationProvider(){
    * details about event object. Upon successful change
    * {@link ng.$location#events_$locationChangeSuccess $locationChangeSuccess} is fired.
    *
+   * The `newState` and `oldState` parameters may be defined only in HTML5 mode and when
+   * the browser supports the HTML5 History API.
+   *
    * @param {Object} angularEvent Synthetic event object.
    * @param {string} newUrl New URL
    * @param {string=} oldUrl URL that was before it was changed.
+   * @param {string=} newState New history state object
+   * @param {string=} oldState History state object that was before it was changed.
    */
 
   /**
@@ -661,9 +701,14 @@ function $LocationProvider(){
    * @description
    * Broadcasted after a URL was changed.
    *
+   * The `newState` and `oldState` parameters may be defined only in HTML5 mode and when
+   * the browser supports the HTML5 History API.
+   *
    * @param {Object} angularEvent Synthetic event object.
    * @param {string} newUrl New URL
    * @param {string=} oldUrl URL that was before it was changed.
+   * @param {string=} newState New history state object
+   * @param {string=} oldState History state object that was before it was changed.
    */
 
   this.$get = ['$rootScope', '$browser', '$sniffer', '$rootElement',
@@ -687,6 +732,7 @@ function $LocationProvider(){
     }
     $location = new LocationMode(appBase, '#' + hashPrefix);
     $location.$$parseLinkUrl(initialUrl, initialUrl);
+    $location.$$state = $browser.state();
 
     var IGNORE_URI_REGEXP = /^\s*(javascript|mailto):/i;
 
@@ -741,18 +787,22 @@ function $LocationProvider(){
     }
 
     // update $location when $browser url changes
-    $browser.onUrlChange(function(newUrl) {
-      if ($location.absUrl() != newUrl) {
+    $browser.onUrlChange(function(newUrl, newState) {
+      if ($location.absUrl() !== newUrl ||
+          ($location.$$html5 && $location.state() != newState && !equals($location.state(), newState))) {
         $rootScope.$evalAsync(function() {
           var oldUrl = $location.absUrl();
+          var oldState = $location.state();
 
           $location.$$parse(newUrl);
-          if ($rootScope.$broadcast('$locationChangeStart', newUrl,
-                                    oldUrl).defaultPrevented) {
+          $location.$$state = copy(newState);
+          if ($rootScope.$broadcast('$locationChangeStart', newUrl, oldUrl,
+              newState, oldState).defaultPrevented) {
             $location.$$parse(oldUrl);
-            $browser.url(oldUrl);
+            $location.$$state = oldState;
+            $browser.url($location.absUrl(), false, newState);
           } else {
-            afterLocationChange(oldUrl);
+            afterLocationChange(oldUrl, oldState);
           }
         });
         if (!$rootScope.$$phase) $rootScope.$digest();
@@ -763,17 +813,20 @@ function $LocationProvider(){
     var changeCounter = 0;
     $rootScope.$watch(function $locationWatch() {
       var oldUrl = $browser.url();
+      var oldState = $browser.state();
       var currentReplace = $location.$$replace;
 
-      if (!changeCounter || oldUrl != $location.absUrl()) {
+      if (!changeCounter || oldUrl !== $location.absUrl() ||
+          ($location.$$html5 && oldState != $location.state() && !equals(oldState, $location.state()))) {
         changeCounter++;
         $rootScope.$evalAsync(function() {
-          if ($rootScope.$broadcast('$locationChangeStart', $location.absUrl(), oldUrl).
-              defaultPrevented) {
+          if ($rootScope.$broadcast('$locationChangeStart', $location.absUrl(), oldUrl,
+            $location.state(), oldState).defaultPrevented) {
             $location.$$parse(oldUrl);
+            $location.$$state = oldState;
           } else {
-            $browser.url($location.absUrl(), currentReplace);
-            afterLocationChange(oldUrl);
+            $browser.url($location.absUrl(), currentReplace, $location.state());
+            afterLocationChange(oldUrl, oldState);
           }
         });
       }
@@ -784,8 +837,8 @@ function $LocationProvider(){
 
     return $location;
 
-    function afterLocationChange(oldUrl) {
-      $rootScope.$broadcast('$locationChangeSuccess', $location.absUrl(), oldUrl);
+    function afterLocationChange(oldUrl, oldState) {
+      $rootScope.$broadcast('$locationChangeSuccess', $location.absUrl(), oldUrl, $location.state(), oldState);
     }
 }];
 }

src/ngMock/angular-mocks.js

@@ -46,9 +46,10 @@ angular.mock.$Browser = function() {
   self.onUrlChange = function(listener) {
     self.pollFns.push(
       function() {
-        if (self.$$lastUrl != self.$$url) {
+        if (self.$$lastUrl != self.$$url || self.$$state != self.$$lastState) {
           self.$$lastUrl = self.$$url;
-          listener(self.$$url);
+          self.$$lastState = self.$$state;
+          listener(self.$$url, self.$$state);
         }
       }
     );
@@ -144,15 +145,20 @@ angular.mock.$Browser.prototype = {
     return pollFn;
   },
 
-  url: function(url, replace) {
+  url: function(url, replace, state) {
     if (url) {
       this.$$url = url;
+      this.$$state = state;
       return this;
     }
 
     return this.$$url;
   },
 
+  state: function() {
+    return this.$$state;
+  },
+
   cookies:  function(name, value) {
     if (name) {
       if (angular.isUndefined(value)) {