docs: update prose for the `let` change to ngFor
This commit is contained in:
parent
216120daba
commit
ebc022e475
|
@ -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)
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -24,7 +24,7 @@ include ../_util-fns
|
|||
* [NgSwitch](#ngSwitch)
|
||||
* [NgFor](#ngFor)
|
||||
* [* and <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).
|
||||
It’s a *microsyntax* — 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).
|
||||
It’s a *microsyntax* — 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.
|
||||
We’ll 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 hero’s properties,
|
||||
as we’re 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 <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.
|
||||
We’re 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 — 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>
|
||||
|
|
|
@ -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=".")
|
||||
|
|
|
@ -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 hero’s 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>` element’s `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.
|
||||
That’s the same `hero` variable we defined previously in the `ngFor`.
|
||||
.l-sub-section
|
||||
:marked
|
||||
|
|
Loading…
Reference in New Issue