Class Ember.Component

public

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 components/my-foo, you will be able to use {{my-foo}} in other templates, which will make an instance of the isolated component.

1
{{app-profile person=currentUser}}
1
2
3
4
<!-- app-profile template -->
<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:

1
2
3
4
{{#app-profile person=currentUser}}
  <p>Admin mode</p>
  {{! Executed in the controller's context. }}
{{/app-profile}}
1
2
3
4
<!-- app-profile template -->
<h1>{{person.title}}</h1>
{{! Executed in the components 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. Note that Component needs to be appended to the name of your subclass like AppProfileComponent.

For example, you could implement the action hello for the app-profile component:

1
2
3
4
5
6
7
App.AppProfileComponent = Ember.Component.extend({
  actions: {
    hello: function(name) {
      console.log("Hello", name);
    }
  }
});

And then use it in the component's template:

1
2
3
4
5
6
7
8
<!-- app-profile 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.

Show:

Module: ember

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.

Module: ember

Available since v1.13.0

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.

Module: ember

Available since v1.13.0

Called after a component has been rendered, both on initial render and in subsequent rerenders.

Module: ember

Available since v1.13.0

Called when the component has updated and rerendered itself. Called only during a rerender, not during an initial render.

Module: ember

Available since v1.13.0

Called when the attributes passed into the component have been changed. Called only during a rerender, not during an initial render.

Module: ember

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

Module: ember

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.

Module: ember

Called when a view is going to insert an element into the DOM.

Module: ember

Available since v1.13.0

Called before a component has been rendered, both on initial render and in subsequent rerenders.

Module: ember

Available since v1.13.0

Called when the component is about to update and rerender itself. Called only during a rerender, not during an initial render.