From 32ac619fc70b3e0eb07c5307ed2f86e56311e54f Mon Sep 17 00:00:00 2001 From: Peter Fryer-Davis Date: Tue, 6 Sep 2016 13:31:25 -0400 Subject: [PATCH] Uwaterloo 210J pfryerda edits (#1968) * template-syntax - removed word redundancies, consistent bolding rather than italics * Some (not all) changes from PR. * remaining changes from pull request --- .../docs/ts/latest/guide/template-syntax.jade | 46 +++++++++---------- 1 file changed, 22 insertions(+), 24 deletions(-) diff --git a/public/docs/ts/latest/guide/template-syntax.jade b/public/docs/ts/latest/guide/template-syntax.jade index 165db573c3..aad1915f73 100644 --- a/public/docs/ts/latest/guide/template-syntax.jade +++ b/public/docs/ts/latest/guide/template-syntax.jade @@ -711,12 +711,12 @@ block style-property-name-dart-diff .l-main-section :marked - ## Event Binding - The bindings we’ve met so far flow data in one direction: *from the component to an element*. + ## Event binding + The bindings we’ve met so far flow data in one direction: **from a component to an element**. Users don’t just stare at the screen. They enter text into input boxes. They pick items from lists. They click buttons. Such user actions may result in a flow of data in the opposite direction: - *from an element to the component*. + **from an element to a component**. The only way to know about a user action is to listen for certain events such as keystrokes, mouse movements, clicks, and touches. @@ -728,12 +728,12 @@ block style-property-name-dart-diff the component's `onSave()` method whenever a click occurs: +makeExample('template-syntax/ts/app/app.component.html', 'event-binding-1')(format=".") :marked - ### Target Event - A **name between enclosing parentheses** — for example, `(click)` — + ### Target event + A **name between parentheses** — for example, `(click)` — identifies the target event. In the following example, the target is the button’s click event. +makeExample('template-syntax/ts/app/app.component.html', 'event-binding-1')(format=".") :marked - Some people prefer the `on-` prefix alternative, known as the *canonical form*: + Some people prefer the `on-` prefix alternative, known as the **canonical form**: +makeExample('template-syntax/ts/app/app.component.html', 'event-binding-2')(format=".") :marked Element events may be the more common targets, but Angular looks first to see if the name matches an event property @@ -742,47 +742,46 @@ block style-property-name-dart-diff .l-sub-section :marked - The `myClick` directive is further described below in the section - on [Aliasing input/output properties](#aliasing-io). + The `myClick` directive is further described in the section + on [aliasing input/output properties](#aliasing-io). :marked - If the name fails to match an element event or an output property of a known directive, + If the name fails to match element event or output property of a known directive, Angular reports an “unknown directive” error. ### *$event* and event handling statements In an event binding, Angular sets up an event handler for the target event. When the event is raised, the handler executes the template statement. - The template statement typically involves a receiver that wants to do something - in response to the event, such as take a value from the HTML control and store it - in a model. + The template statement typically involves a receiver, which performs an action + in response to the event, such as storing a value from the HTML control + into a model. The binding conveys information about the event, including data values, through an **event object named `$event`**. - The shape of the event object is determined by the target event itself. - If the target event is a native DOM element event, the `$event` is a + The shape of the event object is determined by the target event. + If the target event is a native DOM element event, then `$event` is a [DOM event object]( https://developer.mozilla.org/en-US/docs/Web/Events), with properties such as `target` and `target.value`. Consider this example: +makeExample('template-syntax/ts/app/app.component.html', 'without-NgModel')(format=".") :marked - We’re binding the input box `value` to a `firstName` property, and we’re listening for changes by binding to the input box’s `input` event. + This code sets the input box `value` property by binding to the `firstName` property. To listen for changes to the value, the code binds to the input box's `input` event. When the user makes changes, the `input` event is raised, and the binding executes the statement within a context that includes the DOM event object, `$event`. - To update the `firstName` property, we must get the changed text by following - the path `$event.target.value`. + To update the `firstName` property, the changed text is retrieved by following the path `$event.target.value`. - If the event belongs to a directive (remember: components are directives), `$event` has whatever shape the directive chose to produce. + If the event belongs to a directive (recall that components are directives), `$event` has whatever shape the directive decides to produce. ### Custom Events with EventEmitter Directives typically raise custom events with an Angular [EventEmitter](../api/core/index/EventEmitter-class.html). - A directive creates an `EventEmitter` and exposes it as a property. - The directive calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload that can be anything. + The directive creates an `EventEmitter` and exposes it as a property. + The directives calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload, which can be anything. Parent directives listen for the event by binding to this property and accessing the payload through the `$event` object. Consider a `HeroDetailComponent` that presents hero information and responds to user actions. @@ -797,8 +796,8 @@ block style-property-name-dart-diff :marked The component defines a `deleteRequest` property that returns an `EventEmitter`. - When the user clicks *delete*, the component invokes the `delete()` method - which tells the `EventEmitter` to emit a `Hero` object. + When the user clicks *delete*, the component invokes the `delete()` method, + telling the `EventEmitter` to emit a `Hero` object. Now imagine a hosting parent component that binds to the `HeroDetailComponent`'s `deleteRequest` event. @@ -810,12 +809,11 @@ block style-property-name-dart-diff ### Template statements have side effects The `deleteHero` method has a side effect: it deletes a hero. - Template statement side effects are not just OK, they are expected. + Template statement side effects are not just OK, but expected. Deleting the hero updates the model, perhaps triggering other changes including queries and saves to a remote server. These changes percolate through the system and are ultimately displayed in this and other views. - It's all good. // :marked