feat(ngRoute): allow cancelling $route updates via $routeChangeEvent

Previously, one could perform this feat by listening to both
$locationChangeStart as well as $routeChangeStart, and being careful to update
the route correctly. Now, it's possible to simply preventDefault() on the
$beforeRouteChange event in order to prevent location and route from being
updated.

While this does not cancel $routeChangeStart, it does ensure that the correct
location is restored, and provides the same information as $routeChangeStart.

Closes angular#5855
Closes angular#5714
Closes angular#5581

Author: caitp

src/ngRoute/route.js

@@ -364,6 +364,21 @@ function $RouteProvider(){
      * </example>
      */
 
+    /**
+     * @ngdoc event
+     * @name $route#$beforeRouteChange
+     * @eventType broadcast on root scope
+     *
+     * @description
+     * Broadcasted during locationChangeStart, will cancel $locationChangeStart
+     * if preventDefault() is called, thus preventing subsequent $routeChange
+     * events.
+     *
+     * @param {Object} angularEvent Synthetic event object.
+     * @param {Route}  nextRoute route information of the future route.
+     * @param {Route} currentRoute current route information.
+     */
+
     /**
      * @ngdoc event
      * @name $route#$routeChangeStart
@@ -469,6 +484,7 @@ function $RouteProvider(){
           }
         };
 
+    $rootScope.$on('$locationChangeStart', beforeUpdateRoute);
     $rootScope.$on('$locationChangeSuccess', updateRoute);
 
     return $route;
@@ -582,6 +598,18 @@ function $RouteProvider(){
     }
 
 
+    // $locationChangeStart handler. Dispatches $beforeRouteChange, and cancels $locationChangeStart
+    // if the user cancels the $beforeRouteChange event.
+    function beforeUpdateRoute(event, next, current) {
+      var nextRoute = parseRoute();
+      var lastRoute = $route.current;
+
+      if ($rootScope.$broadcast('$beforeRouteChange', nextRoute, lastRoute).defaultPrevented) {
+        event.preventDefault();
+      }
+    }
+
+
     /**
      * @returns {Object} the current active route, by matching it against the URL
      */

test/ngRoute/routeSpec.js

@@ -741,6 +741,65 @@ describe('$route', function() {
         expect($exceptionHandler.errors).toEqual([myError]);
       });
     });
+
+
+    it('should pass nextRoute and currentRoute to $beforeRouteChange', function() {
+      module(function($routeProvider) {
+        $routeProvider.when('/a', {
+          template: '<p>route A</p>'
+        }).when('/b', {
+          template: '<p>route B</p>'
+        });
+      });
+
+      inject(function($location, $route, $rootScope) {
+        var beforeRouteChangeCalled = false;
+        $location.path('/a');
+        $rootScope.$digest();
+
+        $rootScope.$on('$beforeRouteChange', function(event, nextRoute, currentRoute) {
+          beforeRouteChangeCalled = true;
+          expect(nextRoute.template).toBe('<p>route B</p>');
+          expect(currentRoute.template).toBe('<p>route A</p>');
+        });
+
+        $location.path('/b');
+        $rootScope.$digest();
+
+        expect(beforeRouteChangeCalled).toBe(true);
+      });
+    });
+
+
+    it('should cancel $locationChange when $beforeRouteChange is cancelled', function() {
+      module(function($routeProvider) {
+        $routeProvider.when('/a', {
+          template: '<p>route A</p>'
+        }).when('/b', {
+          template: '<p>route B</p>'
+        });
+      });
+
+      inject(function($location, $route, $rootScope) {
+        var didChangeLocation = false;
+        $location.path('/a');
+        $rootScope.$digest();
+
+        $rootScope.$on('$beforeRouteChange', function(event, nextRoute, currentRoute) {
+          event.preventDefault();
+        });
+        $rootScope.$on('$locationChangeSuccess', function() {
+          didChangeLocation = true;
+        });
+
+        $location.path('/b');
+        $rootScope.$digest();
+
+        expect(didChangeLocation).toBe(false);
+        expect($location.path()).toBe('/a');
+        expect($route.current.template).toBe('<p>route A</p>');
+      });
+    });
   });