Class ArrayProxy

public

An ArrayProxy wraps any other object that implements Array and/or 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
7
8
9
import { A } from '@ember/array';
import ArrayProxy from '@ember/array/proxy';

let pets = ['dog', 'cat', 'fish'];
let ap = ArrayProxy.create({ content: 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
10
11
12
import { A } from '@ember/array';
import ArrayProxy from '@ember/array/proxy';

let pets = ['dog', 'cat', 'fish'];
let ap = ArrayProxy.create({
    content: A(pets),
    objectAtContent: function(idx) {
        return this.get('content').objectAt(idx).toUpperCase();
    }
});

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

Show:

Module: @ember/array

Available since v3.2.2

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 array 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/array

Available since v3.2.2

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.

Module: @ember/array

Available since v3.2.2

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.

Module: @ember/array

Available since v3.2.2

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
14
15
16
17
18
import EmberObject from '@ember/object';

const Bar = EmberObject.extend({
  // Configure which properties to concatenate
  concatenatedProperties: ['concatenatedProperty'],

  someNonConcatenatedProperty: ['bar'],
  concatenatedProperty: ['bar']
});

const FooBar = Bar.extend({
  someNonConcatenatedProperty: ['foo'],
  concatenatedProperty: ['foo']
});

let fooBar = FooBar.create();
fooBar.get('someNonConcatenatedProperty'); // ['foo']
fooBar.get('concatenatedProperty'); // ['bar', 'foo']

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

1
2
3
4
5
6
let fooBar = FooBar.create({
  someNonConcatenatedProperty: ['baz'],
  concatenatedProperty: ['baz']
})
fooBar.get('someNonConcatenatedProperty'); // ['baz']
fooBar.get('concatenatedProperty'); // ['bar', 'foo', 'baz']

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

1
2
3
4
let fooBar = FooBar.create({
  concatenatedProperty: 'baz'
})
view.get('concatenatedProperty'); // ['bar', 'foo', 'baz']

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

In Component the classNames, classNameBindings and attributeBindings properties are concatenated.

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/array

Available since v3.2.2

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

Module: @ember/array

Available since v3.2.2

returns
Object | undefined
The first object in the array

The first object in the array, or undefined if the array is empty.

Module: @ember/array

Available since v3.2.2

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

Module: @ember/array

Available since v3.2.2

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/array

Available since v3.2.2

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/array

Available since v3.2.2

returns
Object | undefined
The last object in the array

The last object in the array, or undefined if the array is empty.

Module: @ember/array

Available since v3.2.2

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/array

Available since v3.2.2

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
37
38
39
40
41
import EmberObject from '@ember/object';

const Bar = EmberObject.extend({
  // Configure which properties are to be merged
  mergedProperties: ['mergedProperty'],

  someNonMergedProperty: {
    nonMerged: 'superclass value of nonMerged'
  },
  mergedProperty: {
    page: { replace: false },
    limit: { replace: true }
  }
});

const FooBar = Bar.extend({
  someNonMergedProperty: {
    completelyNonMerged: 'subclass value of nonMerged'
  },
  mergedProperty: {
    limit: { replace: false }
  }
});

let fooBar = FooBar.create();

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

fooBar.get('mergedProperty');
// => {
//   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.

In Route the queryParams property is merged.

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).