Class ArrayProxy

public
Extends: EmberObject
Uses: MutableArray
Defined in: packages/@ember/array/proxy.ts:59
Module: @ember/array/proxy

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'

When overriding this class, it is important to place the call to _super after setting content so the internal observers have a chance to fire properly:

1
2
3
4
5
6
7
8
9

import { A } from '@ember/array';
import ArrayProxy from '@ember/array/proxy';

export default ArrayProxy.extend({
  init() {
    this.set('content', A(['dog', 'cat', 'fish']));
    this._super(...arguments);
  }
});

Show:

[] public

Module: @ember/array/proxy

Inherited from EmberArray packages/@ember/array/index.ts:377

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.

1
2
3
4
5
6

let peopleToMoon = ['Armstrong', 'Aldrin'];

peopleToMoon.get('[]'); // ['Armstrong', 'Aldrin']

peopleToMoon.set('[]', ['Collins']); // ['Collins']
peopleToMoon.get('[]'); // ['Collins']

arrangedContent public

Module: @ember/array/proxy

Defined in packages/@ember/array/proxy.ts:401

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 public

Module: @ember/array/proxy

Inherited from CoreObject packages/@ember/object/core.ts:352

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 Component from @ember/component.

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

content public

Module: @ember/array/proxy

Defined in packages/@ember/array/proxy.ts:172

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

firstObject Object | undefined public

Module: @ember/array/proxy

Inherited from EmberArray packages/@ember/array/index.ts:405

returns
Object | undefined
The first object in the array

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

1
2
3
4
5
6
7
8
9
10
11

let vowels = ['a', 'e', 'i', 'o', 'u'];
vowels.firstObject; // 'a'

vowels.shiftObject();
vowels.firstObject; // 'e'

vowels.reverseObjects();
vowels.firstObject; // 'u'

vowels.clear();
vowels.firstObject; // undefined

isDestroyed public

Module: @ember/array/proxy

Inherited from CoreObject packages/@ember/object/core.ts:501

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 public

Module: @ember/array/proxy

Inherited from CoreObject packages/@ember/object/core.ts:519

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.

lastObject Object | undefined public

Module: @ember/array/proxy

Inherited from EmberArray packages/@ember/array/index.ts:430

returns
Object | undefined
The last object in the array

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

length public

Module: @ember/array/proxy

Inherited from EmberArray packages/@ember/array/index.ts:323

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.

mergedProperties public

Module: @ember/array/proxy

Inherited from CoreObject packages/@ember/object/core.ts:426

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