Class Ember.ContainerView

Extends: Ember.View
Defined in: packages/ember-views/lib/views/container_view.js:16
Module: ember

A ContainerView is an Ember.View subclass that implements Ember.MutableArray allowing programatic management of its child views.

Setting Initial Child Views

The initial array of child views can be set in one of two ways. You can provide a childViews property at creation time that contains instance of Ember.View:

1
2
3

aContainer = Ember.ContainerView.create({
  childViews: [Ember.View.create(), Ember.View.create()]
});

You can also provide a list of property names whose values are instances of Ember.View:

1
2
3
4
5
6

aContainer = Ember.ContainerView.create({
  childViews: ['aView', 'bView', 'cView'],
  aView: Ember.View.create(),
  bView: Ember.View.create(),
  cView: Ember.View.create()
});

The two strategies can be combined:

1
2
3
4

aContainer = Ember.ContainerView.create({
  childViews: ['aView', Ember.View.create()],
  aView: Ember.View.create()
});

Each child view's rendering will be inserted into the container's rendered HTML in the same order as its position in the childViews property.

Adding and Removing Child Views

The container view implements Ember.MutableArray allowing programatic management of its child views.

To remove a view, pass that view into a removeObject call on the container view.

Given an empty <body> the following code

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

aContainer = Ember.ContainerView.create({
  classNames: ['the-container'],
  childViews: ['aView', 'bView'],
  aView: Ember.View.create({
    template: Ember.Handlebars.compile("A")
  }),
  bView: Ember.View.create({
    template: Ember.Handlebars.compile("B")
  })
});

aContainer.appendTo('body');

Results in the HTML

1
2
3
4

<div class="ember-view the-container">
  <div class="ember-view">A</div>
  <div class="ember-view">B</div>
</div>

Removing a view

1
2
3

aContainer.toArray();  // [aContainer.aView, aContainer.bView]
aContainer.removeObject(aContainer.get('bView'));
aContainer.toArray();  // [aContainer.aView]

Will result in the following HTML

1
2
3

<div class="ember-view the-container">
  <div class="ember-view">A</div>
</div>

Similarly, adding a child view is accomplished by adding Ember.View instances to the container view.

Given an empty <body> the following code

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

aContainer = Ember.ContainerView.create({
  classNames: ['the-container'],
  childViews: ['aView', 'bView'],
  aView: Ember.View.create({
    template: Ember.Handlebars.compile("A")
  }),
  bView: Ember.View.create({
    template: Ember.Handlebars.compile("B")
  })
});

aContainer.appendTo('body');

Results in the HTML

1
2
3
4

<div class="ember-view the-container">
  <div class="ember-view">A</div>
  <div class="ember-view">B</div>
</div>

Adding a view

1
2
3
4
5
6
7

AnotherViewClass = Ember.View.extend({
  template: Ember.Handlebars.compile("Another view")
});

aContainer.toArray();  // [aContainer.aView, aContainer.bView]
aContainer.pushObject(AnotherViewClass.create());
aContainer.toArray(); // [aContainer.aView, aContainer.bView, <AnotherViewClass instance>]

Will result in the following HTML

1
2
3
4
5

<div class="ember-view the-container">
  <div class="ember-view">A</div>
  <div class="ember-view">B</div>
  <div class="ember-view">Another view</div>
</div>

Templates and Layout

A template, templateName, defaultTemplate, layout, layoutName or defaultLayout property on a container view will not result in the template or layout being rendered. The HTML contents of a Ember.ContainerView's DOM representation will only be the rendered HTML of its child views.

Binding a View to Display

If you would like to display a single view in your ContainerView, you can set its currentView property. When the currentView property is set to a view instance, it will be added to the ContainerView. If the currentView property is later changed to a different view, the new view will replace the old view. If currentView is set to null, the last currentView will be removed.

This functionality is useful for cases where you want to bind the display of a ContainerView to a controller or state manager. For example, you can bind the currentView of a container to a controller like this:

1
2
3
4
5

App.appController = Ember.Object.create({
  view: Ember.View.create({
    templateName: 'person_template'
  })
});
 
1

{{view Ember.ContainerView currentViewBinding="App.appController.view"}}

Show: