docs: update prose for the `let` change to ngFor

This commit is contained in:
Filipe Silva 2016-04-28 11:18:52 -07:00 committed by Ward Bell
parent 216120daba
commit ebc022e475
9 changed files with 74 additions and 90 deletions

View File

@ -97,12 +97,12 @@ table(width="100%")
### Local variables
+makeExample('cb-a1-a2-quick-reference/ts/app/app.component.html', 'local')(format="." )
:marked
In Angular 2, we have true local template variables that are explicitly defined using the hash (#) symbol.
In Angular 2, we have true template reference variables that are explicitly defined using the hash (#) symbol.
Using a local template variable, we can move data between elements in the template. We can use the local template
Using a template reference variable, we can move data between elements in the template. We can use the template reference
variable on the same element, on sibling elements, or on any child elements.
For more information see [Template Syntax](../guide/template-syntax.html#local-vars).
For more information see [Template Syntax](../guide/template-syntax.html#ref-vars).
:marked
[Back to top](#top)

View File

@ -180,7 +180,7 @@ parent-to-child-local-var
A parent component cannot use data binding to read child properties
or invoke child methods. We can do both
by creating a template local variable for the child element
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.

View File

@ -140,12 +140,12 @@ figure.image-display
.alert.is-important
:marked
Don't forget the leading asterisk (\*) in `*ngFor`. It is an essential part of the syntax.
Learn more about this and `NgFor` in the [Template Syntax](./template-syntax.html#ngFor) chapter.
Learn more about this and `ngFor` in the [Template Syntax](./template-syntax.html#ngFor) chapter.
:marked
Notice the `#hero` in the `NgFor` double-quoted instruction.
The `#hero` is a [local template variable](./template-syntax.html#local-vars) declaration.
The `#` prefix declares a local variable name named `hero`.
Notice the `#hero` in the `ngFor` double-quoted instruction.
The `#hero` is a [template input variable](./template-syntax.html#ngForMicrosyntax) declaration.
The `let` keyword declares a local variable name named `hero`.
Angular duplicates the `<li>` for each item in the list, setting the `hero` variable
to the item (the hero) in the current iteration. Angular uses that variable as the

View File

@ -236,7 +236,7 @@ ol
:marked
We are repeating the `<options>` tag for each power in the list of Powers.
The `#p` local template variable is a different power in each iteration;
The `p` template input variable is a different power in each iteration;
we display its name using the interpolation syntax with the double-curly-braces.
<a id="ngModel"></a>
@ -408,7 +408,7 @@ table
td <code>ng-valid</code>
td <code>ng-invalid</code>
:marked
Let's add a temporary [local template variable](./template-syntax.html#local-vars) named **spy**
Let's add a temporary [template reference variable](./template-syntax.html#ref-vars) named **spy**
to the "Name" `<input>` tag and use the spy to display those classes.
+makeExample('forms/ts/app/hero-form.component.html', 'ngControl-2','app/hero-form.component.html (excerpt)')(format=".")
@ -464,7 +464,7 @@ figure.image-display
:marked
To achieve this effect we extend the `<input>` tag with
1. a [local template variable](./template-syntax.html#local-vars)
1. a [template reference variable](./template-syntax.html#ref-vars)
1. the "*is required*" message in a nearby `<div>` which we'll display only if the control is invalid.
Here's how we do it for the *name* input box:
@ -472,7 +472,7 @@ figure.image-display
'name-with-error-msg',
'app/hero-form.component.html (excerpt)')(format=".")
:marked
We need a template local variable to access the input box's Angular control from within the template.
We need a template reference variable to access the input box's Angular control from within the template.
Here we created a variable called `name` and gave it the value "ngForm".
.l-sub-section
:marked
@ -607,7 +607,7 @@ figure.image-display
wire the button's enable/disabled state to the form's validity without Angular's help?
For us, it was as simple as
1. Define a template local variable on the (enhanced) form element
1. Define a template reference variable on the (enhanced) form element
2. Reference that variable in a button some 50 lines away.
.l-main-section

View File

@ -82,7 +82,7 @@ figure.image-display
:marked
Beneath the heroes is an input box and an *Add Hero* button where we can enter the names of new heroes
and add them to the database.
We use a [local template variable](template-syntax.html#local-vars), `newHero`, to access the
We use a [template reference variable](template-syntax.html#ref-vars), `newHero`, to access the
value of the input box in the `(click)` event binding.
When the user clicks the button, we pass that value to the component's `addHero` method and then
clear it to make ready for a new hero name.

View File

@ -212,10 +212,9 @@ figure.image-display
and move the directive onto the `<template>`.
There are extra nuances stemming from
Angular's [ngFor micro-syntax](template-syntax.html#ngfor-micro-syntax) which expands
Angular's [ngFor micro-syntax](template-syntax.html#ngForMicrosyntax) which expands
into an additional `ngForOf` property binding (the iterable) and
the `#hero` [local template variable](template-syntax.html#local-vars)
(the current item in each iteration).
the `hero` template input variable (the current item in each iteration).
<a id="unless"></a>
.l-main-section

View File

@ -24,7 +24,7 @@ include ../_util-fns
* [NgSwitch](#ngSwitch)
* [NgFor](#ngFor)
* [* and &lt;template>](#star-template)
* [Local template variables](#local-vars)
* [Template reference variables](#ref-vars)
* [Input and output properties](#inputs-outputs)
* [Template expression operators](#expression-operators)
* [pipe](#pipe)
@ -148,7 +148,7 @@ include ../_util-fns
the template expression usually references that component.
The expression context can include objects other than the component.
A [local template variable](#local-vars) is one such alternative context object.
A [template reference variable](#ref-vars) is one such alternative context object.
// #enddocregion template-expressions-context
// #docregion template-expressions-guidelines
@ -251,7 +251,7 @@ include ../_util-fns
The *onSave* in `(click)="onSave()"` is sure to be a method of the data-bound component instance.
The statement context may include an object other than the component.
A [local template variable](#local-vars) is one such alternative context object.
A [template reference variable](#ref-vars) is one such alternative context object.
We'll frequently see the reserved `$event` symbol in event binding statements,
representing the "message" or "payload" of the raised event.
@ -1186,17 +1186,16 @@ figure.image-display
// #enddocregion directives-ngFor-3
// #docregion directives-ngFor-4
.l-sub-section
:marked
#### NgFor microsyntax
The string assigned to `*ngFor` is not a [template expression](#template-expressions).
Its a *microsyntax* &mdash; a little language of its own that Angular interprets. In this example, the string "#hero of heroes" means:
<a id="ngForMicrosyntax"></a>
:marked
#### NgFor microsyntax
The string assigned to `*ngFor` is not a [template expression](#template-expressions).
Its a *microsyntax* &mdash; a little language of its own that Angular interprets. In this example, the string "let hero of heroes" means:
>*Take each hero in the `heroes` array, store it in the local `hero` variable, and make it available to the templated HTML
for each iteration.*
>*Take each hero in the `heroes` array, store it in the local `hero` variable, and make it available to the templated HTML
for each iteration.*
Angular translates this instruction into a new set of elements and bindings.
Well talk about this in the next section.
Angular translates this instruction into a new set of elements and bindings.
// #enddocregion directives-ngFor-4
// #docregion directives-ngFor-5
:marked
@ -1204,8 +1203,13 @@ figure.image-display
stamping out instances of the element to which it is applied.
Angular creates a fresh instance of the template for each hero in the array.
The hash (`#`) character before "hero" creates a [local template variable](#local-vars) called `hero`.
The `let` keyword before "hero" creates a template input variable called `hero`.
.alert.is-critical
:marked
A template input variable is **not** the same as a [template reference variable](#ref-vars)!
:marked
We use this variable within the template to access a heros properties,
as were doing in the interpolation.
We can also pass the variable in a binding to a component element,
@ -1216,7 +1220,7 @@ figure.image-display
:marked
#### NgFor with index
The `ngFor` directive supports an optional `index` that increases from 0 to the length of the array for each iteration.
We can capture the index in a local template variable and use it in our template.
We can capture the index in a template input variable and use it in our template.
The next example captures the index in a variable named `i`, using it to stamp out rows like "1 - Hercules Son of Zeus".
// #enddocregion directives-ngFor-6
@ -1363,79 +1367,60 @@ figure.image-display
Using the `*ngFor` syntax is much easier than writing out this expanded HTML ourselves.
// #enddocregion star-template-ngFor-4
// #docregion local-vars-1
<a id="local-vars"></a>
// #docregion ref-vars-1
<a id="ref-vars"></a>
.l-main-section
:marked
## Local template variables
## Template reference variables
A **local template variable** is a vehicle for moving data across element lines.
A **Template reference variable** is a reference to an DOM element or directive within a template.
We've seen `#hero` used to declare a local template variable several times in this chapter,
most prominently when writing [NgFor](#ngFor) repeaters.
It can be used with native DOM elements but also with Angular 2 components - in fact, it will work with any custom web component.
In [* and &lt;templates>](#star-template), we learned how Angular expands
an `*ngFor` on a component tag into a `<template>` that wraps the component.
// #enddocregion local-vars-1
+makeExample('template-syntax/ts/app/app.component.html', 'Template-4')(format=".")
// #docregion local-vars-2
// #docregion ref-vars-refs
:marked
The hash (`#`) prefix to "hero" means that we're defining a `hero` variable.
### Referencing a template reference variable
We can reference a template reference variable on the same element, on a sibling element, or on
any child elements.
Here are two other examples of creating and consuming a Template reference variable:
// #enddocregion ref-vars-refs
+makeExample('template-syntax/ts/app/app.component.html', 'ref-phone')(format=".")
// #docregion ref-vars-value
:marked
The hash (`#`) prefix to "phone" means that we're defining a `phone` variable.
.l-sub-section
:marked
Folks who don't like using the `#` character can use its canonical alternative,
the `var-` prefix. For example, we can declare the our `hero` variable using
either `#hero` or `var-hero`.
:marked
We define `hero` on the outer `<template>` element, where it becomes the current hero item
as Angular iterates through the list of heroes.
the `ref-` prefix. For example, we can declare the our `phone` variable using
either `#phone` or `ref-phone`.
The `hero` variable appears again in the binding on the inner `<hero-detail>` component element.
That's how each instance of the `<hero-detail>` gets its hero.
// #enddocregion local-vars-2
// #docregion local-vars-refs
:marked
### Referencing a local template variable
We can reference a local template variable on the same element, on a sibling element, or on
any child elements.
Here are two other examples of creating and consuming a local template variable:
// #enddocregion local-vars-refs
+makeExample('template-syntax/ts/app/app.component.html', 'var-phone')(format=".")
// #docregion local-vars-value
:marked
### How a variable gets its value
The value assigned to a variable depends upon the context.
When a directive is present on the element, as it is in the earlier NgFor `<hero-detail>` component example,
the directive sets the value. Accordingly, the `NgFor` directive
sets the `hero` variable to a hero item from the `heroes` array.
When no directive is present, as in phone and fax examples,
Angular sets the variable's value to the element on which it was defined.
We defined these variables on the `input` elements.
Were passing those `input` element objects across to the
button elements, where they're used in arguments to the `call` methods in the event bindings.
// #enddocregion local-vars-value
// #enddocregion ref-vars-value
// #docregion local-vars-form-1
// #docregion ref-vars-form-1
:marked
### NgForm and local template variables
Let's look at one final example: a form, the poster child for local template variables.
### NgForm and template reference variables
Let's look at one final example: a form, the poster child for template reference variables.
The HTML for a form can be quite involved, as we saw in the [Forms](forms.html) chapter.
The following is a *simplified* example &mdash; and it's not simple at all.
// #enddocregion local-vars-form-1
+makeExample('template-syntax/ts/app/app.component.html', 'var-form')(format=".")
// #docregion local-vars-form-2
// #enddocregion ref-vars-form-1
+makeExample('template-syntax/ts/app/app.component.html', 'ref-form')(format=".")
// #docregion ref-vars-form-2
:marked
A local template variable, `theForm`, appears three times in this example, separated
A template reference variable, `theForm`, appears three times in this example, separated
by a large amount of HTML.
// #enddocregion local-vars-form-2
+makeExample('template-syntax/ts/app/app.component.html', 'var-form-a')(format=".")
// #docregion local-vars-form-3
// #enddocregion ref-vars-form-2
+makeExample('template-syntax/ts/app/app.component.html', 'ref-form-a')(format=".")
// #docregion ref-vars-form-3
:marked
What is the value of `theForm`?
@ -1447,7 +1432,7 @@ figure.image-display
This explains how we can disable the submit button by checking `theForm.form.valid`
and pass an object with rich information to the parent component's `onSubmit` method.
// #enddocregion local-vars-form-3
// #enddocregion ref-vars-form-3
// #docregion inputs-outputs-1
<a id="inputs-outputs"></a>

View File

@ -82,18 +82,18 @@ figure.image-display
.l-main-section
:marked
## Get user input from a local template variable
## Get user input from a template reference variable
There's another way to get the user data without the `$event` variable.
Angular has a syntax feature called [**local template variables**](./template-syntax.html#local-vars).
Angular has a syntax feature called [**template reference variables**](./template-syntax.html#ref-vars).
These variables grant us direct access to an element.
We declare a local template variable by preceding an identifier with a hash/pound character (#).
We declare a template reference variable by preceding an identifier with a hash/pound character (#).
Here's an example of using a local template variable
Here's an example of using a template reference variable
to implement a clever keystroke loopback in an ultra-simple template.
+makeExample('user-input/ts/app/loop-back.component.ts', 'loop-back-component', 'app/loop-back.component.ts')(format=".")
:marked
We've declared a template local variable named `box` on the `<input>` element.
We've declared a template reference variable named `box` on the `<input>` element.
The `box` variable is a reference to the `<input>` element itself, which means we can
grab the input element's `value` and display it
with interpolation between `<p>` tags.
@ -116,7 +116,7 @@ figure.image-display
We're binding to the number 0, the shortest statement we can think of.
That is all it takes to keep Angular happy. We said it would be clever!
:marked
That local template variable is intriguing. It's clearly easier to get to the textbox with that
That template reference variable is intriguing. It's clearly easier to get to the textbox with that
variable than to go through the `$event` object. Maybe we can rewrite our previous
keyup example so that it uses the variable to get the user's input. Let's give it a try.
+makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-2' ,'app/keyup.components.ts (v2)')(format=".")

View File

@ -105,10 +105,10 @@ code-example(format="." language="bash").
“*take each hero in the `heroes` array, store it in the local `hero` variable,
and make it available to the corresponding template instance*”.
The `#` prefix before "hero" identifies the `hero` as a local template variable.
The `let` keyword before "hero" identifies the `hero` as a template input variable.
We can reference this variable within the template to access a heros properties.
Learn more about `ngFor` and local template variables in the
Learn more about `ngFor` and template input variables in the
[Displaying Data](../guide/displaying-data.html#ngFor) and
[Template Syntax](../guide/template-syntax.html#ngFor) chapters.
@ -167,7 +167,7 @@ code-example(format="." language="bash").
:marked
The parenthesis identify the `<li>` elements `click` event as the target.
The expression to the right of the equal sign calls the `AppComponent` method, `onSelect()`,
passing the local template variable `hero` as an argument.
passing the template input variable `hero` as an argument.
Thats the same `hero` variable we defined previously in the `ngFor`.
.l-sub-section
:marked