From 08ae41019e5879b1907b2fbf02d129c6ebe452f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Rodr=C3=ADguez?= <Foxandxss@gmail.com>
Date: Wed, 14 Sep 2016 00:57:58 +0200
Subject: [PATCH] docs(animation): add callbacks documentation (#2271)

---
 public/docs/_examples/animations/e2e-spec.ts    | 13 +++++++++++++
 .../ts/app/hero-list-multistep.component.ts     | 15 ++++++++++++++-
 public/docs/ts/latest/guide/animations.jade     | 17 +++++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/public/docs/_examples/animations/e2e-spec.ts b/public/docs/_examples/animations/e2e-spec.ts
index e2e9b64b9b..9b6319db66 100644
--- a/public/docs/_examples/animations/e2e-spec.ts
+++ b/public/docs/_examples/animations/e2e-spec.ts
@@ -289,6 +289,19 @@ describe('Animation Tests', () => {
     });
   });
 
+  describe('callbacks', () => {
+    it('fires a callback on start and done', () => {
+      addActiveHero();
+      browser.manage().logs().get('browser').then((logs) => {
+        const animationMessages = logs.filter((log) => {
+          return log.message.indexOf('Animation') !== -1 ? true : false;
+        });
+
+        expect(animationMessages.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
   function addActiveHero(sleep?: number) {
     sleep = sleep || 500;
     element(by.buttonText('Add active hero')).click();
diff --git a/public/docs/_examples/animations/ts/app/hero-list-multistep.component.ts b/public/docs/_examples/animations/ts/app/hero-list-multistep.component.ts
index f0f4c1b3e1..adea35047c 100644
--- a/public/docs/_examples/animations/ts/app/hero-list-multistep.component.ts
+++ b/public/docs/_examples/animations/ts/app/hero-list-multistep.component.ts
@@ -6,7 +6,8 @@ import {
   style,
   animate,
   transition,
-  keyframes
+  keyframes,
+  AnimationTransitionEvent
 } from '@angular/core';
 
 import { Heroes } from './hero.service';
@@ -14,14 +15,18 @@ import { Heroes } from './hero.service';
 @Component({
   moduleId: module.id,
   selector: 'hero-list-multistep',
+  // #docregion template
   template: `
     <ul>
       <li *ngFor="let hero of heroes"
+          (@flyInOut.start)="animationStarted($event)"
+          (@flyInOut.done)="animationDone($event)"
           [@flyInOut]="'in'">
         {{hero.name}}
       </li>
     </ul>
   `,
+  // #enddocregion template
   styleUrls: ['hero-list.component.css'],
   /* The element here always has the state "in" when it
    * is present. We animate two transitions: From void
@@ -54,4 +59,12 @@ import { Heroes } from './hero.service';
 })
 export class HeroListMultistepComponent {
   @Input() heroes: Heroes;
+
+  animationStarted(event: AnimationTransitionEvent) {
+    console.warn('Animation started: ', event);
+  }
+
+  animationDone(event: AnimationTransitionEvent) {
+    console.warn('Animation done: ', event);
+  }
 }
diff --git a/public/docs/ts/latest/guide/animations.jade b/public/docs/ts/latest/guide/animations.jade
index 5455b1b3d1..8fc54b914c 100644
--- a/public/docs/ts/latest/guide/animations.jade
+++ b/public/docs/ts/latest/guide/animations.jade
@@ -34,6 +34,7 @@ include ../_util-fns
   * [Animation Timing](#animation-timing)
   * [Multi-Step Animations with Keyframes](#multi-step-animations-with-keyframes)
   * [Parallel Animation Groups](#parallel-animation-groups)
+  * [Animation callbacks](#animation-callbacks)
 
 .l-sub-section
   :marked
@@ -337,3 +338,19 @@ figure
 
 :marked
   One group animates the element transform and width. The other animates the opacity.
+
+:marked
+  ## Animation callbacks
+
+  A callback is fired when an animation is started and also when it is done.
+
+  In the keyframes example, we have a `trigger` called `@flyInOut`. There we can hook
+  those callbacks like:
+
++makeExample('animations/ts/app/hero-list-multistep.component.ts', 'template')(format=".")
+
+:marked
+  The callbacks receive an `AnimationTransitionEvent` which contains useful properties such as `fromState`,
+  `toState` and `totalTime`.
+
+  Those callbacks will fire whether or not an animation is picked up.