#

API Docs for: v2.11.1
Show: Inherited Protected Private Deprecated

# Ember.TextSupport Class

Uses

- Ember.TargetActionSupport

Extends Ember.Mixin
Defined in: `packages/ember-views/lib/mixins/text_support.js:18`
Module: ember-views
Parent Module: ember

`TextSupport` is a shared mixin used by both `Ember.TextField` and `Ember.TextArea`. `TextSupport` adds a number of methods that allow you to specify a controller action to invoke when a certain event is fired on your text field or textarea. The specifed controller action would get the current value of the field passed in as the only argument unless the value of the field is empty. In that case, the instance of the field itself is passed in as the only argument.

Let's use the pressing of the escape key as an example. If you wanted to invoke a controller action when a user presses the escape key while on your field, you would use the `escape-press` attribute on your field like so:

      {{! application.hbs}}

      {{input escape-press='alertUser'}}

        App = Ember.Application.create();

        App.ApplicationController = Ember.Controller.extend({
          actions: {
            alertUser: function ( currentValue ) {
              alert( 'escape pressed, current value: ' + currentValue );
            }
          }
        });

The following chart is a visual representation of what takes place when the escape key is pressed in this scenario:

    The Template
    +---------------------------+
    |                           |
    | escape-press='alertUser'  |
    |                           |          TextSupport Mixin
    +----+----------------------+          +-------------------------------+
         |                                 | cancel method                 |
         |      escape button pressed      |                               |
         +-------------------------------> | checks for the escape-press |
                                           | attribute and pulls out the   |
         +-------------------------------+ | alertUser value             |
         |     action name 'alertUser'     +-------------------------------+
         |     sent to controller
         v
    Controller
    +------------------------------------------ +
    |                                           |
    |  actions: {                               |
    |     alertUser: function( currentValue ){  |
    |       alert( 'the esc key was pressed!' ) |
    |     }                                     |
    |  }                                        |
    |                                           |
    +-------------------------------------------+

Here are the events that we currently support along with the name of the attribute you would need to use on your field. To reiterate, you would use the attribute name like so:

      {{input attribute-name='controllerAction'}}

    +--------------------+----------------+
    |                    |                |
    | event              | attribute name |
    +--------------------+----------------+
    | new line inserted  | insert-newline |
    |                    |                |
    | enter key pressed  | insert-newline |
    |                    |                |
    | cancel key pressed | escape-press   |
    |                    |                |
    | focusin            | focus-in       |
    |                    |                |
    | focusout           | focus-out      |
    |                    |                |
    | keypress           | key-press      |
    |                    |                |
    | keyup              | key-up         |
    |                    |                |
    | keydown            | key-down       |
    +--------------------+----------------+

- Index
- Methods
- Properties

## Item Index

### Methods

- apply
- cancel
- detect
- focusIn
- focusOut
- insertNewline
- keyDown
- keyPress
- keyUp
- reopen
- triggerAction

### Properties

- action
- bubbles
- onEvent

## Methods

### `apply`

(

- `obj`

)
private

Inherited from Ember.Mixin: `packages/ember-metal/lib/mixin.js:572`

#### Parameters:

- `obj` Object

#### Returns:

applied object

### `cancel`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:227`

Allows you to specify a controller action to invoke when the escape button is pressed. To use this method, give your field an `escape-press` attribute. The value of that attribute should be the name of the action in your controller that you wish to invoke.

For an example on how to use the `escape-press` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `detect`

(

- `obj`

)
Boolean private

Inherited from Ember.Mixin: `packages/ember-metal/lib/mixin.js:603`

#### Parameters:

- `obj` Object

#### Returns:

Boolean:

### `focusIn`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:244`

Allows you to specify a controller action to invoke when a field receives focus. To use this method, give your field a `focus-in` attribute. The value of that attribute should be the name of the action in your controller that you wish to invoke.

For an example on how to use the `focus-in` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `focusOut`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:261`

Allows you to specify a controller action to invoke when a field loses focus. To use this method, give your field a `focus-out` attribute. The value of that attribute should be the name of the action in your controller that you wish to invoke.

For an example on how to use the `focus-out` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `insertNewline`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:208`

Allows you to specify a controller action to invoke when either the `enter` key is pressed or, in the case of the field being a textarea, when a newline is inserted. To use this method, give your field an `insert-newline` attribute. The value of that attribute should be the name of the action in your controller that you wish to invoke.

For an example on how to use the `insert-newline` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `keyDown`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:315`

Allows you to specify a controller action to invoke when a key-down event is fired. To use this method, give your field a `key-down` attribute. The value of that attribute should be the name of the action in your controller that you wish to invoke.

For an example on how to use the `key-down` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `keyPress`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:279`

Allows you to specify a controller action to invoke when a key is pressed. To use this method, give your field a `key-press` attribute. The value of that attribute should be the name of the action in your controller you that wish to invoke.

For an example on how to use the `key-press` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `keyUp`

(

- `event`

)
private

Defined in `packages/ember-views/lib/mixins/text_support.js:296`

Allows you to specify a controller action to invoke when a key-up event is fired. To use this method, give your field a `key-up` attribute. The value of that attribute should be the name of the action in your controller that you wish to invoke.

For an example on how to use the `key-up` attribute, please reference the example near the top of this file.

#### Parameters:

- `event` Event

### `reopen`

(

- `arguments`

)
private

Inherited from Ember.Mixin: `packages/ember-metal/lib/mixin.js:535`

#### Parameters:

- `arguments` Object multiple

### `triggerAction`

(

- `opts`

)
Boolean private

Inherited from Ember.TargetActionSupport: `packages/ember-runtime/lib/mixins/target_action_support.js:43`

Send an `action` with an `actionContext` to a `target`. The action, actionContext and target will be retrieved from properties of the object. For example:

    App.SaveButtonView = Ember.View.extend(Ember.TargetActionSupport, {
      target: Ember.computed.alias('controller'),
      action: 'save',
      actionContext: Ember.computed.alias('context'),
      click() {
        this.triggerAction(); // Sends the save action, along with the current context
                              // to the current controller
      }
    });

The `target`, `action`, and `actionContext` can be provided as properties of an optional object argument to `triggerAction` as well.

    App.SaveButtonView = Ember.View.extend(Ember.TargetActionSupport, {
      click() {
        this.triggerAction({
          action: 'save',
          target: this.get('controller'),
          actionContext: this.get('context')
        }); // Sends the save action, along with the current context
            // to the current controller
      }
    });

The `actionContext` defaults to the object you are mixing `TargetActionSupport` into. But `target` and `action` must be specified either as properties or with the argument to `triggerAction`, or a combination:

    App.SaveButtonView = Ember.View.extend(Ember.TargetActionSupport, {
      target: Ember.computed.alias('controller'),
      click() {
        this.triggerAction({
          action: 'save'
        }); // Sends the save action, along with a reference to this,
            // to the current controller
      }
    });

#### Parameters:

- `opts` Object

  (optional, with the optional keys action, target and/or actionContext)

#### Returns:

Boolean:

true if the action was sent successfully and did not return false

## Properties

### `action`

String private

Defined in `packages/ember-views/lib/mixins/text_support.js:145`

The action to be sent when the user presses the return key.

This is similar to the `{{action}}` helper, but is fired when the user presses the return key when editing a text field, and sends the value of the field as the context.

Default: null

### `bubbles`

Boolean private

Defined in `packages/ember-views/lib/mixins/text_support.js:174`

Whether the `keyUp` event that triggers an `action` to be sent continues propagating to other views.

By default, when the user presses the return key on their keyboard and the text field has an `action` set, the action will be sent to the view's controller and the key event will stop propagating.

If you would like parent views to receive the `keyUp` event even after an action has been dispatched, set `bubbles` to true.

Default: false

### `onEvent`

String private

Defined in `packages/ember-views/lib/mixins/text_support.js:159`

The event that should send the action.

Options are:

- `enter`: the user pressed enter
- `keyPress`: the user pressed a key

Default: enter