diff --git a/public/docs/ts/latest/guide/template-syntax.jade b/public/docs/ts/latest/guide/template-syntax.jade index b95c50f2e1..0c5318f823 100644 --- a/public/docs/ts/latest/guide/template-syntax.jade +++ b/public/docs/ts/latest/guide/template-syntax.jade @@ -542,7 +542,7 @@ table // #docregion property-binding-7 :marked ### Binding target - A name between enclosing square brackets identifies the target property. The target property in the following code is the image element’s `src` property. + a id between enclosing square brackets identifies the target property. The target property in the following code is the image element’s `src` property. // #enddocregion property-binding-7 +makeExample('template-syntax/ts/app/app.component.html', 'property-binding-1')(format=".") @@ -901,7 +901,7 @@ code-example(format="", language="html"). // #docregion ngModel-1 .l-main-section :marked - + ## Two-way binding with NgModel When developing data entry forms, we often want to both display a data property and update that property when the user makes changes. @@ -929,15 +929,22 @@ code-example(format="", language="html"). +makeExample('template-syntax/ts/app/app.component.html', 'without-NgModel')(format=".") // #docregion ngModel-4 :marked - That’s cumbersome. Who can remember what element property to set and what event reports user changes? + That’s cumbersome. Who can remember which element property to set and what event reports user changes? How do we extract the currently displayed text from the input box so we can update the data property? Who wants to look that up each time? - That `ngModel` directive hides these onerous details. It wraps the element’s `value` property, listens to the `input` event, - and raises its own event with the changed text ready for us to consume. + That `ngModel` directive hides these onerous details behind its own `ngModel` input and `ngModelChange` output properties. // #enddocregion ngModel-4 +makeExample('template-syntax/ts/app/app.component.html', 'NgModel-3')(format=".") // #docregion ngModel-5 +.l-sub-section + :marked + The `ngModel` input property sets the element's value property and the `ngModelChange` output property + listens for changes to the element's value. + The details are specific to each kind of element and therefore the `NgModel` directive only works for elements + that implement one of a few patterns such as the input box's `value` property and `change` event. + We can't simply apply `[(ngModel)]` to our custom components unless we write them to conform. + :marked That’s an improvement, but it could be better. @@ -949,16 +956,18 @@ code-example(format="", language="html"). // #docregion ngModel-6 .l-sub-section :marked - Internally, Angular maps the term `ngModel` to an `ngModel` input property and an - `ngModelChange` output property. - That’s a specific example of a more general pattern in which Angular matches `[(x)]` to an `x` input property - for property binding and an `xChange` output property for event binding. + `[(ngModel)]` is a specific example of a more general pattern in which Angular "de-sugars" the `[(x)]` syntax + into an `x` input property for property binding and an `xChange` output property for event binding. + Angular constructs the event property binding's template statement by appending `=$event` + to the literal string of the template expression. + code-example(format="." ). + [(x)]="hero.name" <==> [x]="hero.name" (xChange)="hero.name=$event" + :marked Is `[(ngModel)]` all we need? Is there ever a reason to fall back to its expanded form? - Well, `NgModel` can only set the target property. - What if we need to do something more or something different when the user changes the value? - Then we need to use the expanded form. + The `[( )]` syntax can only set the data-bound property when the value changes. + If we need to do something more or something different, we need to write the expanded form ourselves. Let's try something silly like forcing the input value to uppercase: // #enddocregion ngModel-6 @@ -973,7 +982,7 @@ figure.image-display // #docregion directives-1 .l-main-section :marked - + ## Built-in directives Earlier versions of Angular included over seventy built-in directives. @@ -1249,8 +1258,8 @@ figure.image-display // #enddocregion directives-ngForTrackBy-3 // #docregion star-template - - + + .l-main-section :marked ## * and <template>