Class Ember.ArrayProxy

public

An ArrayProxy wraps any other object that implements Ember.Array and/or Ember.MutableArray, forwarding all requests. This makes it very useful for a number of binding use cases or other cases where being able to swap out the underlying array is useful.

A simple example of usage:

1
2
3
4
5
6
var pets = ['dog', 'cat', 'fish'];
var ap = Ember.ArrayProxy.create({ content: Ember.A(pets) });

ap.get('firstObject');                        // 'dog'
ap.set('content', ['amoeba', 'paramecium']);
ap.get('firstObject');                        // 'amoeba'

This class can also be useful as a layer to transform the contents of an array, as they are accessed. This can be done by overriding objectAtContent:

1
2
3
4
5
6
7
8
9
var pets = ['dog', 'cat', 'fish'];
var ap = Ember.ArrayProxy.create({
    content: Ember.A(pets),
    objectAtContent: function(idx) {
        return this.get('content').objectAt(idx).toUpperCase();
    }
});

ap.get('firstObject'); // . 'DOG'

Show:

Module: ember

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.

@each should only be used in a non-terminal context. Example:

1
2
3
myMethod: computed('posts.@each.author', function(){
  ...
});

If you merely want to watch for the array being changed, like an object being replaced, added or removed, use [] instead of @each.

1
2
3
myMethod: computed('posts.[]', function(){
  ...
});
Module: ember
returns
this

This is the handler for the special array content property. If you get this property, it will return this. If you set this property to a new array, it will replace the current content.

This property overrides the default property defined in Ember.Enumerable.

Module: ember

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 Ember to 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. Since it changes expectations about behavior of properties, you should properly document its usage in each individual concatenated property (to not mislead your users to think they can override the property in a subclass).

Module: ember
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.

1
2
3
4
5
var arr = ['a', 'b', 'c'];
arr.get('firstObject');  // 'a'

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

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

Module: ember

Destroyed object property flag.

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

Module: ember

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.

Module: ember
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.

1
2
3
4
5
var arr = ['a', 'b', 'c'];
arr.get('lastObject');  // 'c'

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

Required. You must implement this method to apply this mixin.

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

Module: ember

Defines the properties that will be merged 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 merging the superclass property value with the subclass property's value. An example of this in use within Ember is the queryParams property of routes.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
App.BarRoute = Ember.Route.extend({
  someNonMergedProperty: {
    nonMerged: 'superclass value of nonMerged'
  },
  queryParams: {
    page: {replace: false},
    limit: {replace: true}
  }
});

App.FooBarRoute = App.BarRoute.extend({
  someNonMergedProperty: {
    completelyNonMerged: 'subclass value of nonMerged'
  },
  queryParams: {
    limit: {replace: false}
  }
});

var fooBarRoute = App.FooBarRoute.create();

fooBarRoute.get('someNonMergedProperty');
// => { completelyNonMerged: 'subclass value of nonMerged' }
//
// Note the entire object, including the nonMerged property of
// the superclass object, has been replaced

fooBarRoute.get('queryParams');
// => {
//   page: {replace: false},
//   limit: {replace: false}
// }
//
// Note the page remains from the superclass, and the
// `limit` property's value of `false` has been merged from
// the subclass.

This behavior is not available during object create calls. It is only available at extend time.

This feature is available for you to use throughout the Ember object model, although typical app developers are likely to use it infrequently. Since it changes expectations about behavior of properties, you should properly document its usage in each individual merged property (to not mislead your users to think they can override the property in a subclass).