From 41f19c19c350ef38472eda8f669f4a32d7b1abde Mon Sep 17 00:00:00 2001 From: Jakub Freisler Date: Mon, 28 May 2018 01:48:36 +0200 Subject: [PATCH] 0docs(ngAnimate): add `animating between value changes` section Add a section which covers use case when user's need to animate upon every variable's value change. Refers #16561 --- src/ngAnimate/module.js | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/ngAnimate/module.js b/src/ngAnimate/module.js index f37c404f7d7f..07757c8784c6 100644 --- a/src/ngAnimate/module.js +++ b/src/ngAnimate/module.js @@ -267,9 +267,22 @@ * .message.ng-enter-prepare { * opacity: 0; * } - * * ``` * + * ### Animating between value changes + * + * Sometimes you need to animate between different expression states, whose values + * don't necessary need to be known or referenced in CSS styles. + * Unless possible with another ["animation aware" directive](#directive-support), that specific + * use case can always be covered with {@link ngAnimate.directive:ngAnimateSwap} as can be seen in + * {@link ngAnimate.directive:ngAnimateSwap#examples this example}. + * + * Note that {@link ngAnimate.directive:ngAnimateSwap} is a *structural directive*, which means it + * creates a new instance of the element (including any other/child directives it may have) and + * links it to a new scope every time *swap* happens. In some cases this might not be desirable + * (e.g. for performance reasons, or when you wish to retain internal state on the original + * element instance). + * * ## JavaScript-based Animations * * ngAnimate also allows for animations to be consumed by JavaScript code. The approach is similar to CSS-based animations (where there is a shared