include ../../../../_includes/_util-fns :marked When the user clicks a link, pushes a button, or types on the keyboard we want to know about it. These user actions all raise DOM events. In this chapter we learn to bind to those events using the Angular Event Binding syntax. [Live Example](/resources/live-examples/user-input/ts/plnkr.html). :marked ## Binding to User Input Events We can listen to [any DOM event](https://developer.mozilla.org/en-US/docs/Web/Events) with an [Angular Event Binding](./template-syntax.html#event-binding). The syntax is simple. We assign a template expression to the DOM event name, surrounded in parentheses. A click Event Binding makes for a quick illustration. +makeExample('user-input/ts/app/click-me.component.ts', 'click-me-button')(format=".", language="html") :marked The `(click)` to the left of the equal sign identifies the button's click event as the **target of the binding**. The text within quotes on the right is the "**template expression**" in which we respond to the click event by calling the component's `onClickMe` method. A [template expression](./template-syntax.html#template-expressions) is a subset of JavaScript with a few added tricks. When writing a binding we must be aware of a template expression's **execution context**. The identifers appearing within an expression belong to a specific context object. That object is usually the Angular component that controls the template ... which it definitely is in this case because that snippet of HTML belongs to the following component: +makeExample('user-input/ts/app/click-me.component.ts', 'click-me-component', 'app/click-me.component.ts') :marked The `onClickMe` in the template refers to the `onClickMe` method of the component. When the user clicks the button, Angular calls the component's `onClickMe` method. .l-main-section :marked ## Get user input from the $event object We can bind to all kinds of events. Let's bind to the "keyup" event of an input box and replay what the user types back onto the screen. This time we'll (1) listen to an event and (2) grab the user's input. +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-1-template', 'app/keyup.components.ts (template v.1)') :marked Angular makes an event object available in the **`$event`** variable which we pass to the component's `onKey()` method. The user data we want is in that variable somewhere. +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-1-class-no-type', 'app/keyup.components.ts (class v.1)') :marked The shape of the `$event` object is determined by whatever raises the event. The `keyup` event comes from the DOM so `$event` must be a [standard DOM event object](https://developer.mozilla.org/en-US/docs/Web/API/Event). The `$event.target` gives us the [`HTMLInputElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) which has a `value` property and that's where we find our user input data. With had this in mind when we passed `$event` to our `onKey()` component method where we extract the user's input and concatenate it to the previous user data that we're accumulating in the component's' `values` property. We then use [interpolation](./template-syntax.html#interpolation) to display the accumulating `values` property back on screen. Enter the letters "abc", backspace to remove them, and we should see: code-example(). a | ab | abc | ab | a | | figure.image-display img(src='/resources/images/devguide/user-input/keyup1-anim.gif' alt="key up 1") .l-sub-section :marked We cast the `$event` as an `any` type which means we've abandoned strong typing to simplify our code. We generally prefer the strong typing that TypeScript affords. We can rewrite the method, casting to HTML DOM objects like this. +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-1-class', 'app/keyup.components.ts (class v.1 - strongly typed )') :marked
Strong typing reveals a serious problem with passing a DOM event into the method: too much awareness of template details, too little separation of concerns. We'll address this problem in our next try at processing user keystrokes. :marked .l-main-section :marked ## Get user input from a local template variable There's another way to get the user data without the `$event` variable. Angular has syntax feature called [**local template variables**](./template-syntax.html#local-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 (#). Let's demonstrate with 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') :marked We've declared a template local variable named `box` on the `` element. The `box` variable is a reference to the `` element itself which means we can grab the input element's `value` and display it with interpolation between `

` tags. The template is completely self contained. It doesn't bind to the component which does nothing. Type in the input box and watch the display update with each keystroke. *Voila!* figure.image-display img(src='/resources/images/devguide/user-input/keyup-loop-back-anim.gif' alt="loop back") .l-sub-section :marked **This won't work at all unless we bind to an event**. Angular only updates the bindings (and therefore the screen) if we do something in response to asynchronous events such as keystrokes. That's why we bind the `keyup` event to an expression that does ... well, nothing. We're binding to the number 0, the shortest expression 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 easer to get to the textbox with that variable than to go through the `$event` object. Maybe we can re-write our previous "key-up" example using the variable to acquire 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)') :marked That sure seems easier. An especially nice aspect of this approach is that our component code gets clean data values from the view. It no longer requires knowledge of the `$event` and its structure. .l-main-section :marked ## Key event filtering (with `key.enter`) Perhaps we don't care about every keystroke. We're only interested in the input box value when the user hits the "Enter" key. We'd like to ignore all other keys. When we bind to the `(keyup)` event, our event handling expression hears *every key stroke*. We could filter the keys first, examining every `$event.keyCode`, and update the `values` property only if the key is "Enter". Angular can filter the key events for us. Angular has a special syntax for keyboard events. We can listen for just the "Enter" key by binding to Angular's `keyup.enter` pseudo-event. Only then do we update the component's `values` property ... inside the event expression rather than in the component ... because we *can* ... even if it is a dubious practice. +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-3' ,'app/keyup.components.ts (v3)') :marked Here's how it works. figure.image-display img(src='/resources/images/devguide/user-input/keyup3-anim.gif' alt="key up 3") .l-main-section :marked ## On blur Our previous example won't transfer the current state of the input box if the user mouses away and clicks elsewhere on the page. We only update the component's `values` property when the user presses "Enter" inside the input box. Let's fix that by listening to the input box's blur event as well. +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-4' ,'app/keyup.components.ts (v4)') .l-main-section :marked ## Put it all together We learned how to [display data](./displaying-data.html) in the previous chapter. We've acquired a small arsenal of event binding techniques in this chapter. Let's put it all together in a micro-app that can display a list of heroes and add new heroes to that list by typing in the input box and hitting "Enter", clicking "Add", or clicking elsewhere on the page. figure.image-display img(src='/resources/images/devguide/user-input/little-tour-anim.gif' alt="Little Tour of Heroes") :marked Below is the "Little Tour of Heroes" component. We'll call out the highlights after we bask briefly in its minimalist glory. +makeExample('user-input/ts/app/little-tour.component.ts', 'little-tour', 'app/little-tour.component.ts') :marked We've seen almost everything here before. A few things are new or bear repeating. ### *newHero* template variable The *newHero* template variable refers to the `` element. We can access `newHero` from any sibling or child of the `` element. When the user clicks the button, we don't need a fancy css selector to track down the textbox and extract its value. ### Extract the input box *value* We could have passed the `newHero` into the component's `addHero()` method. But that would require `addHero` to pick its way through the `` DOM element, something we learned to dislike in our first try at a [*KeyupComponent*](#keyup1). Instead, we grab the input box *value* and pass *that* to `addHero()`. The component knows nothing about HTML or DOM which is the way we like it. ### Don't let template expressions be complex We bound `(blur)` to *two* JavaScript statements. We like the first one that calls `addHero`. We do not like the second one that assigns an empty string to the input box value. We did it for a good reason. We have to clear the input box after adding the new hero to the list. The component has no way to do that itself — because it has no access to the input box (our design choice). Although it *works*, we are rightly wary of JavaScript in HTML. Template expressions are powerful. We're supposed to use them responsibly. Complex JavaScript in HTML is irresponsible. Should we reconsider our reluctance to pass the input box into the component? There should be a better third way. And there is as we'll see when we learn about `NgModel` in the [Forms](forms.html) chapter. .l-main-section :marked ## Source code Here is all the code we talked about in this chapter. +makeTabs(` user-input/ts/app/click-me.component.ts, user-input/ts/app/keyup.components.ts, user-input/ts/app/loop-back.component.ts, user-input/ts/app/little-tour.component.ts `,'', `click-me.component.ts, keyup.components.ts, loop-back.component.ts, little-tour.component.ts`) .l-main-section :marked ## Next Steps We've mastered the basic primitives for responding to user input and gestures. As powerful as these primitives are, they are a bit clumsy for handling large amounts of user input. We're operating down at the low level of events when we should be writing two-way bindings between data entry fields and model properties. Angular has a two-way binding called `NgModel` and we learn about it in the `Forms` chapter.