Class Ember.ArrayController

Uses: Ember.ControllerMixin , Ember.SortableMixin

Defined in: packages/ember-runtime/lib/controllers/array_controller.js:13

Module: ember

Ember.ArrayController provides a way for you to publish a collection of objects so that you can easily bind to the collection from a Handlebars #each helper, an Ember.CollectionView, or other controllers.

The advantage of using an ArrayController is that you only have to set up your view bindings once; to change what's displayed, simply swap out the content property on the controller.

For example, imagine you wanted to display a list of items fetched via an XHR request. Create an Ember.ArrayController and set its content property:

        
              MyApp.listController = Ember.ArrayController.create();

$.get('people.json', function(data) {
  MyApp.listController.set('content', data);
});

Then, create a view that binds to your new controller:

        
              {{#each MyApp.listController}}
  {{firstName}} {{lastName}}
{{/each}}

Although you are binding to the controller, the behavior of this controller is to pass through any methods or properties to the underlying array. This capability comes from Ember.ArrayProxy, which this class inherits from.

Sometimes you want to display computed properties within the body of an #each helper that depend on the underlying items in content, but are not present on those items. To do this, set itemController to the name of a controller (probably an ObjectController) that will wrap each individual item.

For example:

        
                {{#each post in controller}}
    <li>{{title}} ({{titleLength}} characters)</li>
  {{/each}}

        
              App.PostsController = Ember.ArrayController.extend({
  itemController: 'post'
});

App.PostController = Ember.ObjectController.extend({
  // the `title` property will be proxied to the underlying post.

  titleLength: function() {
    return this.get('title').length;
  }.property('title')
});

In some cases it is helpful to return a different itemController depending on the particular item. Subclasses can do this by overriding lookupItemController.

For example:

        
              App.MyArrayController = Ember.ArrayController.extend({
  lookupItemController: function( object ) {
    if (object.get('isSpecial')) {
      return "special"; // use App.SpecialController
    } else {
      return "regular"; // use App.RegularController
    }
  }
});

The itemController instances will have a parentController property set to either the the parentController property of the ArrayController or to the ArrayController instance itself.

Show: Inherited Protected Private Deprecated

@each

Module: ember

Inherited from Ember.Array packages/ember-runtime/lib/mixins/array.js:409

Returns a special object that can be used to observe individual properties on the array. Just get an equivalent property on this object and it will return an enumerable that maps automatically to the named key on the member objects.

If you merely want to watch for any items being added or removed to the array, use the [] property instead of @each.

Boolean

Module: ember

Inherited from Ember.Array packages/ember-runtime/lib/mixins/array.js:299

Becomes true whenever the array currently has observers watching changes on the array.

[]

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:818

returns: this

This property will trigger anytime the enumerable's content changes. You can observe this property to be notified of changes to the enumerables content.

For plain enumerables, this property is read only. Ember.Array overrides this method.

[]

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:818

returns: this

This property will trigger anytime the enumerable's content changes. You can observe this property to be notified of changes to the enumerables content.

For plain enumerables, this property is read only. Ember.Array overrides this method.

arrangedContent

Module: ember

Inherited from Ember.ArrayProxy packages/ember-runtime/lib/system/array_proxy.js:63

The array that the proxy pretends to be. In the default ArrayProxy implementation, this and content are the same. Subclasses of ArrayProxy can override this property to provide things like sorting and filtering.

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:

        
              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:

        
              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:

        
              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

Inherited from Ember.ArrayProxy packages/ember-runtime/lib/system/array_proxy.js:54

The content array. Must be an object that implements Ember.Array and/or Ember.MutableArray.

controllers

Module: ember

Inherited from Ember.ControllerMixin packages/ember-application/lib/ext/controller.js:78

Stores the instances of other controllers available from within this controller. Any controller listed by name in the needs property will be accessible by name through this property.

        
              App.CommentsController = Ember.ArrayController.extend({
  needs: ['post'],
  postTitle: function(){
    var currentPost = this.get('controllers.post'); // instance of App.PostController
    return currentPost.get('title');
  }.property('controllers.post.title')
});

firstObject Object

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:109

returns: Object; the object or undefined

Helper method returns the first object from a collection. This is usually used by bindings and other parts of the framework to extract a single object if the enumerable contains only one item.

If you override this method, you should implement it so that it will always return the same value each time it is called. If your enumerable contains only one object, this method should always return that object. If your enumerable is empty, this method should return undefined.

        
              var arr = ["a", "b", "c"];
arr.get('firstObject');  // "a"

var arr = [];
arr.get('firstObject');  // undefined

firstObject Object

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:109

returns: Object; the object or undefined

Helper method returns the first object from a collection. This is usually used by bindings and other parts of the framework to extract a single object if the enumerable contains only one item.

        
              var arr = ["a", "b", "c"];
arr.get('firstObject');  // "a"

var arr = [];
arr.get('firstObject');  // undefined

hasEnumerableObservers

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:879

Becomes true whenever the array currently has observers watching changes on the array.

hasEnumerableObservers

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:879

Becomes true whenever the array currently has observers watching changes on the 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.

itemController

Module: ember

Defined in packages/ember-runtime/lib/controllers/array_controller.js:104

The controller used to wrap items, if any.

lastObject Object

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:140

returns: Object; the last object or undefined

Helper method returns the last object from a collection. If your enumerable contains only one object, this method should always return that object. If your enumerable is empty, this method should return undefined.

        
              var arr = ["a", "b", "c"];
arr.get('lastObject');  // "c"

var arr = [];
arr.get('lastObject');  // undefined

lastObject Object

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:140

returns: Object; the last object or undefined

        
              var arr = ["a", "b", "c"];
arr.get('lastObject');  // "c"

var arr = [];
arr.get('lastObject');  // undefined

length

Module: ember

Inherited from Ember.Array packages/ember-runtime/lib/mixins/array.js:51

Your array must support the length property. Your replace methods should set this property whenever it changes.

needs

Module: ember

Inherited from Ember.ControllerMixin packages/ember-application/lib/ext/controller.js:31

An array of other controller objects available inside instances of this controller via the controllers property:

For example, when you define a controller:

        
              App.CommentsController = Ember.ArrayController.extend({
  needs: ['post']
});

The application's single instance of these other controllers are accessible by name through the controllers property:

        
              this.get('controllers.post'); // instance of App.PostController

This is only available for singleton controllers.

sortAscending

Module: ember

Inherited from Ember.SortableMixin packages/ember-runtime/lib/mixins/sortable.js:72

Specifies the arrangedContent's sort direction

sortFunction

Module: ember

Inherited from Ember.SortableMixin packages/ember-runtime/lib/mixins/sortable.js:79

The function used to compare two values. You can override this if you want to do custom comparisons. Functions must be of the type expected by Array#sort, i.e. return 0 if the two parameters are equal, return a negative value if the first parameter is smaller than the second or return a positive value otherwise:

        
              function(x,y) { // These are assumed to be integers
  if (x === y)
    return 0;
  return x < y ? -1 : 1;
}

sortProperties

Module: ember

Inherited from Ember.SortableMixin packages/ember-runtime/lib/mixins/sortable.js:62

Specifies which properties dictate the arrangedContent's sort order.

When specifying multiple properties the sorting will use properties from the sortProperties array prioritized from first to last.

target

Module: ember

Inherited from Ember.ControllerMixin packages/ember-runtime/lib/controllers/controller.js:23

The object to which actions from the view should be sent.

For example, when a Handlebars template uses the {{action}} helper, it will attempt to send the action to the view's controller's target.

By default, a controller's target is set to the router after it is instantiated by Ember.Application#initialize.