feat(Modal): Add a vetoable modal.closing event

Add tests

Includes tests, refinements to the documentation and a fix for an
inconsistent variable name.

Fix test bug

Author: Nathan Williams

Diff for: src/modal/docs/readme.md

@@ -30,3 +30,8 @@ In addition the scope associated with modal's content is augmented with 2 method
 * `$dismiss(reason)`
 
 Those methods make it easy to close a modal window without a need to create a dedicated controller.
+
+Finally, a `modal.closing` event is broadcast to the modal scope before the modal closes.  If the listener calls 
+preventDefault on the event, then the modal will remain open.  The $close and $dismiss methods return true if the 
+event was allowed.  The event itself includes a parameter for the result/reason and a boolean parameter that indicates
+whether the modal is being closed (true) or dismissed.

Diff for: src/modal/modal.js

@@ -290,26 +290,33 @@ angular.module('ui.bootstrap.modal', ['ui.bootstrap.transition'])
         body.addClass(OPENED_MODAL_CLASS);
       };
 
+      function broadcastClosing(modalWindow, resultOrReason, closing) {
+          return !modalWindow.value.modalScope.$broadcast('modal.closing', resultOrReason, closing).defaultPrevented;
+      }
+
       $modalStack.close = function (modalInstance, result) {
         var modalWindow = openedWindows.get(modalInstance);
-        if (modalWindow) {
+        if (modalWindow && broadcastClosing(modalWindow, result, true)) {
           modalWindow.value.deferred.resolve(result);
           removeModalWindow(modalInstance);
+          return true;
         }
+        return !modalWindow;
       };
 
       $modalStack.dismiss = function (modalInstance, reason) {
         var modalWindow = openedWindows.get(modalInstance);
-        if (modalWindow) {
+        if (modalWindow && broadcastClosing(modalWindow, reason, false)) {
           modalWindow.value.deferred.reject(reason);
           removeModalWindow(modalInstance);
+          return true;
         }
+        return !modalWindow;
       };
 
       $modalStack.dismissAll = function (reason) {
         var topModal = this.getTop();
-        while (topModal) {
-          this.dismiss(topModal.key, reason);
+        while (topModal && this.dismiss(topModal.key, reason)) {
           topModal = this.getTop();
         }
       };
@@ -370,10 +377,10 @@ angular.module('ui.bootstrap.modal', ['ui.bootstrap.transition'])
               opened: modalOpenedDeferred.promise,
               rendered: modalRenderDeferred.promise,
               close: function (result) {
-                $modalStack.close(modalInstance, result);
+                return $modalStack.close(modalInstance, result);
               },
               dismiss: function (reason) {
-                $modalStack.dismiss(modalInstance, reason);
+                return $modalStack.dismiss(modalInstance, reason);
               }
             };
 

Diff for: src/modal/test/modal.spec.js

@@ -107,15 +107,17 @@ describe('$modal', function () {
   }
 
   function close(modal, result) {
-    modal.close(result);
+    var closed = modal.close(result);
     $timeout.flush();
     $rootScope.$digest();
+    return closed;
   }
 
   function dismiss(modal, reason) {
-    modal.dismiss(reason);
+    var closed = modal.dismiss(reason);
     $timeout.flush();
     $rootScope.$digest();
+    return closed;
   }
 
   describe('basic scenarios with default options', function () {
@@ -607,4 +609,70 @@ describe('$modal', function () {
       expect(body).not.toHaveClass('modal-open');
     });
   });
+
+  describe('modal.closing event', function() {
+    it('should close the modal contingent on the modal.closing event and return whether the modal closed', function() {
+      var preventDefault;
+      var modal;
+      var template = '<div>content</div>';
+
+      function TestCtrl($scope) {
+        $scope.$on('modal.closing', function (event, resultOrReason, closing) {
+          if (preventDefault) {
+            event.preventDefault();
+          }
+        });
+      }
+
+      modal = open({template: template, controller: TestCtrl});
+
+      preventDefault = true;
+      expect(close(modal, 'result')).toBeFalsy();
+      expect($document).toHaveModalsOpen(1);
+
+      preventDefault = false;
+      expect(close(modal, 'result')).toBeTruthy();
+      expect($document).toHaveModalsOpen(0);
+
+      modal = open({template: template, controller: TestCtrl});
+
+      preventDefault = true;
+      expect(dismiss(modal, 'result')).toBeFalsy();
+      expect($document).toHaveModalsOpen(1);
+
+      preventDefault = false;
+      expect(dismiss(modal, 'result')).toBeTruthy();
+      expect($document).toHaveModalsOpen(0);
+    });
+
+    it('should trigger modal.closing and pass result/reason and closing parameters to the event', function() {
+      var called;
+
+      called = false;
+      close(open({
+        template: '<div>content</div>',
+        controller: function($scope) {
+          $scope.$on('modal.closing', function(event, resultOrReason, closing) {
+            called = true;
+            expect(resultOrReason).toBe('result');
+            expect(closing).toBeTruthy();
+          });
+        }
+      }), 'result');
+      expect(called).toBeTruthy();
+
+      called = false;
+      dismiss(open({
+        template: '<div>content</div>',
+        controller: function($scope) {
+          $scope.$on('modal.closing', function(event, resultOrReason, closing) {
+            called = true;
+            expect(resultOrReason).toBe('reason');
+            expect(closing).toBeFalsy();
+          });
+        }
+      }), 'reason');
+      expect(called).toBeTruthy();
+    });
+  });
 });