`. The spy's `ngOnInit` logs that event.
- We see a new entry for each hero.
The *Reset* button clears the `heroes` list.
- Angular removes all hero divs from the DOM and destroys their spy directives at the same time.
+ Angular removes all hero `
` 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.
- Let's see why we need them.
### OnInit
- We turn to `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
+ 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
- An `ngOnInit` often fetches data for the component as shown in the
- [Tutorial](../tutorial/toh-pt4.html#oninit) and [HTTP](server-communication.html#oninit) chapters.
-
- We don't fetch data in a component constructor. Why?
- Because experienced developers agree that components should be cheap and safe to construct.
- We shouldn't worry that a new component will try to contact a remote server when
- created under test or before we decide to display it.
- Constructors should do no more than set the initial local variables to simple values.
-
- When a component must start working _soon_ after creation,
- we can count on Angular to call the `ngOnInit` method to jumpstart it.
- That's where the heavy initialization logic belongs.
-
- Remember also that a directive's data-bound input properties are not set until _after construction_.
- That's a problem if we need to initialize the directive based on those properties.
- They'll have been set when our `ngOninit` runs.
+ Experienced developers agree that components should be cheap and safe to construct.
.l-sub-section
:marked
- Our first opportunity to access those properties is the `ngOnChanges` method which
- Angular calls before `ngOnInit`. But Angular calls `ngOnChanges` many times after that.
+ 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 this component is going away.
+ 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.
- We risk memory leaks if we neglect to do so.
+ You risk memory leaks if you neglect to do so.
.l-main-section
:marked
## OnChanges
- We monitor the `OnChanges` hook in this example.
Angular calls its `ngOnChanges` method whenever it detects changes to ***input properties*** of the component (or directive).
-
- Here is our implementation of the hook.
+ 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 with the current and previous property values.
- We iterate over the changed properties and log them.
+ [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 input properties for our example `OnChangesComponent` are `hero` and `power`.
+ The example component, `OnChangesComponent`, has two input properties: `hero` and `power`.
+makeExample('lifecycle-hooks/ts/app/on-changes.component.ts', 'inputs')(format=".")
:marked
- The parent binds to them like this:
+ 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 we make changes.
+ 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
- We see log entries as the string value of the *power* property changes. But the `ngOnChanges` did not catch changes to `hero.name`
+ 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.
@@ -435,39 +410,30 @@ figure.image-display
.l-main-section
:marked
## DoCheck
- We can use the `DoCheck` hook to detect and act upon changes that Angular doesn't catch on its own.
+ Use the `DoCheck` hook to detect and act upon changes that Angular doesn't catch on its own.
.l-sub-section
:marked
- With this method we can detect a change that Angular overlooked.
- What we do with that information to refresh the display is a separate matter.
+ Use this method to detect a change that Angular overlooked.
:marked
- The *DoCheck* sample extends the *OnChanges* sample with this implementation of `DoCheck`:
+ 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
- We manually check everything that we care about, capturing and comparing against previous values.
- We write a special message to the log when there are no substantive changes
- to the hero or the power so we can keep an eye on the method's performance characteristics.
-
- The results are illuminating:
+ 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
- We now are able to detect when the hero's `name` has changed. But we must be careful.
-
- The `ngDoCheck` hook is called with enormous frequency —
+ 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 —
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 may suffer.
-
-.l-sub-section
- :marked
- We also see that the `ngOnChanges` method is called in contradiction of the
- [incorrect API documentation](../api/core/index/DoCheck-class.html).
+ Clearly our implementation must be very lightweight or the user experience will suffer.
.l-main-section
:marked
@@ -482,11 +448,11 @@ figure.image-display
+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 we can only reach by querying for the child view via the property decorated with
- [@ViewChild](../api/core/index/ViewChild-var.html).
+ 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=".")
-.a(id="wait-a-tick")
+#wait-a-tick
:marked
### Abide by the unidirectional data flow rule
The `doSomething` method updates the screen when the hero name exceeds 10 characters.
@@ -495,14 +461,14 @@ figure.image-display
:marked
Why does the `doSomething` method wait a tick before updating `comment`?
- Because we must adhere to Angular's unidirectional data flow rule which says that
- we may not update the view *after* it has been composed.
- Both hooks fire after the component's view has been composed.
+ 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 we update component's data-bound `comment` property immediately (try it!).
+ 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` methods, which are implemented by a call to `setTimeout`, postpone the update one turn of the of the browser's JavaScript cycle ... and that's long enough.
+ 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
@@ -527,22 +493,20 @@ figure.image-display
Angular 1 developers know this technique as *transclusion*.
:marked
- We'll illustrate with a variation on the [previous](#afterview) example
- whose behavior and output is almost the same.
-
- This time, instead of including the child view within the template, we'll import it from
+ 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 `
` tag is tucked between the `` tags.
- We never put content between a component's element tags *unless we intend to project that content
+ 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 `` tag is a *placeholder* for the external content.
- They tell Angular where to insert that content.
+ It tells Angular where to insert that content.
In this case, the projected content is the `` from the parent.
figure.image-display
img(src='/resources/images/devguide/lifecycle-hooks/projected-child-view.png' width="230" alt="Projected Content")
@@ -553,8 +517,8 @@ figure.image-display
and (b) the presence of `` tags in the component's template.
:marked
### AfterContent hooks
- *AfterContent* hooks are similar to the *AfterView* hooks. The key difference is the kind of child component
- that we're looking for.
+ *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.
@@ -563,17 +527,18 @@ figure.image-display
projected into the component.
The following *AfterContent* hooks take action based on changing values in a *content child*
- which we can only reach by querying for it via the property decorated with
- [@ContentChild](../api/core/index/ContentChild-var.html).
+ 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=".")
+a#no-unidirectional-flow-worries
:marked
- ### No unidirectional flow worries
+ ### 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.
- We still have a window of opportunity to modify that view.
+ There is a small window between the `AfterContent...` and `AfterView...` hooks to modify the host view.
diff --git a/public/docs/ts/latest/guide/lifecycle-hooks.jade b/public/docs/ts/latest/guide/lifecycle-hooks.jade
index d8a6de909e..00283d1b6d 100644
--- a/public/docs/ts/latest/guide/lifecycle-hooks.jade
+++ b/public/docs/ts/latest/guide/lifecycle-hooks.jade
@@ -7,7 +7,7 @@ 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.
+ 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.
@@ -17,16 +17,13 @@ figure
A directive has the same set of lifecycle hooks, minus the hooks that are specific to component content and views.
- ## Table of Contents
- * [Overview](#hooks-overview)
-
- * [Each hook's purpose and timing](#hooks-purpose-timing)
+ifDocsFor('ts|js')
:marked
+ ## Table of Contents
+ * [Overview](#hooks-overview)
+ * [Each hook's purpose and timing](#hooks-purpose-timing)
* [Interfaces are optional (technically)](#interface-optional)
- :marked
* [Other Angular lifecycle hooks](#other-lifecycle-hooks)
-
* [The lifecycle sample](#the-sample)
* [All](#peek-a-boo)
* [Spying OnInit and OnDestroy](#spy)
@@ -40,7 +37,7 @@ figure
a#hooks-overview
.l-main-section
:marked
- ## Component lifecycle Hooks
+ ## 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
@@ -58,8 +55,8 @@ 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:
+ *After* creating a component/directive by calling its constructor, Angular
+ calls the lifecycle hook methods in the following sequence at specific moments:
table(width="100%")
col(width="20%")
col(width="80%")
@@ -535,6 +532,7 @@ figure.image-display
+makeExample('lifecycle-hooks/ts/app/after-content.component.ts', 'hooks', 'AfterContentComponent (class excerpts)')(format=".")
+a#no-unidirectional-flow-worries
:marked
### No unidirectional flow worries with _AfterContent..._