Class Ember.Component

Extends: Ember.View
Defined in: packages/ember-views/lib/views/component.js:10
Module: ember

An Ember.Component is a view that is completely isolated. Property access 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 is 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 {{bind-attr src=person.avatar}}>
<p class='signature'>{{person.signature}}</p>

You can also use yield inside a template to include the contents of the custom tag:

1
2
3

{{#app-profile person=currentUser}}
  <p>Admin mode</p>
{{/app-profile}}
 
1
2
3

<!-- app-profile template -->
<h1>{{person.title}}</h1>
{{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

App.AppProfileComponent = Ember.Component.extend({
  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:

ariaRole

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1867

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

attributeBindings

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1936

A list of properties of the view to apply as attributes. If the property is a string value, the value of that string will be applied as the attribute.

1
2
3
4
5
6

// Applies the type attribute to the element
// with the value "button", like <div type="button">
Ember.View.extend({
  attributeBindings: ['type'],
  type: 'button'
});

If the value of the property is a Boolean, the name of that property is added as an attribute.

1
2
3
4
5

// Renders something like <div enabled="enabled">
Ember.View.extend({
  attributeBindings: ['enabled'],
  enabled: true
});

classNameBindings

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1893

A list of properties of the view to apply as class names. If the property is a string value, the value of that string will be applied as a class name.

1
2
3
4
5

// Applies the 'high' class to the view element
Ember.View.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.

1
2
3
4
5

// Applies the 'is-urgent' class to the view element
Ember.View.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:

1
2
3
4
5

// Applies the 'urgent' class to the view element
Ember.View.extend({
  classNameBindings: ['isUrgent:urgent']
  isUrgent: true
});

This list of properties is inherited from the view's superclasses as well.

classNames

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1882

Standard CSS class names to apply to the view's outer element. This property automatically inherits any class names defined by the view's superclasses as well.

concatenatedProperties

Module: ember

Inherited from Ember.CoreObject packages/ember-runtime/lib/system/core_object.js:202

Defines the properties that will be concatenated from the superclass (instead of overridden).

By default, when you extend an Ember class a property defined in the subclass overrides a property with the same name that is defined in the superclass. However, there are some cases where it is preferable to build up a property's value by combining the superclass' property value with the subclass' value. An example of this in use within Ember is the classNames property of Ember.View.

Here is some sample code showing the difference between a concatenated property and a normal one:

1
2
3
4
5
6
7
8
9
10
11
12
13

App.BarView = Ember.View.extend({
  someNonConcatenatedProperty: ['bar'],
  classNames: ['bar']
});

App.FooBarView = App.BarView.extend({
  someNonConcatenatedProperty: ['foo'],
  classNames: ['foo'],
});

var fooBarView = App.FooBarView.create();
fooBarView.get('someNonConcatenatedProperty'); // ['foo']
fooBarView.get('classNames'); // ['ember-view', 'bar', 'foo']

This behavior extends to object creation as well. Continuing the above example:

1
2
3
4
5
6

var view = App.FooBarView.create({
  someNonConcatenatedProperty: ['baz'],
  classNames: ['baz']
})
view.get('someNonConcatenatedProperty'); // ['baz']
view.get('classNames'); // ['ember-view', 'bar', 'foo', 'baz']

Adding a single property that is not an array will just add it in the array:

1
2
3
4

var view = App.FooBarView.create({
  classNames: 'baz'
})
view.get('classNames'); // ['ember-view', 'bar', 'foo', 'baz']

Using the concatenatedProperties property, we can tell to Ember that mix the content of the properties.

In Ember.View the classNameBindings and attributeBindings properties are also concatenated, in addition to classNames.

This feature is available for you to use throughout the Ember object model, although typical app developers are likely to use it infrequently.

context

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:962

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

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:913

The controller managing this view. If this property is set, it will be made available for use by the template.

element

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1404

Returns the current DOM element for the view.

isDestroyed

Module: ember

Inherited from Ember.CoreObject packages/ember-runtime/lib/system/core_object.js:267

Destroyed object property flag.

if this property is true the observers and bindings were already removed by the effect of calling the destroy() method.

isDestroying

Module: ember

Inherited from Ember.CoreObject packages/ember-runtime/lib/system/core_object.js:278

Destruction scheduled flag. The destroy() method has been called.

The object stays intact until the end of the run loop at which point the isDestroyed flag is set.

isView

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:840

concatenatedProperties: ['classNames', 'classNameBindings', 'attributeBindings'], /**

isVisible

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1029

If false, the view will appear hidden in DOM.

layout

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:925

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

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:869

The name of the layout to lookup if no layout is provided.

Ember.View will look for a template with this name in this view's templates object. By default, this will be a global object shared in Ember.TEMPLATES.

nearestChildOf

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1126

returns
Ember.View

Return the nearest ancestor whose parent is an instance of klass.

nearestOfType

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1089

returns
Ember.View

Return the nearest ancestor that is an instance of the provided class or mixin.

nearestWithProperty

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1110

returns
Ember.View

Return the nearest ancestor that has a given property.

parentView

Module: ember

Inherited from Ember.CoreView packages/ember-views/lib/views/view.js:78

If the view is currently inserted into the DOM of a parent view, this property will point to the parent of the view.

tagName

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:1851

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.

targetObject

Module: ember

Defined in packages/ember-views/lib/views/component.js:124

If the component is currently inserted into the DOM of a parent view, this property will point to the controller of the parent view.

template

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:891

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

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:856

The name of the template to lookup if no template is provided.

Ember.View will look for a template with this name in this view's templates object. By default, this will be a global object shared in Ember.TEMPLATES.

templates

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:882

The hash in which to look for templateName.

views

Module: ember

Inherited from Ember.View packages/ember-views/lib/views/view.js:2467

Global views hash