docs(component-communication): copy edits and update TOCs (#3417)

This commit is contained in:
Kapunahele Wong 2017-03-23 18:11:48 -04:00 committed by Ward Bell
parent 3ba79f9eb5
commit 9fb57f6b98
1 changed files with 107 additions and 113 deletions

View File

@ -13,21 +13,14 @@ include ../_util-fns
<a id="toc"></a>
:marked
## Table of contents
# Contents
[Pass data from parent to child with input binding](#parent-to-child)
- [Pass data from parent to child with input binding](#parent-to-child)
- [Intercept input property changes with a setter](#parent-to-child-setter)
- [Intercept input property changes with `ngOnChanges()`](#parent-to-child-on-changes)
- [Parent calls an `@ViewChild()`](#parent-to-view-child)
- [Parent and children communicate via a service](#bidirectional-service)
[Intercept input property changes with a setter](#parent-to-child-setter)
[Intercept input property changes with *ngOnChanges*](#parent-to-child-on-changes)
[Parent listens for child event](#child-to-parent)
[Parent interacts with child via a *local variable*](#parent-to-child-local-var)
[Parent calls a *ViewChild*](#parent-to-view-child)
[Parent and children communicate via a service](#bidirectional-service)
:marked
**See the <live-example name="cb-component-communication"></live-example>**.
@ -45,7 +38,7 @@ include ../_util-fns
The second `@Input` aliases the child component property name `masterName` as `'master'`.
The `HeroParentComponent` nests the child `HeroChildComponent` inside an `*ngFor` repeater,
binding its `master` string property to the child's `master` alias
binding its `master` string property to the child's `master` alias,
and each iteration's `hero` instance to the child's `hero` property.
+makeExample('cb-component-communication/ts/src/app/hero-parent.component.ts')
@ -98,14 +91,14 @@ figure.image-display
.l-main-section
<a id="parent-to-child-on-changes"></a>
:marked
## Intercept input property changes with *ngOnChanges*
## Intercept input property changes with *ngOnChanges()*
Detect and act upon changes to input property values with the `ngOnChanges` method of the `OnChanges` lifecycle hook interface.
Detect and act upon changes to input property values with the `ngOnChanges()` method of the `OnChanges` lifecycle hook interface.
.l-sub-section
:marked
May prefer this approach to the property setter when watching multiple, interacting input properties.
You may prefer this approach to the property setter when watching multiple, interacting input properties.
Learn about `ngOnChanges` in the [LifeCycle Hooks](../guide/lifecycle-hooks.html) chapter.
Learn about `ngOnChanges()` in the [LifeCycle Hooks](../guide/lifecycle-hooks.html) chapter.
:marked
This `VersionChildComponent` detects changes to the `major` and `minor` input properties and composes a log message reporting these changes:
@ -148,15 +141,15 @@ figure.image-display
+makeExample('cb-component-communication/ts/src/app/voter.component.ts')
:marked
Clicking a button triggers emission of a `true` or `false` (the boolean *payload*).
Clicking a button triggers emission of a `true` or `false`, the boolean *payload*.
The parent `VoteTakerComponent` binds an event handler (`onVoted`) that responds to the child event
payload (`$event`) and updates a counter.
The parent `VoteTakerComponent` binds an event handler called `onVoted()` that responds to the child event
payload `$event` and updates a counter.
+makeExample('cb-component-communication/ts/src/app/votetaker.component.ts')
:marked
The framework passes the event argument &mdash; represented by `$event` &mdash; to the handler method,
The framework passes the event argument&mdash;represented by `$event`&mdash;to the handler method,
and the method processes it:
figure.image-display
@ -177,30 +170,30 @@ figure.image-display
## Parent interacts with child via *local variable*
A parent component cannot use data binding to read child properties
or invoke child methods. We can do both
or invoke child methods. You can do both
by creating a template reference variable for the child element
and then reference that variable *within the parent template*
as seen in the following example.
<a id="countdown-timer-example"></a>
We have a child `CountdownTimerComponent` that repeatedly counts down to zero and launches a rocket.
The following is a child `CountdownTimerComponent` that repeatedly counts down to zero and launches a rocket.
It has `start` and `stop` methods that control the clock and it displays a
countdown status message in its own template.
+makeExample('cb-component-communication/ts/src/app/countdown-timer.component.ts')
:marked
Let's see the `CountdownLocalVarParentComponent` that hosts the timer component.
The `CountdownLocalVarParentComponent` that hosts the timer component is as follows:
+makeExample('cb-component-communication/ts/src/app/countdown-parent.component.ts', 'lv')
:marked
The parent component cannot data bind to the child's
`start` and `stop` methods nor to its `seconds` property.
We can place a local variable (`#timer`) on the tag (`<countdown-timer>`) representing the child component.
That gives us a reference to the child component itself and the ability to access
You can place a local variable, `#timer`, on the tag `<countdown-timer>` representing the child component.
That gives you a reference to the child component and the ability to access
*any of its properties or methods* from within the parent template.
In this example, we wire parent buttons to the child's `start` and `stop` and
use interpolation to display the child's `seconds` property.
This example wires parent buttons to the child's `start` and `stop` and
uses interpolation to display the child's `seconds` property.
Here we see the parent and child working together.
@ -223,52 +216,53 @@ a(id="countdown-tests")
.l-main-section
<a id="parent-to-view-child"></a>
:marked
## Parent calls a *ViewChild*
## Parent calls an _@ViewChild()_
The *local variable* approach is simple and easy. But it is limited because
the parent-child wiring must be done entirely within the parent template.
The parent component *itself* has no access to the child.
We can't use the *local variable* technique if an instance of the parent component *class*
You can't use the *local variable* technique if an instance of the parent component *class*
must read or write child component values or must call child component methods.
When the parent component *class* requires that kind of access,
we ***inject*** the child component into the parent as a *ViewChild*.
***inject*** the child component into the parent as a *ViewChild*.
We'll illustrate this technique with the same [Countdown Timer](#countdown-timer-example) example.
We won't change its appearance or behavior.
The following example illustrates this technique with the same
[Countdown Timer](#countdown-timer-example) example.
Neither its appearance nor its behavior will change.
The child [CountdownTimerComponent](#countdown-timer-example) is the same as well.
.l-sub-section
:marked
We are switching from the *local variable* to the *ViewChild* technique
solely for the purpose of demonstration.
The switch from the *local variable* to the *ViewChild* technique
is solely for the purpose of demonstration.
:marked
Here is the parent, `CountdownViewChildParentComponent`:
+makeExample('cb-component-communication/ts/src/app/countdown-parent.component.ts', 'vc')
:marked
It takes a bit more work to get the child view into the parent component *class*.
We import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook.
First, you have to import references to the `ViewChild` decorator and the `AfterViewInit` lifecycle hook.
We inject the child `CountdownTimerComponent` into the private `timerComponent` property
Next, inject the child `CountdownTimerComponent` into the private `timerComponent` property
via the `@ViewChild` property decoration.
The `#timer` local variable is gone from the component metadata.
Instead we bind the buttons to the parent component's own `start` and `stop` methods and
Instead, bind the buttons to the parent component's own `start` and `stop` methods and
present the ticking seconds in an interpolation around the parent component's `seconds` method.
These methods access the injected timer component directly.
The `ngAfterViewInit` lifecycle hook is an important wrinkle.
The `ngAfterViewInit()` lifecycle hook is an important wrinkle.
The timer component isn't available until *after* Angular displays the parent view.
So we display `0` seconds initially.
So it displays `0` seconds initially.
Then Angular calls the `ngAfterViewInit` lifecycle hook at which time it is *too late*
to update the parent view's display of the countdown seconds.
Angular's unidirectional data flow rule prevents us from updating the parent view's
in the same cycle. We have to *wait one turn* before we can display the seconds.
Angular's unidirectional data flow rule prevents updating the parent view's
in the same cycle. The app has to *wait one turn* before it can display the seconds.
We use `setTimeout` to wait one tick and then revise the `seconds` method so
Use `setTimeout()` to wait one tick and then revise the `seconds()` method so
that it takes future values from the timer component.
### Test it
@ -304,12 +298,12 @@ a(id="countdown-tests")
.l-sub-section
:marked
Notice that we capture the `subscription` and unsubscribe when the `AstronautComponent` is destroyed.
Notice that this example captures the `subscription` and `unsubscribe()` when the `AstronautComponent` is destroyed.
This is a memory-leak guard step. There is no actual risk in this app because the
lifetime of a `AstronautComponent` is the same as the lifetime of the app itself.
That *would not* always be true in a more complex application.
We do not add this guard to the `MissionControlComponent` because, as the parent,
You don't add this guard to the `MissionControlComponent` because, as the parent,
it controls the lifetime of the `MissionService`.
:marked
The *History* log demonstrates that messages travel in both directions between
@ -323,7 +317,7 @@ figure.image-display
### Test it
Tests click buttons of both the parent `MissionControlComponent` and the `AstronautComponent` children
and verify that the *History* meets expectations:
and verify that the history meets expectations:
+makeExample('cb-component-communication/e2e-spec.ts', 'bidirectional-service')