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 filtering animations, such as allowing
specific events only, or enabling animations on specific subtrees of the DOM.

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) {