Ember.ViewTargetActionSupport Class packages/ember-views/lib/mixins/view_target_action_support.js:5
PRIVATE
Extends: Ember.TargetActionSupport
Defined in: packages/ember-views/lib/mixins/view_target_action_support.js:5
Module: ember
Ember.ViewTargetActionSupport is a mixin that can be included in a
view class to add a triggerAction method with semantics similar to
the Handlebars {{action}} helper. It provides intelligent defaults
for the action's target: the view's controller; and the context that is
sent with the action: the view's context.
Note: In normal Ember usage, the {{action}} helper is usually the best
choice. This mixin is most often useful when you are doing more complex
event handling in custom View subclasses.
For example:
1 2 3 4 5 6 7 |
App.SaveButtonView = Ember.View.extend(Ember.ViewTargetActionSupport, {
action: 'save',
click: function() {
this.triggerAction(); // Sends the `save` action, along with the current context
// to the current controller
}
});
|
The action can be provided as properties of an optional object argument
to triggerAction as well.
1 2 3 4 5 6 7 8 |
App.SaveButtonView = Ember.View.extend(Ember.ViewTargetActionSupport, {
click: function() {
this.triggerAction({
action: 'save'
}); // Sends the `save` action, along with the current context
// to the current controller
}
});
|
Methods
- $
- _register
- _unregister
- append
- appendTo
- apply
- create
- createChildView
- createElement
- destroy
- destroyElement
- detect
- findElementInParentElement
- handleEvent
- init
- nearestOfType
- nearestWithProperty
- readDOMAttr
- remove
- removeChild
- removeFromParent
- renderToElement
- reopen
- replaceIn
- rerender
- triggerAction
Properties
- _context
- actionContext
- childViews
- context
- controller
- element
- elementId
- isView
- layout
- layoutName
- tagName
- target
- template
- templateName
Events
$
(selector)
JQuery
public
Returns a jQuery object for this view's element. If you pass in a selector string, this method will return a jQuery object, using the current element as its buffer.
For example, calling view.$('li') will return a jQuery object containing
all of the li elements inside the DOM element of this view.
Parameters:
- selector [String]
- a jQuery-compatible selector string
Returns:
- JQuery
- the jQuery object for the DOM node
_register
private
Registers the view in the view registry, keyed on the view's elementId.
This is used by the EventDispatcher to locate the view in response to
events.
This method should only be called once the view has been inserted into the DOM.
_unregister
private
Removes the view from the view registry. This should be called when the view is removed from DOM.
append
Ember.View
private
Appends the view's element to the document body. If the view does not have an HTML representation yet the element will be generated automatically.
If your application uses the rootElement property, you must append
the view within that element. Rendering views outside of the rootElement
is not supported.
Note that this method just schedules the view to be appended; the DOM element will not be appended to the document body until all bindings have finished synchronizing.
Returns:
- Ember.View
- receiver
appendTo
(A)
Ember.View
private
Appends the view's element to the specified parent element.
If the view does not have an HTML representation yet, createElement()
will be called automatically.
Note that this method just schedules the view to be appended; the DOM element will not be appended to the given element until all bindings have finished synchronizing.
This is not typically a function that you will need to call directly when
building your application. You might consider using Ember.ContainerView
instead. If you do need to use appendTo, be sure that the target element
you are providing is associated with an Ember.Application and does not
have an ancestor element that is associated with an Ember view.
Parameters:
- A String|DOMElement|jQuery
- selector, element, HTML string, or jQuery object
Returns:
- Ember.View
- receiver
apply
(obj)
private
Parameters:
- obj
Returns:
- applied object
create
(arguments)
public
static
Parameters:
- arguments
createChildView
(viewClass, attrs)
Ember.View
private
Instantiates a view to be added to the childViews array during view
initialization. You generally will not call this method directly unless
you are overriding createChildViews(). Note that this method will
automatically configure the correct settings on the new view instance to
act as a child of the parent.
Parameters:
- viewClass Class|String
- attrs [Object]
- Attributes to add
Returns:
- Ember.View
- new instance
createElement
Ember.View
private
Creates a DOM representation of the view and all of its child views by
recursively calling the render() method. Once the element is created,
it sets the element property of the view to the rendered element.
After the element has been inserted into the DOM, didInsertElement will
be called on this view and all of its child views.
Returns:
- Ember.View
- receiver
destroy
private
You must call destroy on a view to destroy the view (and all of its
child views). This will remove the view from any parent node, then make
sure that the DOM element managed by the view can be released by the
memory manager.
destroyElement
Ember.View
private
Destroys any existing element along with the element for any child views as well. If the view does not currently have a element, then this method will do nothing.
If you implement willDestroyElement() on your view, then this method will
be invoked on your view before your element is destroyed to give you a
chance to clean up any event handlers, etc.
If you write a willDestroyElement() handler, you can assume that your
didInsertElement() handler was called earlier for the same element.
You should not call or override this method yourself, but you may want to implement the above callbacks.
Returns:
- Ember.View
- receiver
detect
(obj)
Boolean
private
Parameters:
- obj
Returns:
- Boolean
findElementInParentElement
(parentElement)
DOMElement
private
Attempts to discover the element in the parent element. The default
implementation looks for an element with an ID of elementId (or the
view's guid if elementId is null). You can override this method to
provide your own form of lookup. For example, if you want to discover your
element using a CSS class name instead of an ID.
Parameters:
- parentElement DOMElement
- The parent's DOM element
Returns:
- DOMElement
- The discovered element
handleEvent
(eventName, evt)
private
Handle events from Ember.EventDispatcher
Parameters:
- eventName String
- evt Event
init
private
Setup a view, but do not finish waking it up.
- configure
childViews - register the view with the global views hash, which is used for event dispatch
nearestOfType
(klass)
private
Return the nearest ancestor that is an instance of the provided class or mixin.
Parameters:
- klass Class,Mixin
- Subclass of Ember.View (or Ember.View itself), or an instance of Ember.Mixin.
Returns:
- Ember.View
nearestWithProperty
(property)
private
Return the nearest ancestor that has a given property.
Parameters:
- property String
- A property name
Returns:
- Ember.View
readDOMAttr
(name)
public
Normally, Ember's component model is "write-only". The component takes a bunch of attributes that it got passed in, and uses them to render its template.
One nice thing about this model is that if you try to set a value to the same thing as last time, Ember (through HTMLBars) will avoid doing any work on the DOM.
This is not just a performance optimization. If an attribute has not
changed, it is important not to clobber the element's "hidden state".
For example, if you set an input's value to the same value as before,
it will clobber selection state and cursor position. In other words,
setting an attribute is not always idempotent.
This method provides a way to read an element's attribute and also update the last value Ember knows about at the same time. This makes setting an attribute idempotent.
In particular, what this means is that if you get an <input> element's
value attribute and then re-render the template with the same value,
it will avoid clobbering the cursor and selection position.
Since most attribute sets are idempotent in the browser, you typically can get away with reading attributes using jQuery, but the most reliable way to do so is through this method.
Parameters:
- name String
- the name of the attribute
Returns:
- String
remove
Ember.View
private
Removes the view's element from the element to which it is attached.
Returns:
- Ember.View
- receiver
removeChild
(view)
Ember.View
private
Removes the child view from the parent view.
Parameters:
- view Ember.View
Returns:
- Ember.View
- receiver
removeFromParent
Ember.View
private
Removes the view from its parentView, if one is found. Otherwise
does nothing.
Returns:
- Ember.View
- receiver
renderToElement
(tagName)
HTMLBodyElement
private
Parameters:
- tagName String
- The tag of the element to create and render into. Defaults to "body".
Returns:
- HTMLBodyElement
- element
reopen
(arguments)
private
Parameters:
- arguments
replaceIn
(target)
Ember.View
private
Replaces the content of the specified parent element with this view's element. If the view does not have an HTML representation yet, the element will be generated automatically.
Note that this method just schedules the view to be appended; the DOM element will not be appended to the given element until all bindings have finished synchronizing
Parameters:
- target String|DOMElement|jQuery
- A selector, element, HTML string, or jQuery object
Returns:
- Ember.View
- received
rerender
public
Renders the view again. This will work regardless of whether the view is already in the DOM or not. If the view is in the DOM, the rendering process will be deferred to give bindings a chance to synchronize.
If children were added during the rendering process using appendChild,
rerender will remove them, because they will be added again
if needed by the next render.
In general, if the display of your view changes, you should modify
the DOM element directly instead of manually calling rerender, which can
be slow.
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
_context
private
Private copy of the view's template context. This can be set directly by Handlebars without triggering the observer that causes the view to be re-rendered.
The context of a view is looked up as follows:
- Supplied context (usually by Handlebars)
- Specified controller
parentView's context (for a child of a ContainerView)
The code in Handlebars that overrides the _context property first
checks to see whether the view has a specified controller. This is
something of a hack and should be revisited.
actionContext
private
childViews
Array
private
Array of child views. You should never edit this array directly.
Instead, use appendChild and removeFromParent.
Default: []
context
Object
private
The object from which templates should access properties.
This object will be passed to the template function each time the render method is called, but it is up to the individual function to decide what to do with it.
By default, this will be the view's controller.
controller
Object
private
The controller managing this view. If this property is set, it will be made available for use by the template.
element
DOMElement
public
Returns the current DOM element for the view.
elementId
String
public
The HTML id of the view's element in the DOM. You can provide this
value yourself but it must be unique (just as in HTML):
If not manually set a default value will be provided by the framework.
Once rendered an element's elementId is considered immutable and you
should never change it. If you need to compute a dynamic value for the
elementId, you should do this when the component or element is being
instantiated:
1 2 3 4 5 6 |
export default Ember.Component.extend({ setElementId: Ember.on('init', function() { var index = this.get('index'); this.set('elementId', 'component-id' + index); }) }); |
isView
Boolean
private
static
Default: true
layout
Function
private
A view may contain a layout. A layout is a regular template but
supersedes the template property during rendering. It is the
responsibility of the layout template to retrieve the template
property from the view (or alternatively, call Handlebars.helpers.yield,
{{yield}}) to render it in the correct location.
This is useful for a view that has a shared wrapper, but which delegates
the rendering of the contents of the wrapper to the template property
on a subclass.
layoutName
String
private
The name of the layout to lookup if no layout is provided.
By default Ember.View will lookup a template with this name in
Ember.TEMPLATES (a shared global object).
Default: null
tagName
String
public
Tag name for the view's outer element. The tag name is only used when an
element is first created. If you change the tagName for an element, you
must destroy and recreate the view element.
By default, the render buffer will use a <div> tag for views.
Default: null
target
private
template
Function
private
The template used to render the view. This should be a function that accepts an optional context parameter and returns a string of HTML that will be inserted into the DOM relative to its parent view.
In general, you should set the templateName property instead of setting
the template yourself.
templateName
String
private
The name of the template to lookup if no template is provided.
By default Ember.View will lookup a template with this name in
Ember.TEMPLATES (a shared global object).
Default: null
didInsertElement
public
Called when the element of the view has been inserted into the DOM or after the view was re-rendered. Override this function to do any set up that requires an element in the document body.
When a view has children, didInsertElement will be called on the child view(s) first, bubbling upwards through the hierarchy.
parentViewDidChange
private
Called when the parentView property has changed.
willClearRender
public
Called when the view is about to rerender, but before anything has been torn down. This is a good opportunity to tear down any manual observers you have installed based on the DOM state
willDestroyElement
public
Called when the element of the view is going to be destroyed. Override this function to do any teardown that requires an element, like removing event listeners.
Please note: any property changes made during this event will have no effect on object observers.
willInsertElement
public
Called when a view is going to insert an element into the DOM.