Class Ember.CollectionView

Extends: Ember.ContainerView
Defined in: packages/ember-views/lib/views/collection_view.js:11
Module: ember
Since: vEmber 0.9

Ember.CollectionView is an Ember.View descendent responsible for managing a collection (an array or array-like object) by maintaining a child view object and associated DOM representation for each item in the array and ensuring that child views and their associated rendered HTML are updated when items in the array are added, removed, or replaced.

Setting content

The managed collection of objects is referenced as the Ember.CollectionView instance's content property.

1
2
3

someItemsView = Ember.CollectionView.create({
  content: ['A', 'B','C']
})

The view for each item in the collection will have its content property set to the item.

Specifying itemViewClass

By default the view class for each item in the managed collection will be an instance of Ember.View. You can supply a different class by setting the CollectionView's itemViewClass property.

Given an empty <body> and the following code:

1
2
3
4
5
6
7
8
9

someItemsView = Ember.CollectionView.create({
  classNames: ['a-collection'],
  content: ['A','B','C'],
  itemViewClass: Ember.View.extend({
    template: Ember.Handlebars.compile("the letter: {{view.content}}")
  })
});

someItemsView.appendTo('body');

Will result in the following HTML structure

1
2
3
4
5

<div class="ember-view a-collection">
  <div class="ember-view">the letter: A</div>
  <div class="ember-view">the letter: B</div>
  <div class="ember-view">the letter: C</div>
</div>

Automatic matching of parent/child tagNames

Setting the tagName property of a CollectionView to any of "ul", "ol", "table", "thead", "tbody", "tfoot", "tr", or "select" will result in the item views receiving an appropriately matched tagName property.

Given an empty <body> and the following code:

1
2
3
4
5
6
7
8
9

anUndorderedListView = Ember.CollectionView.create({
  tagName: 'ul',
  content: ['A','B','C'],
  itemViewClass: Ember.View.extend({
    template: Ember.Handlebars.compile("the letter: {{view.content}}")
  })
});

anUndorderedListView.appendTo('body');

Will result in the following HTML structure

1
2
3
4
5

<ul class="ember-view a-collection">
  <li class="ember-view">the letter: A</li>
  <li class="ember-view">the letter: B</li>
  <li class="ember-view">the letter: C</li>
</ul>

Additional tagName pairs can be provided by adding to Ember.CollectionView.CONTAINER_MAP

1

Ember.CollectionView.CONTAINER_MAP['article'] = 'section'

Programatic creation of child views

For cases where additional customization beyond the use of a single itemViewClass or tagName matching is required CollectionView's createChildView method can be overidden:

1
2
3
4
5
6
7
8
9
10

CustomCollectionView = Ember.CollectionView.extend({
  createChildView: function(viewClass, attrs) {
    if (attrs.content.kind == 'album') {
      viewClass = App.AlbumView;
    } else {
      viewClass = App.SongView;
    }
    return this._super(viewClass, attrs);
  }
});

Empty View

You can provide an Ember.View subclass to the Ember.CollectionView instance as its emptyView property. If the content property of a CollectionView is set to null or an empty array, an instance of this view will be the CollectionViews only child.

1
2
3
4
5
6
7
8
9

aListWithNothing = Ember.CollectionView.create({
  classNames: ['nothing']
  content: null,
  emptyView: Ember.View.extend({
    template: Ember.Handlebars.compile("The collection is empty")
  })
});

aListWithNothing.appendTo('body');

Will result in the following HTML structure

1
2
3
4
5

<div class="ember-view nothing">
  <div class="ember-view">
    The collection is empty
  </div>
</div>

Adding and Removing items

The childViews property of a CollectionView should not be directly manipulated. Instead, add, remove, replace items from its content property. This will trigger appropriate changes to its rendered HTML.

Show:

CONTAINER_MAP

Module: ember

Defined in packages/ember-views/lib/views/collection_view.js:407

A map of parent tags to their default child tags. You can add additional parent tags if you want collection views that use a particular parent tag to default to a child tag.

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.

content

Module: ember

Defined in packages/ember-views/lib/views/collection_view.js:161

A list of items to be displayed by the Ember.CollectionView.

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.

emptyView

Module: ember

Defined in packages/ember-views/lib/views/collection_view.js:181

An optional view to display if content is set to an empty array.

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.

itemViewClass

Module: ember

Defined in packages/ember-views/lib/views/collection_view.js:190

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.

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