diff --git a/aio/content/guide/user-input.md b/aio/content/guide/user-input.md index 655bda572f7..2a7b003df37 100644 --- a/aio/content/guide/user-input.md +++ b/aio/content/guide/user-input.md @@ -4,7 +4,7 @@
Marked for archiving
-To ensure that you have the best experience possible, this topic is marked for archiving until we determine that it clearly conveys the most accurate information possible. +To ensure that you have the best experience possible, this topic is marked for archiving until it clearly conveys the most accurate information possible. In the meantime, this topic might be helpful: [Event binding](guide/event-binding). @@ -28,16 +28,20 @@ To bind to a DOM event, surround the DOM event name in parentheses and assign a The following example shows an event binding that implements a click handler: + + + + The `(click)` to the left of the equals sign identifies the button's click event as the **target of the binding**. -The text in quotes to the right of the equals sign is the **template statement**, which responds to the click event by calling the component's `onClickMe` method. +The text in quotes to the right of the equals sign is the **template statement**. The statement responds to the click event by calling the component's `onClickMe` method. When writing a binding, be aware of a template statement's **execution context**. The identifiers in a template statement belong to a specific context object, usually the Angular component controlling the template. -The example above shows a single line of HTML, but that HTML belongs to a larger component: +The preceding example shows a single line of HTML, but that HTML belongs to a larger component: @@ -52,7 +56,7 @@ The following code listens to the `keyup` event and passes the entire event payl -When a user presses and releases a key, the `keyup` event occurs, and Angular provides a corresponding DOM event object in the `$event` variable which this code passes as a parameter to the component's `onKey()` method. +When a user presses and releases a key, the `keyup` event occurs. Angular then provides a corresponding DOM event object in the `$event` variable which this code passes as a parameter to the component's `onKey()` method. @@ -65,9 +69,13 @@ In this case, `target` refers to the [`` element](https://developer.mozil After each call, the `onKey()` method appends the contents of the input box value to the list in the component's `values` property, followed by a separator character \(`|`\). The [interpolation](guide/interpolation) displays the accumulating input box changes from the `values` property. -Suppose the user enters the letters "abc", and then backspaces to remove them one by one. + + +Suppose the user enters the letters "abc" and then backspaces to remove them one by one. Here's what the UI displays: + + a | ab | abc | ab | a | | @@ -82,7 +90,7 @@ a | ab | abc | ab | a | |
-Alternatively, you could accumulate the individual keys themselves by substituting `event.key` for `event.target.value` in which case the same user input would produce: +You could also accumulate the individual keys themselves by substituting `event.key` for `event.target.value` in which case the same user input would produce: @@ -96,7 +104,7 @@ a | b | c | backspace | backspace | backspace ### Type the `$event` -The example above casts the `$event` as an `any` type. +The preceding example casts the `$event` as an `any` type. That simplifies the code at a cost. There is no type information that could reveal properties of the event object and prevent silly mistakes. @@ -110,19 +118,18 @@ The `OnKey` method more clearly expresses what it expects from the template and ### Passing `$event` is a dubious practice -Typing the event object reveals a significant objection to passing the entire DOM event into the method: -The component has too much awareness of the template details. +Typing the event object reveals a significant objection to passing the entire DOM event into the method. Namely, the component has too much awareness of the template details. It can't extract information without knowing more than it should about the HTML implementation. -That breaks the separation of concerns between the template \(*what the user sees*\) and the component \(*how the application processes user data*\). +That breaks the separation of concerns between the template, *what the user sees*, and the component, *how the application processes user data*. The next section shows how to use template reference variables to address this problem. ## Get user input from a template reference variable There's another way to get the user data: -Use Angular [**template reference variables**](guide/template-reference-variables). +use Angular [**template reference variables**](guide/template-reference-variables). These variables provide direct access to an element from within the template. -To declare a template reference variable, precede an identifier with a hash \(or pound\) character \(`#`\). +To declare a template reference variable, precede an identifier with a hash/pound character \(`#`\). The following example uses a template reference variable to implement a keystroke loopback in a simple template. @@ -146,9 +153,9 @@ Type something in the input box, and watch the display update with each keystrok
This won't work at all unless you bind to an event.
-Angular updates the bindings \(and therefore the screen\) only if the app does something in response to asynchronous events, such as keystrokes. +Angular updates the bindings and screen only if the app does something in response to asynchronous events, such as keystrokes. This example code binds the `keyup` event to the number 0, the shortest template statement possible. -While the statement does nothing useful, it satisfies Angular's requirement so that Angular will update the screen. +While the statement does nothing useful, it satisfies Angular's condition so that Angular updates the screen.
@@ -169,7 +176,7 @@ Sometimes only the *Enter* key matters, because it signals that the user has fin One way to reduce the noise would be to examine every `$event.keyCode` and take action only when the key is *Enter*. There's an easier way: -Bind to Angular's `keyup.enter` pseudo-event. +bind to Angular's `keyup.enter` pseudo-event. Then Angular calls the event handler only when the user presses *Enter*. @@ -184,7 +191,7 @@ Here's how it works. ## On blur -In the previous example, the current state of the input box is lost if the user mouses away and clicks elsewhere on the page without first pressing *Enter*. +In the previous example, the current state of the input box is lost if the user mouses away and clicks elsewhere without first pressing *Enter*. The component's `value` property is updated only when the user presses *Enter*. To fix this issue, listen to both the *Enter* key and the `blur` event. @@ -248,7 +255,7 @@ For example, you can use the following steps to make the scroll event passive. -After those steps, if you add event listeners for the `scroll` event, the listeners will be `passive`. +After those steps, if you add event listeners for the `scroll` event, the listeners are going to be `passive`. ## Summary