From 06fa5843ec46df5a9b1cdb97156a4486ecdeae6b Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Mon, 18 Jan 2016 23:54:27 -0800 Subject: [PATCH] docs(template-syntax): Clarify input/output aliasing syntax --- .../template-syntax/ts/app/app.component.html | 8 ++-- .../ts/app/my-click.directive.ts | 14 +++++-- .../docs/ts/latest/guide/template-syntax.jade | 37 ++++++++++--------- 3 files changed, 34 insertions(+), 25 deletions(-) diff --git a/public/docs/_examples/template-syntax/ts/app/app.component.html b/public/docs/_examples/template-syntax/ts/app/app.component.html index 5a567265fb..f983716ee4 100644 --- a/public/docs/_examples/template-syntax/ts/app/app.component.html +++ b/public/docs/_examples/template-syntax/ts/app/app.component.html @@ -257,10 +257,10 @@

-
click with myClick
+
click with myClick
-{{clickity}} +{{clickMessage}} @@ -567,8 +567,8 @@

Example Form

-
myClick2
-{{clicked2}} +
myClick2
+{{clickMessage2}}

Pipes

diff --git a/public/docs/_examples/template-syntax/ts/app/my-click.directive.ts b/public/docs/_examples/template-syntax/ts/app/my-click.directive.ts index 88901da46b..32e708cb9e 100644 --- a/public/docs/_examples/template-syntax/ts/app/my-click.directive.ts +++ b/public/docs/_examples/template-syntax/ts/app/my-click.directive.ts @@ -4,14 +4,17 @@ import {Directive, Output, ElementRef, EventEmitter} from 'angular2/core'; @Directive({selector:'[myClick]'}) export class MyClickDirective { // #docregion my-click-output-1 - @Output('myClick') clicks = new EventEmitter(); + @Output('myClick') clicks = new EventEmitter(); // @Output(alias) propertyName = ... // #enddocregion my-click-output-1 + constructor(el: ElementRef){ el.nativeElement .addEventListener('click', (event:Event) => { - this.clicks.emit('Click!'); + this._toggle = !this._toggle; + this.clicks.emit(this._toggle ? 'Click!' : ''); }); } + _toggle = false; } // #docregion my-click-output-2 @@ -19,15 +22,18 @@ export class MyClickDirective { // #enddocregion my-click-output-2 selector:'[myClick2]', // #docregion my-click-output-2 - outputs:['clicks:myClick'] + outputs:['clicks:myClick'] // propertyName:alias }) // #enddocregion my-click-output-2 export class MyClickDirective2 { clicks = new EventEmitter(); + constructor(el: ElementRef){ el.nativeElement .addEventListener('click', (event:Event) => { - this.clicks.emit('Click!'); + this._toggle = !this._toggle; + this.clicks.emit(this._toggle ? 'Click2!' : ''); }); } + _toggle = false; } \ No newline at end of file diff --git a/public/docs/ts/latest/guide/template-syntax.jade b/public/docs/ts/latest/guide/template-syntax.jade index 498c7cad44..2b18d3b9e0 100644 --- a/public/docs/ts/latest/guide/template-syntax.jade +++ b/public/docs/ts/latest/guide/template-syntax.jade @@ -101,7 +101,7 @@ include ../../../../_includes/_util-fns We write template expressions in a language that looks like JavaScript. Many JavaScript expressions are legal template expressions but not all. JavaScript expressions that have or promote side-effects are prohibited including: - * assignment (`=`) + * assignments (`=`, `+=`, `-=`) * the `new` operator * chaining expressions with `;` or `,` * increment and decrement operators, `++` and `--`. @@ -191,11 +191,12 @@ include ../../../../_includes/_util-fns :marked Angular template statements are also written in a language that looks like JavaScript. The template statement parser is different than the template expression parser and - specifically supports both assignment (=) and chaining expressions with semicolons (;) and commas (,). + specifically supports both basic assignment (=) and chaining expressions with semicolons (;) and commas (,). However, certain JavaScript syntax is not allowed: * the `new` operator * increment and decrement operators, `++` and `--` + * operator assignment, e.g. `+=`, `-=` * bit-wise operators, `|` and `&` * the [template expression operators](#expression-operators) @@ -1172,28 +1173,30 @@ figure.image-display This is frequently the case with [Attribute Directives](attribute-directives.html). Directive consumers expect to bind to the name of the directive. - For example, we expect to bind to the `myClick` event property of the `MyClickDirective`. - - The directive name is often a poor choice for the the internal property name - because it rarely describes what the property does. - `myClick` is not a good name for a property that emits click events. + For example, when we apply a directive with a `myClick` selector to a `
` tag, + we expect to bind to an event property that is also called `myClick`. ++makeExample('template-syntax/ts/app/app.component.html', 'my-click')(format=".") +:marked + However, the directive name is often a poor choice for the the name of a property within the directive class. + The directive name rarely describes what the property does. + The `myClick` directive name is not a good name for a property that emits click messages. Fortunately, we can have a public name for the property that meets conventional expectations - and use a different name internally - by providing a public alias for the internal property name in the decorator like this: + while using a different name internally. + In the example immediately above, we are actually binding *through the* `myClick` *alias* to + the directive's own `clicks` property. + + We can specify the alias for the property name by passing it into the input/output decorator like this: + +makeExample('template-syntax/ts/app/my-click.directive.ts', 'my-click-output-1')(format=".") :marked - Now the directive name, `myClick`, is the public facing property name to which we can bind -+makeExample('template-syntax/ts/app/app.component.html', 'my-click')(format=".") -:marked - while inside the directive, the property is known as `clicks`. + - With aliasing we please both the directive consumer and the directive author. .l-sub-section :marked - We can alias property names in the `inputs` and `outputs` arrays as well. - We write a colon-delimited string with - the internal property name on the left and the public name on the right: + We can also alias property names in the `inputs` and `outputs` arrays. + We write a *colon-delimited* (:) string with + the directive property name on the *left* and the public alias on the *right*: +makeExample('template-syntax/ts/app/my-click.directive.ts', 'my-click-output-2')(format=".")