From 5309d295b49087868d68891b0d97450f8fa85f68 Mon Sep 17 00:00:00 2001 From: Paul Rohde Date: Tue, 18 Mar 2014 13:59:43 -0700 Subject: [PATCH 1/4] feat(doc): Library description for angular.animate --- lib/animate/module.dart | 84 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/lib/animate/module.dart b/lib/animate/module.dart index 612e5e678..78ac67a79 100644 --- a/lib/animate/module.dart +++ b/lib/animate/module.dart @@ -1,3 +1,87 @@ +/** + * The [animate] library makes it easier to build animations that affect the + * lifecycle of dom elements. The cononical example of this is animating the + * removal of an element from the dom. In order to do this, + * one must know about the duration of the animation, and immediatly perform + * changes in the backing data model. The animation library uses computed css + * styles to calculate the total duration of animation and handles the addition + * and removal of elements for the dom for elements that are manipulated by + * block level directives such as `ng-if`, `ng-repeat`, `ng-hide`, and more. + * + * To use, install the NgAnimateModule into your main module: + * + * var module = new Module() + * ..install(new NgAnimateModule()); + * + * Once this is installed, all block level dom manipulations will be routed + * through the [CssAnimate] implementation instead of the default [NgAnimate] + * class. + * + * For dom manipulations, this will add the `.ng-enter` class to a new dom + * element, and then read the computed style. If there is a transition or + * keyframe animation, the animation duration will be read, + * and the animation will be performed. The `.ng-enter-active` class will be + * added to set the target state for transition based animations. For + * removing elements from the dom, a simliar pattern is followed. The + * `.ng-leave` class will be added to an element, the transition and / or + * keyframe animation duration will be computed, and if it is non-zero the + * animation will be run by adding the `.ng-leave-active` class, + * and the element will be physically removed after the animation completes. + * + * The same set of steps is run for each of the following types of dom + * manipulation: + * + * * `.ng-enter` + * * `.ng-leave` + * * `.ng-move` + * * `.{cssclass}-add` + * * `.{cssclasss}-remove` + * + * When writing the css for animating a component you should avoid putting + * css transitions on elements that might be animated, otherwise there may be + * unintended pauses or side effects when an element is removed. + * + * Fade out example: + * + * HTML: + *
+ * Goodby world! + *
+ * + * CSS: + * .goodby.ng-leave { + * opacity: 1; + * transition: opacity 1s; + * } + * .goodby.ng-leave.ng-leave-active { + * opacity: 0; + * } + * + * This will perform a fade out animation on the 'goodby' div when the + * `ctrl.visible` property goes from `true` to `false`. + * + * The [CssAnimate] will also do optimizations on running animations by + * preventing child dom animations with the [AnimationOptimizer]. This + * prevents transitions on child elements while the parent is animating, + * but will not stop running transitions once they have started. + * + * Finally, it's possible to change the behavior of the [AnimationOptimizer] + * by using the `ng-animate` and `ng-animate-children` with the options + * `never`, `always`, or `auto`. `ng-animate` works only on the specific + * element it is applied too and will override other optimizations if `never` + * or `always` is specified. `ng-animate` defaults to `auto` which will + * defer to the `ng-animate-children` on a parent element or the currently + * running animation check. + * + * `ng-animate-children` allows animation to be controlled on large chunks of + * dom. It only affects child elements, and allows the `always`, `never`, + * and `auto` values to be specified. Always will always attempt animations + * on child dom directives, never will always prevent them (except in the + * case where a given element has `ng-animate="always"` specified), + * and `auto` will defer the decision to the currently running animation + * check. + */ + library angular.animate; import 'dart:async'; From f320a3c52e3f9578dc2d613b38785cfbcbfb4bce Mon Sep 17 00:00:00 2001 From: Paul Rohde Date: Tue, 18 Mar 2014 14:30:04 -0700 Subject: [PATCH 2/4] feat(doc): Animation library documentation updates and fixes. --- lib/animate/module.dart | 50 +++++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/lib/animate/module.dart b/lib/animate/module.dart index 78ac67a79..e86b03e2b 100644 --- a/lib/animate/module.dart +++ b/lib/animate/module.dart @@ -1,32 +1,44 @@ /** * The [animate] library makes it easier to build animations that affect the - * lifecycle of dom elements. The cononical example of this is animating the - * removal of an element from the dom. In order to do this, - * one must know about the duration of the animation, and immediatly perform - * changes in the backing data model. The animation library uses computed css - * styles to calculate the total duration of animation and handles the addition - * and removal of elements for the dom for elements that are manipulated by - * block level directives such as `ng-if`, `ng-repeat`, `ng-hide`, and more. + * lifecycle of dom elements. A useful example of this is animating the + * removal of an element from the dom. In order to do this ideally the + * operation should immediatly execute and manipulate the data model, + * and the framework should handle the actual remove of the dom element once + * the animation complets. This ensures that the logic and model of the + * application is seperated so that the state of the model can be reasoned + * about without having to wory about future modifications of the model. + * This library uses computed css styles to calculate the total duration + * of an animation and handles the addition, removal, and modification of dom + * elements for block level directives such as `ng-if`, `ng-repeat`, + * `ng-hide`, and more. * * To use, install the NgAnimateModule into your main module: * - * var module = new Module() + * var module = new Module() * ..install(new NgAnimateModule()); * - * Once this is installed, all block level dom manipulations will be routed - * through the [CssAnimate] implementation instead of the default [NgAnimate] - * class. + * Once the module has been installed, all block level dom manipulations will + * be routed through the [CssAnimate] class instead of the + * default [NgAnimate] implementation. This will, in turn, + * perform the tracking, manipulation, and computation for animations. * - * For dom manipulations, this will add the `.ng-enter` class to a new dom - * element, and then read the computed style. If there is a transition or - * keyframe animation, the animation duration will be read, + * As an example of how this works, lets walk through what happens whan an + * element is added to the dom. The [CssAnimate] implementation will add the + * `.ng-enter` class to new dom elements when they are inserted into the dom + * by a directive and will read the computed style. If there is a + * transition or keyframe animation, that animation duration will be read, * and the animation will be performed. The `.ng-enter-active` class will be - * added to set the target state for transition based animations. For - * removing elements from the dom, a simliar pattern is followed. The + * added to the dom element to set the target state for transition based + * animations. When the animation is complete (determined by the + * precomputed duration) the `.ng-enter` and `.ng-enter-active` classes + * will be removed from the dom element. + * + * When removing elements from the dom, a simliar pattern is followed. The * `.ng-leave` class will be added to an element, the transition and / or * keyframe animation duration will be computed, and if it is non-zero the - * animation will be run by adding the `.ng-leave-active` class, - * and the element will be physically removed after the animation completes. + * animation will be run by adding the `.ng-leave-active` class. When + * the animation completes, the element will be physically removed from the + * dom. * * The same set of steps is run for each of the following types of dom * manipulation: @@ -38,7 +50,7 @@ * * `.{cssclasss}-remove` * * When writing the css for animating a component you should avoid putting - * css transitions on elements that might be animated, otherwise there may be + * css transitions on elements that might be animated or there may be * unintended pauses or side effects when an element is removed. * * Fade out example: From 99c7afb2275dee41b043d77421a29d8d1f746eff Mon Sep 17 00:00:00 2001 From: Paul Rohde Date: Tue, 18 Mar 2014 14:49:50 -0700 Subject: [PATCH 3/4] feat(doc): Animation editorial tweaks and spelling corrections. --- lib/animate/module.dart | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/animate/module.dart b/lib/animate/module.dart index e86b03e2b..927284917 100644 --- a/lib/animate/module.dart +++ b/lib/animate/module.dart @@ -1,4 +1,6 @@ /** + * Css animation and dom lifecycle management for Angular. + * * The [animate] library makes it easier to build animations that affect the * lifecycle of dom elements. A useful example of this is animating the * removal of an element from the dom. In order to do this ideally the @@ -56,16 +58,16 @@ * Fade out example: * * HTML: - *
- * Goodby world! + *
+ * Goodbye world! *
* * CSS: - * .goodby.ng-leave { + * .goodbye.ng-leave { * opacity: 1; * transition: opacity 1s; * } - * .goodby.ng-leave.ng-leave-active { + * .goodbye.ng-leave.ng-leave-active { * opacity: 0; * } * From ca5e0b98054d051774f40cd4a6e43fe1ba11897f Mon Sep 17 00:00:00 2001 From: Paul Rohde Date: Tue, 18 Mar 2014 14:51:16 -0700 Subject: [PATCH 4/4] feat(doc): Animation editorial tweaks and spelling corrections. --- lib/animate/module.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/animate/module.dart b/lib/animate/module.dart index 927284917..3560a1371 100644 --- a/lib/animate/module.dart +++ b/lib/animate/module.dart @@ -49,7 +49,7 @@ * * `.ng-leave` * * `.ng-move` * * `.{cssclass}-add` - * * `.{cssclasss}-remove` + * * `.{cssclass}-remove` * * When writing the css for animating a component you should avoid putting * css transitions on elements that might be animated or there may be