lifecycle-hooks.jade

block includes
  include ../_util-fns

- var top="vertical-align:top"

figure
  img(src="/resources/images/devguide/lifecycle-hooks/hooks-in-sequence.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:30px")

:marked
  A component has a lifecycle managed by Angular itself. 
  
  Angular creates it, renders it, creates and renders its children,
  checks it when its data-bound properties change, and destroys it before removing it from the DOM.

  Angular offers **lifecycle hooks**
  that provide visibility into these key life moments and the ability to act when they occur.

  A directive has the same set of lifecycle hooks.
  <br clear="all">
  ## Table of Contents
    * [Overview](#hooks-overview)
    <br><br>
    * [Each hook's purpose and timing](#hooks-purpose-timing)
+ifDocsFor('ts|js')
  :marked
    * [Interfaces are optional (technically)](#interface-optional)
  :marked
    * [Other Angular lifecycle hooks](#other-lifecycle-hooks)
    <br><br>
    * [The lifecycle sample](#the-sample)
      * [All](#peek-a-boo)
      * [Spying OnInit and OnDestroy](#spy)
      * [OnChanges](#onchanges)
      * [DoCheck](#docheck)
      * [AfterViewInit and AfterViewChecked](#afterview)
      * [AfterContentInit and AfterContentChecked](#aftercontent)
:marked
  Try the <live-example></live-example>.

a#hooks-overview
.l-main-section
:marked
  ## Component lifecycle Hooks
  Directive and component instances have a lifecycle
  as Angular creates, updates, and destroys them.
  Developers can tap into key moments in that lifecycle by implementing
  one or more of the *Lifecycle Hook* interfaces in the Angular `core` library.

  Each interface has a single hook method whose name is the interface name prefixed with `ng`.
  For example, the `OnInit` interface has a hook method named `ngOnInit` 
  that Angular calls shortly after creating the component:
+makeExample('lifecycle-hooks/ts/app/peek-a-boo.component.ts', 'ngOnInit', 'peek-a-boo.component.ts (excerpt)')(format='.')
:marked
  No directive or component will implement all of the lifecycle hooks.
  Angular only calls a directive/component hook method *if it is defined*.

a#hooks-purpose-timing
.l-main-section
:marked
  ## Lifecycle sequence
  *After* Angular creates a component/directive by `new`-ing its constructor,
  it calls the lifecycle hook methods in the following sequence at specific moments:
table(width="100%")
  col(width="20%")
  col(width="80%")
  tr
    th Hook
    th Purpose and Timing

  tr(style=top)
    td ngOnChanges
    td
      :marked
        Respond when Angular (re)sets data-bound input properties.
        The method receives a `SimpleChanges` object of current and previous property values.
        
        Called before `ngOnInit` and whenever one or more data-bound input properties change.

  tr(style=top)
    td ngOnInit
    td
      :marked
        Initialize the directive/component after Angular first displays the data-bound properties
        and sets the directive/component's input properties.
        
        Called _once_, after the _first_ `ngOnChanges`. 

  tr(style=top)
    td ngDoCheck
    td
      :marked
        Detect and act upon changes that Angular can't or won't detect on its own. 
        
        Called during every change detection run, immediately after `ngOnChanges` and `ngOnInit`.

  tr(style=top)
    td ngAfterContentInit
    td
      :marked
        Respond after Angular projects external content into the directive/component's view.

        Called _once_ after the first `NgDoCheck`.
        
  tr(style=top)
    td ngAfterContentChecked
    td
      :marked
        Respond after Angular checks the content projected into the directive/component.

        Called after the `ngAfterContentInit` and every subsequent `NgDoCheck`.
        
  tr(style=top)
    td ngAfterViewInit
    td
      :marked
        Respond after Angular initializes the directive/component's views and child views.

        Called _once_ after the first `ngAfterContentChecked`.

  tr(style=top)
    td ngAfterViewChecked
    td
      :marked
        Respond after Angular checks the directive/component's views and child views.

        Called after the `ngAfterViewInit` and every subsequent `ngAfterContentChecked`.

  tr(style=top)
    td ngOnDestroy
    td
      :marked
        Cleanup just before Angular destroys the directive/component.
        Unsubscribe observables and detach event handlers to avoid memory leaks.      

        Called _just before_ Angular destroys the directive/component.

+ifDocsFor('ts|js')
  a#interface-optional
  .l-main-section  
  :marked
    ## Interface are optional (technically)

    The interfaces are optional for JavaScript and Typescript developers from a purely technical perspective.
    The JavaScript language doesn't have interfaces.
    Angular can't see TypeScript interfaces at runtime because they disappear from the transpiled JavaScript.

    Fortunately, they aren't necessary.
    You don't have to add the lifecycle hook interfaces to directives and components to benefit from the hooks themselves.

    Angular instead inspects directive and component classes and calls the hook methods *if they are defined*.
    Angular finds and calls methods like `ngOnInit()`, with or without the interfaces.

    Nonetheless, it's good practice to add interfaces to TypeScript directive classes
    in order to benefit from strong typing and editor tooling.
  
a#other-lifecycle-hooks
.l-main-section
:marked
  ## Other lifecycle hooks

  Other Angular sub-systems may have their own lifecycle hooks apart from these component hooks.

block other-angular-subsystems
  //- N/A for TS.

:marked
  3rd party libraries might implement their hooks as well in order to give developers more
  control over how these libraries are used.

.l-main-section#the-sample
:marked
  ## Lifecycle exercises

  The <live-example></live-example>
  demonstrates the lifecycle hooks in action through a series of exercises
  presented as components under the control of the root `AppComponent`.

  They follow a common pattern:  a *parent* component serves as a test rig for
  a *child* component that illustrates one or more of the lifecycle hook methods.

  Here's a brief description of each exercise:

table(width="100%")
  col(width="20%")
  col(width="80%")
  tr
    th Component
    th Description
  tr(style=top)
    td <a href="#peek-a-boo">Peek-a-boo</a>
    td
      :marked
        Demonstrates every lifecycle hook.
        Each hook method writes to the on-screen log.
  tr(style=top)
    td <a href="#spy">Spy</a>
    td
      :marked
        Directives have lifecycle hooks too.
        A `SpyDirective` can log when the element it spies upon is
        created or destroyed using the `ngOnInit` and `ngOnDestroy` hooks.

        This example applies the `SpyDirective` to a `<div>` in an `ngFor` *hero* repeater
        managed by the parent `SpyComponent`.
  tr(style=top)
    td <a href="#onchanges">OnChanges</a>
    td
      :marked
        See how Angular calls the `ngOnChanges` hook with a `changes` object
        every time one of the component input properties changes.
        Shows how to interpret the `changes` object.
  tr(style=top)
    td <a href="#docheck">DoCheck</a>
    td
      :marked
        Implements an `ngDoCheck` method with custom change detection.
        See how often Angular calls this hook and watch it post changes to a log.
  tr(style=top)
    td <a href="#afterview">AfterView</a>
    td
      :marked
        Shows what Angular means by a *view*.
        Demonstrates the `ngAfterViewInit` and `ngAfterViewChecked` hooks.
  tr(style=top)
    td <a href="#aftercontent">AfterContent</a>
    td
      :marked
        Shows how to project external content into a component and
        how to distinguish projected content from a component's view children.
        Demonstrates the `ngAfterContentInit` and `ngAfterContentChecked` hooks.
  tr(style=top)
    td Counter
    td
      :marked
        Demonstrates a combination of a component and a directive
        each with its own hooks.

        In this example, a `CounterComponent` logs a change (via `ngOnChanges`)
        every time the parent component increments its input counter property.
        Meanwhile, the `SpyDirective` from the previous example is applied
        to the `CounterComponent` log where it watches log entries being created and destroyed.

:marked
  The remainder of this chapter discusses selected exercises in further detail.

a#peek-a-boo
.l-main-section
:marked
  ## Peek-a-boo: all hooks
  The `PeekABooComponent` demonstrates all of the hooks in one component.

  You would rarely, if ever, implement all of the interfaces like this.
  The peek-a-boo exists to show how Angular calls the hooks in the expected order.

  This snapshot reflects the state of the log after the user clicked the *Create...* button and then the *Destroy...* button.
figure.image-display
  img(src="/resources/images/devguide/lifecycle-hooks/peek-a-boo.png" alt="Peek-a-boo")
:marked
  The sequence of log messages follows the prescribed hook calling order:
  `OnChanges`, `OnInit`, `DoCheck`&nbsp;(3x), `AfterContentInit`, `AfterContentChecked`&nbsp;(3x),
  `AfterViewInit`, `AfterViewChecked`&nbsp;(3x), and `OnDestroy`.

.l-sub-section
  :marked
    The constructor isn't an Angular hook *per se*.
    The log confirms that input properties (the `name` property in this case) have no assigned values at construction.
:marked
  Had the user clicked the *Update Hero* button, the log would show another `OnChanges` and two more triplets of
  `DoCheck`, `AfterContentChecked` and `AfterViewChecked`.
  Clearly these three hooks fire a *often*. Keep the logic in these hooks as lean as possible!

  The next examples focus on hook details.

a#spy
.l-main-section
:marked
  ## Spying *OnInit* and *OnDestroy*

  Go undercover with these two spy hooks to discover when an element is initialized or destroyed.

  This is the perfect infiltration job for a directive.
  The heroes will never know they're being watched.

.l-sub-section
  :marked
    Kidding aside, pay attention to two key points:

    1. Angular calls hook methods for *directives* as well as components.<br><br>

    2. A spy directive can provide insight into a DOM object that you cannot change directly.
    Obviously you can't touch the implementation of a native `div`.
    You can't modify a third party component either.
    But you can watch both with a directive.


:marked
  The sneaky spy directive is simple,  consisting almost entirely of `ngOnInit` and `ngOnDestroy` hooks
  that log messages to the parent via an injected `LoggerService`.

+makeExample('lifecycle-hooks/ts/app/spy.directive.ts', 'spy-directive')(format=".")

:marked
  You can apply the spy to any native or component element and it'll be initialized and destroyed
  at the same time as that element.
  Here it is attached to the repeated hero `<div>`
+makeExample('lifecycle-hooks/ts/app/spy.component.html', 'template')(format=".")

:marked
  Each spy's birth and death marks the birth and death of the attached hero `<div>`
  with an entry in the *Hook Log* as seen here:

figure.image-display
  img(src='/resources/images/devguide/lifecycle-hooks/spy-directive.gif' alt="Spy Directive")

:marked
  Adding a hero results in a new hero `<div>`. The spy's `ngOnInit` logs that event.

  The *Reset* button clears the `heroes` list.
  Angular removes all hero `<div>` elements from the DOM and destroys their spy directives at the same time.
  The spy's `ngOnDestroy` method reports its last moments.

  The `ngOnInit` and `ngOnDestroy` methods have more vital roles to play in real applications.

  ### OnInit

  Use `ngOnInit` for two main reasons:
  1. to perform complex initializations shortly after construction
  1. to set up the component after Angular sets the input properties

  Experienced developers agree that components should be cheap and safe to construct.
.l-sub-section
  :marked
    Misko Hevery, Angular team lead,
    [explains why](http://misko.hevery.com/code-reviewers-guide/flaw-constructor-does-real-work/) 
    you should avoid complex constructor logic.

:marked
  Don't fetch data in a component constructor.
  You shouldn't worry that a new component will try to contact a remote server when
  created under test or before you decide to display it.
  Constructors should do no more than set the initial local variables to simple values.
  
  An `ngOnInit` is a good place for a component to fetch its initial data. The
  [Tutorial](../tutorial/toh-pt4.html#oninit) and [HTTP](server-communication.html#oninit) chapter
  show how.


  Remember also that a directive's data-bound input properties are not set until _after construction_.
  That's a problem if you need to initialize the directive based on those properties.
  They'll have been set when `ngOninit` runs.
.l-sub-section
  :marked
    The `ngOnChanges` method is your first opportunity to access those properties.
    Angular calls `ngOnChanges` before `ngOnInit` ... and many times after that.
    It only calls `ngOnInit` once.
:marked
  You can count on Angular to call the `ngOnInit` method _soon_ after creating the component.
  That's where the heavy initialization logic belongs.

  ### OnDestroy

  Put cleanup logic in `ngOnDestroy`, the logic that *must* run before Angular destroys the directive.

  This is the time to notify another part of the application that the component is going away.

  This is the place to free resources that won't be garbage collected automatically.
  Unsubscribe from observables and DOM events. Stop interval timers.
  Unregister all callbacks that this directive registered with global or application services.
  You risk memory leaks if you neglect to do so.

.l-main-section
:marked
  ## OnChanges

  Angular calls its `ngOnChanges` method whenever it detects changes to ***input properties*** of the component (or directive).
  This example monitors the `OnChanges` hook.
+makeExample('lifecycle-hooks/ts/app/on-changes.component.ts', 'ng-on-changes', 'OnChangesComponent (ngOnChanges)')(format=".")
:marked
  The `ngOnChanges` method takes an object that maps each changed property name to a
  [SimpleChange](../api/core/index/SimpleChange-class.html) object holding the current and previous property values.
  This hook iterates over the changed properties and logs them.

  The example component, `OnChangesComponent`, has two input properties: `hero` and `power`.
+makeExample('lifecycle-hooks/ts/app/on-changes.component.ts', 'inputs')(format=".")
:marked
  The host `OnChangesParentComponent` binds to them like this:

+makeExample('lifecycle-hooks/ts/app/on-changes-parent.component.html', 'on-changes')
:marked
  Here's the sample in action as the user makes changes.

figure.image-display
  img(src='/resources/images/devguide/lifecycle-hooks/on-changes-anim.gif' alt="OnChanges")

:marked
  The log entries appear as the string value of the *power* property changes. 
  But the `ngOnChanges` does not catch changes to `hero.name`
  That's surprising at first.

  Angular only calls the hook when the value of the input property changes.
  The value of the `hero` property is the *reference to the hero object*.
  Angular doesn't care that the hero's own `name` property changed.
  The hero object *reference* didn't change so, from Angular's perspective, there is no change to report!

.l-main-section
:marked
  ## DoCheck
  Use the `DoCheck` hook to detect and act upon changes that Angular doesn't catch on its own.
.l-sub-section
  :marked
    Use this method to detect a change that Angular overlooked.
:marked
  The *DoCheck* sample extends the *OnChanges* sample with the following `ngDoCheck` hook:
+makeExample('lifecycle-hooks/ts/app/do-check.component.ts', 'ng-do-check', 'DoCheckComponent (ngDoCheck)')(format=".")
:marked
  This code inspects certain _values-of-interest_, capturing and comparing their current state against previous values.
  It writes a special message to the log when there are no substantive changes to the `hero` or the `power`
  so you can see how often `DoCheck` is called. The results are illuminating:

figure.image-display
  img(src='/resources/images/devguide/lifecycle-hooks/do-check-anim.gif' alt="DoCheck")
:marked
  While the `ngDoCheck` hook can detect when the hero's `name` has changed, it has a frightful cost.
  This hook is called with enormous frequency &mdash;
  after _every_ change detection cycle no matter where the change occurred.
  It's called over twenty times in this example before the user can do anything.

  Most of these initial checks are triggered by Angular's first rendering of *unrelated data elsewhere on the page*.
  Mere mousing into another input box triggers a call.
  Relatively few calls reveal actual changes to pertinent data.
  Clearly our implementation must be very lightweight or the user experience will suffer.

.l-main-section
:marked
  ## AfterView
  The *AfterView* sample explores the `AfterViewInit` and `AfterViewChecked` hooks that Angular calls
  *after* it creates a component's child views.

  Here's a child view that displays a hero's name in an input box:
+makeExample('lifecycle-hooks/ts/app/after-view.component.ts', 'child-view', 'ChildComponent')(format=".")
:marked
  The `AfterViewComponent` displays this child view *within its template*:
+makeExample('lifecycle-hooks/ts/app/after-view.component.ts', 'template', 'AfterViewComponent (template)')(format=".")
:marked
  The following hooks take action based on changing values *within the child view*
  which can only be reached by querying for the child view via the property decorated with
  [@ViewChild](../api/core/index/ViewChild-decorator.html).

+makeExample('lifecycle-hooks/ts/app/after-view.component.ts', 'hooks', 'AfterViewComponent (class excerpts)')(format=".")
#wait-a-tick
:marked
  ### Abide by the unidirectional data flow rule
  The `doSomething` method updates the screen when the hero name exceeds 10 characters.

+makeExample('lifecycle-hooks/ts/app/after-view.component.ts', 'do-something', 'AfterViewComponent (doSomething)')(format=".")
:marked
  Why does the `doSomething` method wait a tick before updating `comment`?

  Angular's unidirectional data flow rule forbids updates to the view *after* it has been composed.
  Both of these hooks fire _after_ the component's view has been composed.

  Angular throws an error if the hook updates the component's data-bound `comment` property immediately (try it!).
block tick-methods
  :marked
    The `LoggerService.tick_then()` postpones the log update 
    for one turn of the browser's JavaScript cycle ... and that's just long enough.

:marked
  Here's *AfterView* in action
figure.image-display
  img(src='/resources/images/devguide/lifecycle-hooks/after-view-anim.gif' alt="AfterView")
:marked
  Notice that Angular frequently calls `AfterViewChecked`, often when there are no changes of interest.
  Write lean hook methods to avoid performance problems.

.l-main-section
:marked
  ## AfterContent
  The *AfterContent* sample explores the `AfterContentInit` and `AfterContentChecked` hooks that Angular calls
  *after* Angular projects external content into the component.

  ### Content projection
  *Content projection* is a way to import HTML content from outside the component and insert that content
  into the component's template in a designated spot.

.l-sub-section
  :marked
    Angular 1 developers know this technique as *transclusion*.

:marked
  Consider this variation on the [previous _AfterView_](#afterview) example.
  This time, instead of including the child view within the template, it imports the content from
  the `AfterContentComponent`'s parent. Here's the parent's template.
+makeExample('lifecycle-hooks/ts/app/after-content.component.ts', 'parent-template', 'AfterContentParentComponent (template excerpt)')(format=".")
:marked
  Notice that the `<my-child>` tag is tucked between the `<after-content>` tags.
  Never put content between a component's element tags *unless you intend to project that content
  into the component*.

  Now look at the component's template:
+makeExample('lifecycle-hooks/ts/app/after-content.component.ts', 'template', 'AfterContentComponent (template)')(format=".")
:marked
  The `<ng-content>` tag is a *placeholder* for the external content.
  It tells Angular where to insert that content.
  In this case, the projected content is the `<my-child>` from the parent.
figure.image-display
  img(src='/resources/images/devguide/lifecycle-hooks/projected-child-view.png' width="230" alt="Projected Content")
:marked
.l-sub-section
  :marked
    The tell-tale signs of *content projection* are (a) HTML between component element tags
    and (b) the presence of `<ng-content>` tags in the component's template.
:marked
  ### AfterContent hooks
  *AfterContent* hooks are similar to the *AfterView* hooks. 
  The key difference is in the child component

  * The *AfterView* hooks concern `ViewChildren`, the child components whose element tags
  appear *within* the component's template.

  * The *AfterContent* hooks concern `ContentChildren`, the child components that Angular
  projected into the component.

  The following *AfterContent* hooks take action based on changing values in a  *content child*
  which can only be reached by querying for it via the property decorated with
  [@ContentChild](../api/core/index/ContentChild-decorator.html).

+makeExample('lifecycle-hooks/ts/app/after-content.component.ts', 'hooks', 'AfterContentComponent (class excerpts)')(format=".")

:marked
   ### No unidirectional flow worries with _AfterContent..._

   This component's `doSomething` method update's the component's data-bound `comment` property immediately.
   There's no [need to wait](#wait-a-tick).

   Recall that Angular calls both *AfterContent* hooks before calling either of the *AfterView* hooks.
   Angular completes composition of the projected content *before* finishing the composition of this component's view.
   There is a small window between the `AfterContent...` and `AfterView...` hooks to modify the host view.