Ember.Component Class
An Ember.Component
is a view that is completely
isolated. Properties accessed in its templates go
to the view object and actions are targeted at
the view object. There is no access to the
surrounding context or outer controller; all
contextual information must be passed in.
The easiest way to create an Ember.Component
is via
a template. If you name a template
app/components/my-foo.hbs
, you will be able to use
{{my-foo}}
in other templates, which will make
an instance of the isolated component.
{{person-profile person=currentUser}}
<h1>{{person.title}}</h1>
<img src={{person.avatar}}>
<p class='signature'>{{person.signature}}</p>
You can use yield
inside a template to
include the contents of any block attached to
the component. The block will be executed in the
context of the surrounding context or outer controller:
{{#person-profile person=currentUser}}
<p>Admin mode</p>
{{! Executed in the controller's context. }}
{{/person-profile}}
<h1>{{person.title}}</h1>
{{! Executed in the component's context. }}
{{yield}} {{! block contents }}
If you want to customize the component, in order to
handle events or actions, you implement a subclass
of Ember.Component
named after the name of the
component.
For example, you could implement the action
hello
for the person-profile
component:
import Ember from 'ember';
export default Ember.Component.extend({
actions: {
hello(name) {
console.log("Hello", name);
}
}
});
And then use it in the component's template:
<h1>{{person.title}}</h1>
{{yield}} <!-- block contents -->
<button {{action 'hello' person.name}}>
Say Hello to {{person.name}}
</button>
Components must have a -
in their name to avoid
conflicts with built-in controls that wrap HTML
elements. This is consistent with the same
requirement in web components.
HTML Tag
The default HTML tag name used for a component's DOM representation is div
.
This can be customized by setting the tagName
property.
The following component class:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'em'
});
Would result in instances with the following HTML:
<em id="ember1" class="ember-view"></em>
HTML class
Attribute
The HTML class
attribute of a component's tag can be set by providing a
classNames
property that is set to an array of strings:
import Ember from 'ember';
export default Ember.Component.extend({
classNames: ['my-class', 'my-other-class']
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view my-class my-other-class"></div>
class
attribute values can also be set by providing a classNameBindings
property set to an array of properties names for the component. The return value
of these properties will be added as part of the value for the components's class
attribute. These properties can be computed properties:
import Ember from 'ember';
export default Ember.Component.extend({
classNameBindings: ['propertyA', 'propertyB'],
propertyA: 'from-a',
propertyB: Ember.computed(function() {
if (someLogic) { return 'from-b'; }
})
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view from-a from-b"></div>
If the value of a class name binding returns a boolean the property name
itself will be used as the class name if the property is true.
The class name will not be added if the value is false
or undefined
.
import Ember from 'ember';
export default Ember.Component.extend({
classNameBindings: ['hovered'],
hovered: true
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view hovered"></div>
When using boolean class name bindings you can supply a string value other
than the property name for use as the class
HTML attribute by appending the
preferred value after a ":" character when defining the binding:
import Ember from 'ember';
export default Ember.Component.extend({
classNameBindings: ['awesome:so-very-cool'],
awesome: true
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view so-very-cool"></div>
Boolean value class name bindings whose property names are in a camelCase-style format will be converted to a dasherized format:
import Ember from 'ember';
export default Ember.Component.extend({
classNameBindings: ['isUrgent'],
isUrgent: true
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view is-urgent"></div>
Class name bindings can also refer to object values that are found by traversing a path relative to the component itself:
import Ember from 'ember';
export default Ember.Component.extend({
classNameBindings: ['messages.empty'],
messages: Ember.Object.create({
empty: true
})
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view empty"></div>
If you want to add a class name for a property which evaluates to true and and a different class name if it evaluates to false, you can pass a binding like this:
import Ember from 'ember';
export default Ember.Component.extend({
classNameBindings: ['isEnabled:enabled:disabled'],
isEnabled: true
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view enabled"></div>
When isEnabled is false
, the resulting HTML representation looks like
this:
<div id="ember1" class="ember-view disabled"></div>
This syntax offers the convenience to add a class if a property is false
:
import Ember from 'ember';
// Applies no class when isEnabled is true and class 'disabled' when isEnabled is false
export default Ember.Component.extend({
classNameBindings: ['isEnabled::disabled'],
isEnabled: true
});
Will result in component instances with an HTML representation of:
<div id="ember1" class="ember-view"></div>
When the isEnabled
property on the component is set to false
, it will result
in component instances with an HTML representation of:
<div id="ember1" class="ember-view disabled"></div>
Updates to the value of a class name binding will result in automatic
update of the HTML class
attribute in the component's rendered HTML
representation. If the value becomes false
or undefined
the class name
will be removed.
Both classNames
and classNameBindings
are concatenated properties. See
Ember.Object documentation for more
information about concatenated properties.
HTML Attributes
The HTML attribute section of a component's tag can be set by providing an
attributeBindings
property set to an array of property names on the component.
The return value of these properties will be used as the value of the component's
HTML associated attribute:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'a',
attributeBindings: ['href'],
href: 'http://google.com'
});
Will result in component instances with an HTML representation of:
<a id="ember1" class="ember-view" href="http://google.com"></a>
One property can be mapped on to another by placing a ":" between the source property and the destination property:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'a',
attributeBindings: ['url:href'],
url: 'http://google.com'
});
Will result in component instances with an HTML representation of:
<a id="ember1" class="ember-view" href="http://google.com"></a>
Namespaced attributes (e.g. xlink:href
) are supported, but have to be
mapped, since :
is not a valid character for properties in Javascript:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'use',
attributeBindings: ['xlinkHref:xlink:href'],
xlinkHref: '#triangle'
});
Will result in component instances with an HTML representation of:
<use xlink:href="#triangle"></use>
If the return value of an attributeBindings
monitored property is a boolean
the attribute will be present or absent depending on the value:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'input',
attributeBindings: ['disabled'],
disabled: false
});
Will result in a component instance with an HTML representation of:
<input id="ember1" class="ember-view" />
attributeBindings
can refer to computed properties:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'input',
attributeBindings: ['disabled'],
disabled: Ember.computed(function() {
if (someLogic) {
return true;
} else {
return false;
}
})
});
To prevent setting an attribute altogether, use null
or undefined
as the
return value of the attributeBindings
monitored property:
import Ember from 'ember';
export default Ember.Component.extend({
tagName: 'form',
attributeBindings: ['novalidate'],
novalidate: null
});
Updates to the property of an attribute binding will result in automatic
update of the HTML attribute in the component's rendered HTML representation.
attributeBindings
is a concatenated property. See Ember.Object
documentation for more information about concatenated properties.
Layouts
See Ember.Templates.helpers.yield for more information.
Responding to Browser Events
Components can respond to user-initiated events in one of three ways: method
implementation, through an event manager, and through {{action}}
helper use
in their template or layout.
Method Implementation
Components can respond to user-initiated events by implementing a method that
matches the event name. A jQuery.Event
object will be passed as the
argument to this method.
import Ember from 'ember';
export default Ember.Component.extend({
click(event) {
// will be called when an instance's
// rendered element is clicked
}
});
{{action}}
Helper
See Ember.Templates.helpers.action.
Event Names
All of the event handling approaches described above respond to the same set
of events. The names of the built-in events are listed below. (The hash of
built-in events exists in Ember.EventDispatcher
.) Additional, custom events
can be registered by using Ember.Application.customEvents
.
Touch events:
touchStart
touchMove
touchEnd
touchCancel
Keyboard events:
keyDown
keyUp
keyPress
Mouse events:
mouseDown
mouseUp
contextMenu
click
doubleClick
mouseMove
focusIn
focusOut
mouseEnter
mouseLeave
Form events:
submit
change
focusIn
focusOut
input
HTML5 drag and drop events:
dragStart
drag
dragEnter
dragLeave
dragOver
dragEnd
drop
Item Index
Methods
- $
- _lazyInjections
- _onLookup
- _scheduledDestroy
- addObserver
- append
- appendTo
- beginPropertyChanges
- cacheFor
- decrementProperty
- destroy
- didReceiveAttrs
- didRender
- didUpdate
- didUpdateAttrs
- endPropertyChanges
- findElementInParentElement
- get
- getChildViews
- getProperties
- getRootViews
- getViewBoundingClientRect
- getViewBounds
- getViewClientRects
- getViewElement
- getViewId
- getViewRange
- getWithDefault
- handleEvent
- has
- hasObserverFor
- incrementProperty
- init
- matches
- nearestOfType deprecated
- nearestWithProperty deprecated
- notifyPropertyChange
- off
- on
- one
- propertyDidChange
- propertyWillChange
- readDOMAttr
- removeObserver
- renderToElement deprecated
- reopen
- reopenClass
- replaceIn
- rerender
- send
- sendAction
- set
- setProperties
- toggleProperty
- toString
- trigger
- triggerAction
- willDestroy
- willRender
- willUpdate
Properties
Methods
$
-
[selector]
Returns a jQuery object for this component'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 component.$('li')
will return a jQuery object containing
all of the li
elements inside the DOM element of this component.
Parameters:
-
[selector]
String optionala jQuery-compatible selector string
Returns:
the jQuery object for the DOM node
_lazyInjections
()
Object
private
Returns:
_onLookup
()
private
_scheduledDestroy
()
private
destroy
method.
addObserver
-
key
-
target
-
method
context
parameter:
`
javascript
fooDidChange: function(sender, key, value, rev) { };
`
The sender is the object that changed. The key is the property that
changes. The value property is currently reserved and unused. The rev
is the last property revision of the object when it changed, which you can
use to detect if the key value has really changed or not.
If you pass a context
parameter, the context will be passed before the
revision like so:
`
javascript
fooDidChange: function(sender, key, value, context, rev) { };
`
Usually you will not need the value, context or revision parameters at
the end. In this case, it is common to write observer methods that take
only a sender and key value as parameters or, if you aren't interested in
any of these values, to write an observer that has no parameters at all.
append
()
Ember.View
private
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:
appendTo
-
A
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 | JQueryselector, element, HTML string, or jQuery object
Returns:
beginPropertyChanges
()
Ember.Observable
private
endPropertyChanges()
to deliver the deferred change notifications and end
deferring.
Returns:
cacheFor
-
keyName
Parameters:
-
keyName
String
Returns:
decrementProperty
-
keyName
-
decrement
`
javascript
player.decrementProperty('lives');
orc.decrementProperty('health', 5);
`
Parameters:
-
keyName
StringThe name of the property to decrement -
decrement
NumberThe amount to decrement by. Defaults to 1
Returns:
destroy
()
private
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.
didReceiveAttrs
()
public
Called when the attributes passed into the component have been updated. Called both during the initial render of a container and during a rerender. Can be used in place of an observer; code placed here will be executed every time any attribute updates.
didRender
()
public
Called after a component has been rendered, both on initial render and in subsequent rerenders.
didUpdate
()
public
Called when the component has updated and rerendered itself. Called only during a rerender, not during an initial render.
didUpdateAttrs
()
public
Called when the attributes passed into the component have been changed. Called only during a rerender, not during an initial render.
endPropertyChanges
()
Ember.Observable
private
beginPropertyChanges()
at the beginning of the changes to defer change
notifications. When you are done making changes, call this method to
deliver the deferred change notifications and end deferring.
Returns:
findElementInParentElement
-
parentElement
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
DOMElementThe parent's DOM element
Returns:
get
-
keyName
object[keyName]
or object.keyName
,
however it supports both computed properties and the unknownProperty
handler.
Because get
unifies the syntax for accessing all these kinds
of properties, it can make many refactorings easier, such as replacing a
simple property with a computed property, or vice versa.
### Computed Properties
Computed properties are methods defined with the property
modifier
declared at the end, such as:
`
javascript
fullName: Ember.computed('firstName', 'lastName', function() {
return this.get('firstName') + ' ' + this.get('lastName');
})
`
When you call get
on a computed property, the function will be
called and the return value will be returned instead of the function
itself.
### Unknown Properties
Likewise, if you try to call get
on a property whose value is
undefined
, the unknownProperty()
method will be called on the object.
If this method returns any value other than undefined
, it will be returned
instead. This allows you to implement "virtual" properties that are
not defined upfront.
Parameters:
-
keyName
StringThe property to retrieve
Returns:
getProperties
-
list
getProperties
with a list of strings or an array:
`
javascript
record.getProperties('firstName', 'lastName', 'zipCode');
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
`
is equivalent to:
`
javascript
record.getProperties(['firstName', 'lastName', 'zipCode']);
// { firstName: 'John', lastName: 'Doe', zipCode: '10011' }
`
Parameters:
-
list
String... | Arrayof keys to get
Returns:
getRootViews
-
owner
Parameters:
-
owner
Object
getViewBoundingClientRect
-
view
getViewBoundingClientRect
provides information about the position of the
bounding border box edges of a view relative to the viewport.
It is only intended to be used by development tools like the Ember Inpsector
and may not work on older browsers.
Parameters:
-
view
Ember.View
getViewClientRects
-
view
getViewClientRects
provides information about the position of the border
box edges of a view relative to the viewport.
It is only intended to be used by development tools like the Ember Inspector
and may not work on older browsers.
Parameters:
-
view
Ember.View
getWithDefault
-
keyName
-
defaultValue
undefined
.
`
javascript
person.getWithDefault('lastName', 'Doe');
`
Parameters:
-
keyName
StringThe name of the property to retrieve -
defaultValue
ObjectThe value to return if the property value is undefined
Returns:
handleEvent
-
eventName
-
evt
Ember.EventDispatcher
Parameters:
-
eventName
String -
evt
Event
has
-
name
Parameters:
-
name
StringThe name of the event
Returns:
hasObserverFor
-
key
true
if the object currently has observers registered for a
particular key. You can use this method to potentially defer performing
an expensive action until someone begins observing a particular property
on the object.
Parameters:
-
key
StringKey to check
Returns:
incrementProperty
-
keyName
-
increment
`
javascript
person.incrementProperty('age');
team.incrementProperty('score', 2);
`
Parameters:
-
keyName
StringThe name of the property to increment -
increment
NumberThe amount to increment by. Defaults to 1
Returns:
init
()
private
childViews
* register the view with the global views hash, which is used for event
dispatch
matches
-
el
-
selector
Parameters:
-
el
DOMElement -
selector
String
nearestOfType
-
klass
Parameters:
-
klass
Class,MixinSubclass of Ember.View (or Ember.View itself), or an instance of Ember.Mixin.
Returns:
nearestWithProperty
-
property
Parameters:
-
property
StringA property name
Returns:
notifyPropertyChange
-
keyName
propertyWillChange
and propertyDidChange
in
succession.
Parameters:
-
keyName
StringThe property key to be notified about.
Returns:
off
-
name
-
target
-
method
Parameters:
Returns:
on
-
name
-
[target]
-
method
`
javascript
person.on('didLoad', function() {
// fired once the person has loaded
});
`
An optional target can be passed in as the 2nd argument that will
be set as the "this" for the callback. This is a good way to give your
function access to the object triggering the event. When the target
parameter is used the callback becomes the third argument.
Parameters:
Returns:
one
-
name
-
[target]
-
method
`one
` when
you only care about the first time an event has taken place.
This function takes an optional 2nd argument that will become the "this"
value for the callback. If this argument is passed then the 3rd argument
becomes the function.
Parameters:
Returns:
propertyDidChange
-
keyName
get()
or set()
on it. In this case, you can use this
method and propertyWillChange()
instead. Calling these two methods
together will notify all observers that the property has potentially
changed value.
Note that you must always call propertyWillChange
and propertyDidChange
as a pair. If you do not, it may get the property change groups out of
order and cause notifications to be delivered more often than you would
like.
Parameters:
-
keyName
StringThe property key that has just changed.
Returns:
propertyWillChange
-
keyName
get()
or set()
on it. In this case, you can use this
method and propertyDidChange()
instead. Calling these two methods
together will notify all observers that the property has potentially
changed value.
Note that you must always call propertyWillChange
and propertyDidChange
as a pair. If you do not, it may get the property change groups out of
order and cause notifications to be delivered more often than you would
like.
Parameters:
-
keyName
StringThe property key that is about to change.
Returns:
readDOMAttr
-
name
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
Stringthe name of the attribute
Returns:
String
removeObserver
-
key
-
target
-
method
addObserver()
and your
target will no longer receive notifications.
renderToElement
-
tagName
BODY
element,
since this is the default context that views are rendered into when being
inserted directly into the DOM.
`
js
let element = view.renderToElement();
element.tagName; // => "BODY"
`
You can override the kind of element rendered into and returned by
specifying an optional tag name as the first argument.
`
js
let element = view.renderToElement('table');
element.tagName; // => "TABLE"
`
This method is useful if you want to render the view into an element that
is not in the document's body. Instead, a new body
element, detached from
the DOM is returned. FastBoot uses this to serialize the rendered view into
a string for transmission over the network.
`
js
app.visit('/').then(function(instance) {
let element;
Ember.run(function() {
element = renderToElement(instance);
});
res.send(serialize(element));
});
`
Parameters:
-
tagName
StringThe tag of the element to create and render into. Defaults to "body".
Returns:
reopen
()
public
`
javascript
const MyObject = Ember.Object.extend({
name: 'an object'
});
o = MyObject.create();
o.get('name'); // 'an object'
MyObject.reopen({
say(msg){
console.log(msg);
}
})
o2 = MyObject.create();
o2.say("hello"); // logs "hello"
o.say("goodbye"); // logs "goodbye"
`
To add functions and properties to the constructor itself,
see reopenClass
reopenClass
()
public
`
javascript
const MyObject = Ember.Object.extend({
name: 'an object'
});
MyObject.reopenClass({
canBuild: false
});
MyObject.canBuild; // false
o = MyObject.create();
`
In other words, this creates static properties and functions for the class.
These are only available on the class and not on any instance of that class.
`
javascript
const Person = Ember.Object.extend({
name: "",
sayHello() {
alert("Hello. My name is " + this.get('name'));
}
});
Person.reopenClass({
species: "Homo sapiens",
createPerson(newPersonsName){
return Person.create({
name:newPersonsName
});
}
});
let tom = Person.create({
name: "Tom Dale"
});
let yehuda = Person.createPerson("Yehuda Katz");
tom.sayHello(); // "Hello. My name is Tom Dale"
yehuda.sayHello(); // "Hello. My name is Yehuda Katz"
alert(Person.species); // "Homo sapiens"
`
Note that species
and createPerson
are *not* valid on the tom
and yehuda
variables. They are only valid on Person
.
To add functions and properties to instances of
a constructor by extending the constructor's prototype
see reopen
replaceIn
-
target
Parameters:
-
target
String | DOMElement | JQueryA selector, element, HTML string, or jQuery object
Returns:
rerender
()
public
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.
send
-
actionName
-
context
ActionHandler
. Any parameters
supplied after the actionName
string will be passed as arguments
to the action target function.
If the ActionHandler
has its target
property set, actions may
bubble to the target
. Bubbling happens when an actionName
can
not be found in the ActionHandler
's actions
hash or if the
action target function returns true
.
Example
`
js
App.WelcomeRoute = Ember.Route.extend({
actions: {
playTheme() {
this.send('playMusic', 'theme.mp3');
},
playMusic(track) {
// ...
}
}
});
`
Parameters:
-
actionName
StringThe action to trigger -
context
a context to send with the action
sendAction
-
[action]
-
[params]
`
javascript
// app/components/play-button.js
export default Ember.Component.extend({
click() {
if (this.get('isPlaying')) {
this.sendAction('play');
} else {
this.sendAction('stop');
}
}
});
`
The actions "play" and "stop" must be passed to this play-button
component:
`
handlebars
{{! app/templates/application.hbs }}
{{play-button play=(action "musicStarted") stop=(action "musicStopped")}}
`
When the component receives a browser click
event it translate this
interaction into application-specific semantics ("play" or "stop") and
calls the specified action.
`
javascript
// app/controller/application.js
export default Ember.Controller.extend({
actions: {
musicStarted() {
// called when the play button is clicked
// and the music started playing
},
musicStopped() {
// called when the play button is clicked
// and the music stopped playing
}
}
});
`
If no action is passed to sendAction
a default name of "action"
is assumed.
`
javascript
// app/components/next-button.js
export default Ember.Component.extend({
click() {
this.sendAction();
}
});
`
`
handlebars
{{! app/templates/application.hbs }}
{{next-button action=(action "playNextSongInAlbum")}}
`
`
javascript
// app/controllers/application.js
App.ApplicationController = Ember.Controller.extend({
actions: {
playNextSongInAlbum() {
...
}
}
});
`
Parameters:
-
[action]
String optionalthe action to call -
[params]
optionalarguments for the action
set
-
keyName
-
value
`
javascript
record.set("key", value);
`
This method is generally very similar to calling object["key"] = value
or
object.key = value
, except that it provides support for computed
properties, the setUnknownProperty()
method and property observers.
### Computed Properties
If you try to set a value on a key that has a computed property handler
defined (see the get()
method for an example), then set()
will call
that method, passing both the value and key instead of simply changing
the value itself. This is useful for those times when you need to
implement a property that is composed of one or more member
properties.
### Unknown Properties
If you try to set a value on a key that is undefined in the target
object, then the setUnknownProperty()
handler will be called instead. This
gives you an opportunity to implement complex "virtual" properties that
are not predefined on the object. If setUnknownProperty()
returns
undefined, then set()
will simply set the value on the object.
### Property Observers
In addition to changing the property, set()
will also register a property
change with the object. Unless you have placed this call inside of a
beginPropertyChanges()
and endPropertyChanges(),
any "local" observers
(i.e. observer methods declared on the same object), will be called
immediately. Any "remote" observers (i.e. observer methods declared on
another object) will be placed in a queue and called at a later time in a
coalesced manner.
Parameters:
-
keyName
StringThe property to set -
value
ObjectThe value to set ornull
.
Returns:
setProperties
-
hash
beginPropertyChanges
and endPropertyChanges
batch, so
observers will be buffered.
`
javascript
record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });
`
Parameters:
-
hash
Objectthe hash of keys and values to set
Returns:
toggleProperty
-
keyName
`
javascript
starship.toggleProperty('warpDriveEngaged');
`
Parameters:
-
keyName
StringThe name of the property to toggle
Returns:
toString
()
String
public
toString
typically does, in a generic way for all Ember
objects.
`
javascript
const Person = Ember.Object.extend()
person = Person.create()
person.toString() //=> "`
If the object's class is not defined on an Ember namespace, it will
indicate it is a subclass of the registered superclass:
`
javascript
const Student = Person.extend()
let student = Student.create()
student.toString() //=> "<(subclass of Person):ember1025>"
`
If the method toStringExtension
is defined, its return value will be
included in the output.
`
javascript
const Teacher = Person.extend({
toStringExtension() {
return this.get('fullName');
}
});
teacher = Teacher.create()
teacher.toString(); //=> "`
Returns:
trigger
-
name
Ember.Evented
to
also call methods with the given name.
Parameters:
-
name
String
triggerAction
-
opts
action
with an actionContext
to a target
. The action, actionContext
and target will be retrieved from properties of the object. For example:
`
javascript
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.
`
javascript
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:
`
javascript
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:
willDestroy
()
public
willRender
()
public
Called before a component has been rendered, both on initial render and in subsequent rerenders.
willUpdate
()
public
Called when the component is about to update and rerender itself. Called only during a rerender, not during an initial render.
Properties
actions
Object
public
ActionHandler
as action targets.
These functions will be invoked when a matching {{action}}
is triggered
from within a template and the application's current route is this route.
Actions can also be invoked from other parts of your application
via ActionHandler#send
.
The actions
hash will inherit action handlers from
the actions
hash defined on extended parent classes
or mixins rather than just replace the entire hash, e.g.:
`
js
App.CanDisplayBanner = Ember.Mixin.create({
actions: {
displayBanner(msg) {
// ...
}
}
});
App.WelcomeRoute = Ember.Route.extend(App.CanDisplayBanner, {
actions: {
playMusic() {
// ...
}
}
});
// WelcomeRoute
, when active, will be able to respond
// to both actions, since the actions hash is merged rather
// then replaced when extending mixins / parent classes.
this.send('displayBanner');
this.send('playMusic');
`
Within a Controller, Route or Component's action handler,
the value of the this
context is the Controller, Route or
Component object:
`
js
App.SongRoute = Ember.Route.extend({
actions: {
myAction() {
this.controllerFor("song");
this.transitionTo("other.route");
...
}
}
});
`
It is also possible to call this._super(...arguments)
from within an
action handler if it overrides a handler defined on a parent
class or mixin:
Take for example the following routes:
`
js
App.DebugRoute = Ember.Mixin.create({
actions: {
debugRouteInformation() {
console.debug("trololo");
}
}
});
App.AnnoyingDebugRoute = Ember.Route.extend(App.DebugRoute, {
actions: {
debugRouteInformation() {
// also call the debugRouteInformation of mixed in App.DebugRoute
this._super(...arguments);
// show additional annoyance
window.alert(...);
}
}
});
`
## Bubbling
By default, an action will stop bubbling once a handler defined
on the actions
hash handles it. To continue bubbling the action,
you must return true
from the handler:
`
js
App.Router.map(function() {
this.route("album", function() {
this.route("song");
});
});
App.AlbumRoute = Ember.Route.extend({
actions: {
startPlaying: function() {
}
}
});
App.AlbumSongRoute = Ember.Route.extend({
actions: {
startPlaying() {
// ...
if (actionShouldAlsoBeTriggeredOnParentRoute) {
return true;
}
}
}
});
`
Default: null
ariaRole
String
public
The WAI-ARIA role of the control represented by this view. For example, a button may have a role of type 'button', or a pane may have a role of type 'alertdialog'. This property is used by assistive software to help visually challenged users navigate rich web applications.
The full list of valid WAI-ARIA roles is available at: http://www.w3.org/TR/wai-aria/roles#roles_categorization
Default: null
childViews
Array
private
Default: []
classNameBindings
Array
public
`
javascript
// Applies the 'high' class to the view element
Ember.Component.extend({
classNameBindings: ['priority'],
priority: 'high'
});
`
If the value of the property is a Boolean, the name of that property is
added as a dasherized class name.
`
javascript
// Applies the 'is-urgent' class to the view element
Ember.Component.extend({
classNameBindings: ['isUrgent'],
isUrgent: true
});
`
If you would prefer to use a custom value instead of the dasherized
property name, you can pass a binding like this:
`
javascript
// Applies the 'urgent' class to the view element
Ember.Component.extend({
classNameBindings: ['isUrgent:urgent'],
isUrgent: true
});
`
This list of properties is inherited from the component's superclasses as well.
Default: []
classNames
Array
public
Default: ['ember-view']
concatenatedProperties
Array
public
classNames
property of Ember.View
.
Here is some sample code showing the difference between a concatenated
property and a normal one:
`
javascript
const Bar = Ember.Object.extend({
// Configure which properties to concatenate
concatenatedProperties: ['concatenatedProperty'],
someNonConcatenatedProperty: ['bar'],
concatenatedProperty: ['bar']
});
const FooBar = Bar.extend({
someNonConcatenatedProperty: ['foo'],
concatenatedProperty: ['foo']
});
let fooBar = FooBar.create();
fooBar.get('someNonConcatenatedProperty'); // ['foo']
fooBar.get('concatenatedProperty'); // ['bar', 'foo']
`
This behavior extends to object creation as well. Continuing the
above example:
`
javascript
let fooBar = FooBar.create({
someNonConcatenatedProperty: ['baz'],
concatenatedProperty: ['baz']
})
fooBar.get('someNonConcatenatedProperty'); // ['baz']
fooBar.get('concatenatedProperty'); // ['bar', 'foo', 'baz']
`
Adding a single property that is not an array will just add it in the array:
`
javascript
let fooBar = FooBar.create({
concatenatedProperty: 'baz'
})
view.get('concatenatedProperty'); // ['bar', 'foo', 'baz']
`
Using the concatenatedProperties
property, we can tell Ember to mix the
content of the properties.
In Ember.Component
the classNames
, classNameBindings
and
attributeBindings
properties are concatenated.
This feature is available for you to use throughout the Ember object model,
although typical app developers are likely to use it infrequently. Since
it changes expectations about behavior of properties, you should properly
document its usage in each individual concatenated property (to not
mislead your users to think they can override the property in a subclass).
Default: null
element
DOMElement
public
elementId
String
public
The HTML id
of the component's element in the DOM. You can provide this
value yourself but it must be unique (just as in HTML):
{{my-component elementId="a-really-cool-id"}}
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:
export default Ember.Component.extend({
init() {
this._super(...arguments);
var index = this.get('index');
this.set('elementId', component-id${index}
);
}
});
isDestroyed
Unknown
public
true
the observers and bindings were already
removed by the effect of calling the destroy()
method.
Default: false
isDestroying
Unknown
public
destroy()
method has been called.
The object stays intact until the end of the run loop at which point
the isDestroyed
flag is set.
Default: false
isVisible
Boolean
public
If false
, the view will appear hidden in DOM.
Default: null
layout
Function
public
A component 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 component (or alternatively, call Handlebars.helpers.yield
,
{{yield}}
) to render it in the correct location.
This is useful for a component 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.Component
will lookup a template with this name in
Ember.TEMPLATES
(a shared global object).
Default: null
mergedProperties
Array
public
queryParams
property of routes.
Here is some sample code showing the difference between a merged
property and a normal one:
`
javascript
const Bar = Ember.Object.extend({
// Configure which properties are to be merged
mergedProperties: ['mergedProperty'],
someNonMergedProperty: {
nonMerged: 'superclass value of nonMerged'
},
mergedProperty: {
page: {replace: false},
limit: {replace: true}
}
});
const FooBar = Bar.extend({
someNonMergedProperty: {
completelyNonMerged: 'subclass value of nonMerged'
},
mergedProperty: {
limit: {replace: false}
}
});
let fooBar = FooBar.create();
fooBar.get('someNonMergedProperty');
// => { completelyNonMerged: 'subclass value of nonMerged' }
//
// Note the entire object, including the nonMerged property of
// the superclass object, has been replaced
fooBar.get('mergedProperty');
// => {
// page: {replace: false},
// limit: {replace: false}
// }
//
// Note the page remains from the superclass, and the
// limit
property's value of false
has been merged from
// the subclass.
`
This behavior is not available during object create
calls. It is only
available at extend
time.
In Ember.Route
the queryParams
property is merged.
This feature is available for you to use throughout the Ember object model,
although typical app developers are likely to use it infrequently. Since
it changes expectations about behavior of properties, you should properly
document its usage in each individual merged property (to not
mislead your users to think they can override the property in a subclass).
Default: null
parentView
Ember.View
private
Default: null
positionalParams
Unknown
public
static
Enables components to take a list of parameters as arguments.
For example, a component that takes two parameters with the names
name
and age
:
let MyComponent = Ember.Component.extend;
MyComponent.reopenClass({
positionalParams: ['name', 'age']
});
It can then be invoked like this:
{{my-component "John" 38}}
The parameters can be referred to just like named parameters:
Name: {{name}}, Age: {{age}}.
Using a string instead of an array allows for an arbitrary number of parameters:
let MyComponent = Ember.Component.extend;
MyComponent.reopenClass({
positionalParams: 'names'
});
It can then be invoked like this:
{{my-component "John" "Michael" "Scott"}}
The parameters can then be referred to by enumerating over the list:
{{#each names as |name|}}{{name}}{{/each}}
tagName
String
public
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
Events
didInsertElement
public
didReceiveAttrs
public
Called when the attributes passed into the component have been updated. Called both during the initial render of a container and during a rerender. Can be used in place of an observer; code placed here will be executed every time any attribute updates.
didRender
public
Called after a component has been rendered, both on initial render and in subsequent rerenders.
didUpdate
public
Called when the component has updated and rerendered itself. Called only during a rerender, not during an initial render.
didUpdateAttrs
public
Called when the attributes passed into the component have been changed. Called only during a rerender, not during an initial render.
parentViewDidChange
private
willClearRender
public
willDestroyElement
public
willInsertElement
public
willRender
public
Called before a component has been rendered, both on initial render and in subsequent rerenders.
willUpdate
public
Called when the component is about to update and rerender itself. Called only during a rerender, not during an initial render.