docs(guide/animations): improve animations guide

1 files changed, 289 insertions, 0 deletions

diff --git a/docs/content/guide/animations.ngdoc b/docs/content/guide/animations.ngdoc
new file mode 100644
index 00000000..f3a2bcf0
--- /dev/null
+++ b/docs/content/guide/animations.ngdoc
@@ -0,0 +1,289 @@
+@ngdoc overview
+@name Developer Guide: Animations
+@description
+
+
+# Animations
+
+AngularJS 1.2 provides animation hooks for common directives such as `ngRepeat`, `ngSwitch`, and `ngView`, as well as custom directives
+via the `$animate` service. These animation hooks are set in place to trigger animations during the life cycle of various directives and when
+triggered, will attempt to perform a CSS Transition, CSS Keyframe Animation or a JavaScript callback Animation (depending on if an animation is
+placed on the given directive). Animations can be placed using vanilla CSS by following the naming conventions set in place by AngularJS
+or with JavaScript code when it's defined as a factory.
+
+Animations are not available unless you include the {@link api/ngAnimate `ngAnimate` module} as a dependency within your application.
+
+Below is a quick example of animations being enabled for `ngShow` and `ngHide`:
+
+<example animations="true">
+  <file name="index.html">
+    <div ng-init="checked=true">
+      <label>
+        <input type="checkbox" ng-model="checked" style="float:left; margin-right:10px;"> Is Visible...
+      </label>
+      <div class="check-element animate-show-hide" ng-show="checked" style="clear:both;">
+        Visible...
+      </div>
+    </div>
+  </file>
+  <file name="animations.css">
+    .animate-show-hide {
+      padding:10px;
+      border:1px solid black;
+      background:white;
+    }
+
+    .animate-show-hide.ng-hide-add, .animate-show-hide.ng-hide-remove {
+      -webkit-transition:all linear 0.5s;
+      -moz-transition:all linear 0.5s;
+      -o-transition:all linear 0.5s;
+      transition:all linear 0.5s;
+      display:block!important;
+    }
+
+    .animate-show-hide.ng-hide-add.ng-hide-add-active,
+    .animate-show-hide.ng-hide-remove {
+      opacity:0;
+    }
+
+    .animate-show-hide.ng-hide-add,
+    .animate-show-hide.ng-hide-remove.ng-hide-remove-active {
+      opacity:1;
+    }
+  </file>
+</example>
+
+## Installation
+
+See the {@link api/ngAnimate API docs for `ngAnimate`} for instructions on installing the module.
+
+You may also want to setup a separate CSS file for defining CSS-based animations.
+
+## How they work
+
+Animations in AngularJS are completely based on CSS classes. As long as you have a CSS class attached to a HTML element within
+your website, you can apply animations to it. Lets say for example that we have an HTML template with a repeater in it like so:
+
+<pre>
+<div ng-repeat="item in items" class="repeated-item">
+  {{ item.id }}
+</div>
+</pre>
+
+As you can see, the `.repeated-item` class is present on the element that will be repeated and this class will be
+used as a reference within our application's CSS and/or JavaScript animation code to tell AngularJS to perform an animation.
+
+As ngRepeat does its thing, each time a new item is added into the list, ngRepeat will add
+a `ng-enter` class name to the element that is being added. When removed it will apply a `ng-leave` class name and when moved around
+it will apply a `ng-move` class name.
+
+Taking a look at the following CSS code, we can see some transition and keyframe animation code set for each of those events that
+occur when ngRepeat triggers them:
+
+<pre>
+&#47;&#42;
+  We're using CSS transitions for when
+  the enter and move events are triggered
+  for the element that has the .repeated-item
+  class
+&#42;&#47;
+.repeated-item.ng-enter, .repeated-item.ng-move {
+  -webkit-transition:0.5s linear all;
+  -moz-transition:0.5s linear all;
+  -o-transition:0.5s linear all;
+  transition:0.5s linear all;
+  opacity:0;
+}
+
+&#47;&#42;
+ The ng-enter-active and ng-move-active
+ are where the transition destination properties
+ are set so that the animation knows what to
+ animate.
+&#42;&#47;
+.repeated-item.ng-enter.ng-enter-active,
+.repeated-item.ng-move.ng-move-active {
+  opacity:1;
+}
+
+&#47;&#42;
+  We're using CSS keyframe animations for when
+  the leave event is triggered for the element
+  that has the .repeated-item class
+&#42;&#47;
+.repeated-item.ng-leave {
+  -webkit-animation:0.5s my_animation;
+  -moz-animation:0.5s my_animation;
+  -o-animation:0.5s my_animation;
+  animation:0.5s my_animation;
+}
+
+&#64;keyframes my_animation {
+  from { opacity:1; }
+  to { opacity:0; }
+}
+
+&#47;&#42;
+  Unfortunately each browser vendor requires
+  its own definition of keyframe animation code...
+&#42;&#47;
+&#64;-webkit-keyframes my_animation {
+  from { opacity:1; }
+  to { opacity:0; }
+}
+
+&#64;-moz-keyframes my_animation {
+  from { opacity:1; }
+  to { opacity:0; }
+}
+
+&#64;-o-keyframes my_animation {
+  from { opacity:1; }
+  to { opacity:0; }
+}
+</pre>
+
+The same approach to animation can be used using JavaScript code (**jQuery is used within to perform animations**):
+
+<pre>
+myModule.animation('.repeated-item', function() {
+  return {
+    enter : function(element, done) {
+      element.css('opacity',0);
+      jQuery(element).animate({
+        opacity: 1
+      }, done);
+
+      // optional onDone or onCancel callback
+      // function to handle any post-animation
+      // cleanup operations
+      return function(isCancelled) {
+        if(isCancelled) {
+          jQuery(element).stop();
+        }
+      }
+    },
+    leave : function(element, done) {
+      element.css('opacity', 1);
+      jQuery(element).animate({
+        opacity: 0
+      }, done);
+
+      // optional onDone or onCancel callback
+      // function to handle any post-animation
+      // cleanup operations
+      return function(isCancelled) {
+        if(isCancelled) {
+          jQuery(element).stop();
+        }
+      }
+    },
+    move : function(element, done) {
+      element.css('opacity', 0);
+      jQuery(element).animate({
+        opacity: 1
+      }, done);
+
+      // optional onDone or onCancel callback
+      // function to handle any post-animation
+      // cleanup operations
+      return function(isCancelled) {
+        if(isCancelled) {
+          jQuery(element).stop();
+        }
+      }
+    },
+
+    // you can also capture these animation events
+    addClass : function(element, className, done) {},
+    removeClass : function(element, className, done) {}
+  }
+});
+</pre>
+
+With these generated CSS class names present on the element at the time, AngularJS automatically
+figures out whether to perform a CSS and/or JavaScript animation. If both CSS and JavaScript animation
+code is present, and match the CSS class name on the element, then AngularJS will run both animations at the same time.
+
+## Class and ngClass animation hooks
+
+AngularJS also pays attention to CSS class changes on elements by triggering the **add** and **remove** hooks.
+This means that if a CSS class is added to or removed from an element then an animation can be executed in between
+before the CSS class addition or removal is finalized. (Keep in mind that AngularJS will only be
+able to capture class changes if an **expression** or the **ng-class** directive is used on the element.)
+
+The example below shows how to perform animations during class changes:
+
+<example animations="true">
+ <file name="index.html">
+  <p>
+    <input type="button" value="set" ng-click="myCssVar='css-class'">
+    <input type="button" value="clear" ng-click="myCssVar=''">
+    <br>
+    <span ng-class="myCssVar">CSS-Animated Text</span>
+  </p>
+ </file>
+ <file name="style.css">
+   .css-class-add, .css-class-remove {
+     -webkit-transition:all cubic-bezier(0.250, 0.460, 0.450, 0.940) 0.5s;
+     -moz-transition:all cubic-bezier(0.250, 0.460, 0.450, 0.940) 0.5s;
+     -o-transition:all cubic-bezier(0.250, 0.460, 0.450, 0.940) 0.5s;
+     transition:all cubic-bezier(0.250, 0.460, 0.450, 0.940) 0.5s;
+   }
+
+   .css-class,
+   .css-class-add.css-class-add-active {
+     color: red;
+     font-size:3em;
+   }
+
+   .css-class-remove.css-class-remove-active {
+     font-size:1.0em;
+     color:black;
+   }
+ </file>
+</example>
+
+Although the CSS is a little different then what we saw before, the idea is the same.
+
+## Which directives support animations?
+
+A handful of common AngularJS directives support and trigger animation hooks whenever any major event occurs during its life cycle.
+The table below explains in detail which animation events are triggered
+
+| Directive                                                                           | Supported Animations                     |
+|-------------------------------------------------------------------------------------|------------------------------------------|
+| {@link api/ng.directive:ngRepeat#animations ngRepeat}                               | enter, leave, and move                   |
+| {@link api/ngRoute.directive:ngView#animations ngView}                              | enter and leave                          |
+| {@link api/ng.directive:ngInclude#animations ngInclude}                             | enter and leave                          |
+| {@link api/ng.directive:ngSwitch#animations ngSwitch}                               | enter and leave                          |
+| {@link api/ng.directive:ngIf#animations ngIf}                                       | enter and leave                          |
+| {@link api/ng.directive:ngShow#animations ngClass or &#123;&#123;class&#125;&#125;} | add and remove                           |
+| {@link api/ng.directive:ngShow#animations ngShow & ngHide}                          | add and remove (the ng-hide class value) |
+
+For a full breakdown of the steps involved during each animation event, refer to the {@link api/ngAnimate.$animate API docs}.
+
+## How do I use animations in my own directives?
+
+You can also use animations within custom directives can also be established by injecting `$animate` directly into your directive and
+making calls to it when needed.
+
+<pre>
+myModule.directive('my-directive', ['$animate', function($animate) {
+  return function(element, scope, attrs) {
+    element.bind('click', function() {
+      if(element.hasClass('clicked')) {
+        $animate.removeClass(element, 'clicked');
+      } else {
+        $animate.addClass(element, 'clicked');
+      }
+    });
+  };
+}]);
+</pre>
+
+## More about animations
+
+For a full breakdown of each method available on `$animate`, see the {@link api/ngAnimate.$animate API documentation}.
+
+To see a complete demo, see the {@link tutorial/step_12 animation step within the AngularJS phonecat tutorial}.