feat($animate): add support for customFilter

This commit adds a new `customFilter()` function on `$animateProvider` (similar to
`classNameFilter()`), which can be used to filter animations (i.e. decide whether thay are allowed
or not), based on the return value of a custom filter function.
This allows to easily create arbitrarily complex rules for filtering animations, such as allowing
specific events only, or enabling animations on specific subtrees of the DOM etc.

Fixes #14891

Author: gkalpak

src/ng/animate.js

@@ -169,6 +169,7 @@ var $$CoreAnimateQueueProvider = function() {
  */
 var $AnimateProvider = ['$provide', function($provide) {
   var provider = this;
+  var customFilter = null;
 
   this.$$registeredAnimations = Object.create(null);
 
@@ -249,6 +250,30 @@ var $AnimateProvider = ['$provide', function($provide) {
     return this.$$classNameFilter;
   };
 
+  /**
+   * @ngdoc method
+   * @name $animateProvider#customFilter
+   *
+   * @description
+   * TODO(gkalpak)
+   *
+   * @param {Function=} filterFn - The filter function which will be used to filter all animations.
+   *     If a falsy value is returned, no animation will be performed. The function will be called
+   *     with the followijg arguments:
+   *     - **node** `{DOMElement}` - The DOM element to be animated.
+   *     - **event** `{String}` - The name of the animation event (e.g. `enter`, `leave`, `addClass`
+   *       etc).
+   *     - **options** `{Object}` - An collection of options/styles used for the animation.
+   * @return {Function} The current filter function or `null` if there is none set.
+   */
+  this.customFilter = function(filterFn) {
+    if (arguments.length === 1) {
+      customFilter = isFunction(filterFn) ? filterFn : null;
+    }
+
+    return customFilter;
+  };
+
   this.$get = ['$$animateQueue', function($$animateQueue) {
     function domInsert(element, parentElement, afterElement) {
       // if for some reason the previous element was removed

src/ngAnimate/animateQueue.js

@@ -168,6 +168,7 @@ var $$AnimateQueueProvider = ['$animateProvider', function($animateProvider) {
               : function(className) {
                 return classNameFilter.test(className);
               };
+    var isAnimatableByFilter = $animateProvider.customFilter() || function() { return true; };
 
     var applyAnimationClasses = applyAnimationClassesFactory($$jqLite);
 
@@ -361,7 +362,7 @@ var $$AnimateQueueProvider = ['$animateProvider', function($animateProvider) {
       }
 
       var className = [node.getAttribute('class'), options.addClass, options.removeClass].join(' ');
-      if (!isAnimatableClassName(className)) {
+      if (!isAnimatableClassName(className) || !isAnimatableByFilter(node, event, initialOptions)) {
         close();
         return runner;
       }

test/ngAnimate/animateSpec.js

@@ -292,6 +292,129 @@ describe("animations", function() {
       });
     });
 
+    describe('customFilter()', function() {
+      it('should clear the `customFilter` if no function is passed',
+        module(function($animateProvider) {
+          expect($animateProvider.customFilter()).toBeNull();
+
+          $animateProvider.customFilter(angular.noop);
+          expect($animateProvider.customFilter()).toEqual(jasmine.any(Function));
+
+          $animateProvider.customFilter({});
+          expect($animateProvider.customFilter()).toBeNull();
+        })
+      );
+
+      it('should animate only elements that pass through `$animateProvider.customFilter()`',
+        function() {
+          var animationsAllowed = false;
+
+          module(function($animateProvider) {
+            $animateProvider.customFilter(function() { return animationsAllowed; });
+          });
+
+          inject(function($animate, $rootScope) {
+            $animate.enter(element, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeFalsy();
+
+            $animate.leave(element, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeFalsy();
+
+            animationsAllowed = true;
+
+            $animate.enter(element, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeTruthy();
+
+            capturedAnimation = null;
+
+            $animate.leave(element, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeTruthy();
+          });
+        }
+      );
+
+      it('should animate only elements that pass through `$animateProvider.customFilter()`',
+        function() {
+          var animationsAllowed = false;
+
+          module(function($animateProvider) {
+            $animateProvider.customFilter(function() { return animationsAllowed; });
+          });
+
+          inject(function($animate, $compile, $rootScope) {
+            var svgElement = $compile('<svg class="element"></svg>')($rootScope);
+
+            $animate.enter(svgElement, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeFalsy();
+
+            $animate.leave(svgElement, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeFalsy();
+
+            animationsAllowed = true;
+
+            $animate.enter(svgElement, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeTruthy();
+
+            capturedAnimation = null;
+
+            $animate.leave(svgElement, parent);
+            $rootScope.$digest();
+            expect(capturedAnimation).toBeTruthy();
+          });
+        }
+      );
+
+      it('should pass the DOM element, event name and options to the filter function', function() {
+        var filterFn = jasmine.createSpy('filterFn');
+        var options = {};
+
+        module(function($animateProvider) {
+          $animateProvider.customFilter(filterFn);
+        });
+
+        inject(function($animate, $rootScope) {
+          $animate.enter(element, parent, null, options);
+          expect(filterFn).toHaveBeenCalledOnceWith(element[0], 'enter', options);
+
+          filterFn.calls.reset();
+
+          $animate.leave(element);
+          expect(filterFn).toHaveBeenCalledOnceWith(element[0], 'leave', jasmine.any(Object));
+        });
+      });
+
+      it('should complete the DOM operation even if filtered out', function() {
+        var filterFn = jasmine.createSpy('filterFn').and.returnValue(false);
+
+        module(function($animateProvider) {
+          $animateProvider.customFilter(filterFn);
+        });
+
+        inject(function($animate, $rootScope) {
+          expect(element.parent()[0]).toBeUndefined();
+
+          $animate.enter(element, parent);
+          $rootScope.$digest();
+
+          expect(capturedAnimation).toBeFalsy();
+          expect(element.parent()[0]).toBe(parent[0]);
+
+          $animate.leave(element);
+          $rootScope.$digest();
+
+          expect(capturedAnimation).toBeFalsy();
+          expect(element.parent()[0]).toBeUndefined();
+        });
+      });
+    });
+
     describe('enabled()', function() {
       it("should work for all animations", inject(function($animate) {