Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit d45ac77

Browse files
matskomhevery
matsko
authored and
mhevery
committed
chore(ngdocs): provide detailed documentation for the $animate service timeline
1 parent 9f3935b commit d45ac77

File tree

1 file changed

+64
-53
lines changed

1 file changed

+64
-53
lines changed

‎src/ngAnimate/animate.js‎

Lines changed: 64 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
* Below is a more detailed breakdown of the supported animation events provided by pre-existing ng directives:
2525
*
2626
* | Directive | Supported Animations |
27-
* |========================================================== |====================================================|
27+
* |---------------------------------------------------------- |----------------------------------------------------|
2828
* | {@link ng.directive:ngRepeat#animations ngRepeat} | enter, leave and move |
2929
* | {@link ngRoute.directive:ngView#animations ngView} | enter and leave |
3030
* | {@link ng.directive:ngInclude#animations ngInclude} | enter and leave |
@@ -55,7 +55,7 @@
5555
*
5656
* <!--
5757
* the animate service will automatically add .ng-enter and .ng-leave to the element
58-
* to trigger the CSS animations
58+
* to trigger the CSS transition/animations
5959
* -->
6060
* <ANY class="slide" ng-include="..."></ANY>
6161
* </pre>
@@ -261,12 +261,20 @@ angular.module('ngAnimate', ['ng'])
261261
* @description
262262
* Appends the element to the parent element that resides in the document and then runs the enter animation. Once
263263
* the animation is started, the following CSS classes will be present on the element for the duration of the animation:
264-
* <pre>
265-
* .ng-enter
266-
* .ng-enter-active
267-
* </pre>
268264
*
269-
* Once the animation is complete then the done callback, if provided, will be also fired.
265+
* Below is a breakdown of each step that occurs during enter animation:
266+
*
267+
* | Animation Step | What the element class attribute looks like |
268+
* |----------------------------------------------------------------------------------------------|-----------------------------------------------|
269+
* | 1. $animate.enter(...) is called | class="my-animation" |
270+
* | 2. element is inserted into the parent element or beside the after element | class="my-animation" |
271+
* | 3. the .ng-enter class is added to the element | class="my-animation ng-enter" |
272+
* | 4. $animate runs any JavaScript-defined animations on the element | class="my-animation ng-enter" |
273+
* | 5. $animate scans the element styles to get the CSS transition/animation duration and delay | class="my-animation ng-enter" |
274+
* | 6. the .ng-enter-active class is added (this triggers the CSS transition/animation) | class="my-animation ng-enter ng-enter-active" |
275+
* | 7. $animate waits for X milliseconds for the animation to complete | class="my-animation ng-enter ng-enter-active" |
276+
* | 8. The animation ends and both CSS classes are removed from the element | class="my-animation" |
277+
* | 9. The done() callback is fired (if provided) | class="my-animation" |
270278
*
271279
* @param {jQuery/jqLite element} element the element that will be the focus of the enter animation
272280
* @param {jQuery/jqLite element} parent the parent element of the element that will be the focus of the enter animation
@@ -287,12 +295,20 @@ angular.module('ngAnimate', ['ng'])
287295
* @description
288296
* Runs the leave animation operation and, upon completion, removes the element from the DOM. Once
289297
* the animation is started, the following CSS classes will be added for the duration of the animation:
290-
* <pre>
291-
* .ng-leave
292-
* .ng-leave-active
293-
* </pre>
294298
*
295-
* Once the animation is complete then the done callback, if provided, will be also fired.
299+
* Below is a breakdown of each step that occurs during enter animation:
300+
*
301+
* | Animation Step | What the element class attribute looks like |
302+
* |----------------------------------------------------------------------------------------------|----------------------------------------------|
303+
* | 1. $animate.leave(...) is called | class="my-animation" |
304+
* | 2. the .ng-leave class is added to the element | class="my-animation ng-leave" |
305+
* | 3. $animate runs any JavaScript-defined animations on the element | class="my-animation ng-leave" |
306+
* | 4. $animate scans the element styles to get the CSS transition/animation duration and delay | class="my-animation ng-leave" |
307+
* | 5. the .ng-leave-active class is added (this triggers the CSS transition/animation) | class="my-animation ng-leave ng-leave-active |
308+
* | 6. $animate waits for X milliseconds for the animation to complete | class="my-animation ng-leave ng-leave-active |
309+
* | 7. The animation ends and both CSS classes are removed from the element | class="my-animation" |
310+
* | 8. The element is removed from the DOM | ... |
311+
* | 9. The done() callback is fired (if provided) | ... |
296312
*
297313
* @param {jQuery/jqLite element} element the element that will be the focus of the leave animation
298314
* @param {function()=} done callback function that will be called once the animation is complete
@@ -313,12 +329,20 @@ angular.module('ngAnimate', ['ng'])
313329
* Fires the move DOM operation. Just before the animation starts, the animate service will either append it into the parent container or
314330
* add the element directly after the after element if present. Then the move animation will be run. Once
315331
* the animation is started, the following CSS classes will be added for the duration of the animation:
316-
* <pre>
317-
* .ng-move
318-
* .ng-move-active
319-
* </pre>
320332
*
321-
* Once the animation is complete then the done callback, if provided, will be also fired.
333+
* Below is a breakdown of each step that occurs during move animation:
334+
*
335+
* | Animation Step | What the element class attribute looks like |
336+
* |----------------------------------------------------------------------------------------------|---------------------------------------------|
337+
* | 1. $animate.move(...) is called | class="my-animation" |
338+
* | 2. element is moved into the parent element or beside the after element | class="my-animation" |
339+
* | 3. the .ng-move class is added to the element | class="my-animation ng-move" |
340+
* | 4. $animate runs any JavaScript-defined animations on the element | class="my-animation ng-move" |
341+
* | 5. $animate scans the element styles to get the CSS transition/animation duration and delay | class="my-animation ng-move" |
342+
* | 6. the .ng-move-active class is added (this triggers the CSS transition/animation) | class="my-animation ng-move ng-move-active" |
343+
* | 7. $animate waits for X milliseconds for the animation to complete | class="my-animation ng-move ng-move-active" |
344+
* | 8. The animation ends and both CSS classes are removed from the element | class="my-animation" |
345+
* | 9. The done() callback is fired (if provided) | class="my-animation" |
322346
*
323347
* @param {jQuery/jqLite element} element the element that will be the focus of the move animation
324348
* @param {jQuery/jqLite element} parent the parent element of the element that will be the focus of the move animation
@@ -340,27 +364,19 @@ angular.module('ngAnimate', ['ng'])
340364
* Unlike the other animation methods, the animate service will suffix the className value with {@type -add} in order to provide
341365
* the animate service the setup and active CSS classes in order to trigger the animation.
342366
*
343-
* For example, upon execution of:
344-
*
345-
* <pre>
346-
* $animate.addClass(element, 'super');
347-
* </pre>
348-
*
349-
* The generated CSS class values present on element will look like:
350-
* <pre>
351-
* .super-add
352-
* .super-add-active
353-
* </pre>
367+
* Below is a breakdown of each step that occurs during addClass animation:
354368
*
355-
* And upon completion, the generated animation CSS classes will be removed from the element, but the className
356-
* value will be attached to the element. In this case, based on the previous example, the resulting CSS class for the element
357-
* will look like so:
358-
*
359-
* <pre>
360-
* .super
361-
* </pre>
362-
*
363-
* Once this is complete, then the done callback, if provided, will be fired.
369+
* | Animation Step | What the element class attribute looks like |
370+
* |------------------------------------------------------------------------------------------------|---------------------------------------------|
371+
* | 1. $animate.addClass(element, 'super') is called | class="" |
372+
* | 2. the .super-add class is added to the element | class="super-add" |
373+
* | 3. $animate runs any JavaScript-defined animations on the element | class="super-add" |
374+
* | 4. $animate scans the element styles to get the CSS transition/animation duration and delay | class="super-add" |
375+
* | 5. the .super-add-active class is added (this triggers the CSS transition/animation) | class="super-add super-add-active" |
376+
* | 6. $animate waits for X milliseconds for the animation to complete | class="super-add super-add-active" |
377+
* | 7. The animation ends and both CSS classes are removed from the element | class="" |
378+
* | 8. The super class is added to the element | class="super" |
379+
* | 9. The done() callback is fired (if provided) | class="super" |
364380
*
365381
* @param {jQuery/jqLite element} element the element that will be animated
366382
* @param {string} className the CSS class that will be animated and then attached to the element
@@ -382,23 +398,18 @@ angular.module('ngAnimate', ['ng'])
382398
* from the element. Unlike the other animation methods, the animate service will suffix the className value with {@type -remove} in
383399
* order to provide the animate service the setup and active CSS classes in order to trigger the animation.
384400
*
385-
* For example, upon the execution of:
386-
*
387-
* <pre>
388-
* $animate.removeClass(element, 'super');
389-
* </pre>
390-
*
391-
* The CSS class values present on element during the animation will look like:
392-
*
393-
* <pre>
394-
* .super //this was here from before
395-
* .super-remove
396-
* .super-remove-active
397-
* </pre>
401+
* Below is a breakdown of each step that occurs during removeClass animation:
398402
*
399-
* And upon completion, the generated animation CSS classes will be removed from the element as well as the
400-
* className value that was provided (in this case {@type super} will be removed). Once that is complete, then, if provided,
401-
* the done callback will be fired.
403+
* | Animation Step | What the element class attribute looks like |
404+
* |-----------------------------------------------------------------------------------------------|-------------------------------------------------|
405+
* | 1. $animate.removeClass(element, 'super') is called | class="super" |
406+
* | 2. the .super-remove class is added to the element | class="super super-remove" |
407+
* | 3. $animate runs any JavaScript-defined animations on the element | class="super super-remove" |
408+
* | 4. $animate scans the element styles to get the CSS transition/animation duration and delay | class="super super-remove" |
409+
* | 5. the .super-remove-active class is added (this triggers the CSS transition/animation) | class="super super-remove super-remove-active" |
410+
* | 6. $animate waits for X milliseconds for the animation to complete | class="super super-remove super-remove-active" |
411+
* | 7. The animation ends and both CSS all three classes are removed from the element | class="" |
412+
* | 8. The done() callback is fired (if provided) | class="" |
402413
*
403414
* @param {jQuery/jqLite element} element the element that will be animated
404415
* @param {string} className the CSS class that will be animated and then removed from the element

0 commit comments

Comments
 (0)