Ember.TextSupport Class packages/ember-views/lib/mixins/text_support.js:16
PRIVATE
Extends: Ember.Mixin
Uses: Ember.TargetActionSupport
Defined in: packages/ember-views/lib/mixins/text_support.js:16
Module: ember-views
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:
1 2 3 4 5 6 7 8 9 |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
+--------------------+----------------+ | | | | 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 | +--------------------+----------------+ |
Methods
- apply
- cancel
- create
- detect
- focusIn
- focusOut
- insertNewline
- keyDown
- keyPress
- keyUp
- reopen
- triggerAction
Properties
apply
(obj)
private
Parameters:
- obj
Returns:
- applied object
cancel
(event)
private
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
create
(arguments)
public
static
Parameters:
- arguments
detect
(obj)
Boolean
private
Parameters:
- obj
Returns:
- Boolean
focusIn
(event)
private
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
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
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
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
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
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
Parameters:
- arguments
triggerAction
(opts)
Boolean
private
Send an action with an actionContext to a target. The action, actionContext
and target will be retrieved from properties of the object. For example:
1 2 3 4 5 6 7 8 9 |
App.SaveButtonView = Ember.View.extend(Ember.TargetActionSupport, {
target: Ember.computed.alias('controller'),
action: 'save',
actionContext: Ember.computed.alias('context'),
click: function() {
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.
1 2 3 4 5 6 7 8 9 10 |
App.SaveButtonView = Ember.View.extend(Ember.TargetActionSupport, {
click: function() {
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:
1 2 3 4 5 6 7 8 9 |
App.SaveButtonView = Ember.View.extend(Ember.TargetActionSupport, {
target: Ember.computed.alias('controller'),
click: function() {
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
action
String
private
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
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
The event that should send the action.
Options are:
enter: the user pressed enterkeyPress: the user pressed a key
Default: enter