In the previous example we've seen how to animate AngularJS built-in directives and now we're going to see which tools AngularJS offers us to animate our own directives or simply to animate some HTML elements. This can be done with the $animate service.
Before moving on, remember that if you want to see all the methods made available by the $animate service, you can check the official documentation. In the same page you'll see for each method the exact sequence of CSS classes that are applied to the target HTML element during the animation. Remember also that starting with AngularJS 1.3 all the methods return a promise to know when the animation is complete, while in previous AngularJS versions a callback was used for the same purpose. Here we're going to focus on version 1.3 so we're going to use promises taking advantage of all the flexibility they offer.
Let's start by taking a look at point 1 of the example. Here we see how to use the enter and leave methods of the $animate service. The enter method adds an element to the DOM and executes the corresponding enter animation. This means that we must define our own CSS transitions or keyframe animations for the ng-enter class like we've seen in our previous example about animated directives. In our HTML page we've got a div element with ID box1Parent and we use the enter method to add another div (with ID box1) inside box1Parent or as its sibling. When box1 is added we can see the enter animation. We use the promise returned by the enter method to know when the animation is complete and we update the enterAnimationStateBox1 variable to display the animation state during its progress. As you can see, inside the callback of the promise we must use $scope.$apply because the code inside the callback would be outside the AngularJS life-cycle otherwise. The use of the leave method is very similar. In this case the CSS transitions or keyframe animations must be defined for the ng-leave class and we use the method to remove the box1 we've previously added.
In point 2 of the example we see how to use the move method. Here we have three boxes and each time we invoke the move method we want them to shift by one position. moveLeftmostElement is just a placeholder because we need to tell move to move an element after another one so here's the description of the first move sequence:
- $animate.move(greenBox, null, moveLeftmostElement): move greenBox after moveLeftmostElement;
- $animate.move(blueBox, null, greenBox): move blueBox after greenBox;
- $animate.move(redBox, null, blueBox): move redBox after blueBox.
Since we've defined a staggering animation for the move event, each move animation starts a short time after the previous one thus giving the staggering effect. Remember that we've talked about the staggering animations in the example about animated directives. We use the $q service to wait for all the animation promises to end and notice that in this case we don't need to use $scope.$apply inside the then method callback for the promise returned by $q. That would be needed if we were using directly the promises returned by the move method like it happens with any other animation method of the $animate service.
In point 3 of the example we simply see how we can add and remove a class and animate the target HTML element. We use three methods of the $animate service: addClass, removeClass and setClass. There's nothing special in the first two methods, while the third one (setClass) allows us to add and remove CSS classes at the same time and as you can see, the animations for both the add and remove events run in parallel.
Point 4 shows the use of the animate method and how we can cancel a running animation with the cancel method. You should follow this description while looking also at the official documentation of the animate method. Here we have a long animation made of three successive steps:
- The animation is on the opacity property that we've specified directly inline in the animate method and we make it go from 0 to 1 (this means that at the beginning of the animation, the style attribute of the animated HTML element will contain the value opacity: 0; while at the end of the animation it will contain the value opacity: 1; and that inline style will stay there even after the animation ends, it will not be removed). The CSS transition is defined in the custom-inline-animation-1 class. During the animation, the box-border class is added to the animated element and is removed at the end of the animation. This last functionality is not documented and, as you've probably seen in the official documentation, for most of the animation methods there's an options parameter. In the version of AngularJS used for this example, that parameter is an object that accepts an array of class names in its tempClasses property with the classes that have to be added to the animated element while the animation is running. Since all of this is not documented and I've found it with a close inspection of AngularJS source code, you should not rely on it for the future, it has been presented here just to let you know what that mysterious options parameter is for.
- The animation is completely defined in the CSS. Since we call the animate method just with the target HTML element, we don't specify any inline style to animate and we use the default ng-inline-animate class of the method to specify our CSS animation.
- This step is a mix of step 1 and 2, so we've both specified inline styles to apply at the beginning and the end of the animation and a custom-inline-animation-2 class to define a CSS keyframe animation. In this case both the inline styles and the CSS animation will be applied and at the end of the animation the style attribute of the animated HTML element will contain the value opacity: 0;. Inside the promise callback for the end of the animation step 3 we remove the style attribute completely from the HTML element to restore its state as it was before animation step 1 started.
Each time an animation step starts, we keep track of the current animation promise in the currLongAnimationPromise variable. If we want to cancel a running animation, all we have to do is call the $animate.cancel method with the corresponding promise as argument. Each time you cancel an animation step in the example, the corresponding promise is immediately resolved and the corresponding callback is called as if the animation ended normally and the next animation step starts.
Point 5 of the example shows how we can easily completely disable animations or enable them again. To do this, we just need to call the $animate.enabled method. If you disable the animations, you can try any animation in the example and you'll see that they all reach their final state immediately instead of going through a progression.
In point 6 we finally make our own animated directive. We create the elementGlow directive that applies a glow effect to an element. This directive accepts as input the name of a scope variable that tells if the glow should be made visible or not. In this case, the enableGlow variable set by a checkbox makes the glow visible or invisible. Inside the directive we keep track of the value changes of the variable with the scope.$watch method, we use the $animate.animate method to animate the target HTML element and we've defined the CSS transition in the element-glow-animation class. It's very important to notice that we also handle the $destroy event for the HTML element to which the directive is applied because we need to unwatch the variable in case the element is removed from the DOM, otherwise the $watch handler would be fired every time the enableGlow changes even though the HTML element is not on the DOM anymore! We use the element.one method because the handler needs to be fired just once for the $destroy event and detached from the element immediately after its execution. Handling the $destroy event is a good habit for any of your custom directives in case you need to watch some variables defined outside the directives.
NOTE: due to a bug in Firefox, inline animations (that we have when we use the $animate.animate method) with CSS keyframes don't work and this is the case of point 4 in this example, so that point is not going to work properly on Firefox (see https://bugzilla.mozilla.org/show_bug.cgi?id=830056 for this bug).