Ember.ComputedProperty Class packages/ember-metal/lib/computed.js:37


A computed property transforms an object's function into a property.

By default the function backing the computed property will only be called once and the result will be cached. You can specify various properties that your computed property depends on. This will force the cached result to be recomputed if the dependencies are modified.

In the following example we declare a computed property (by calling .property() on the fullName function) and setup the property dependencies (depending on firstName and lastName). The fullName function will be called once (regardless of how many times it is accessed) as long as its dependencies have not changed. Once firstName or lastName are updated any future calls (or anything bound) to fullName will incorporate the new values.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var Person = Ember.Object.extend({
  // these will be supplied by `create`
  firstName: null,
  lastName: null,

  fullName: function() {
    var firstName = this.get('firstName');
    var lastName = this.get('lastName');

   return firstName + ' ' + lastName;
  }.property('firstName', 'lastName')
});

var tom = Person.create({
  firstName: 'Tom',
  lastName: 'Dale'
});

tom.get('fullName') // 'Tom Dale'

You can also define what Ember should do when setting a computed property. If you try to set a computed property, it will be invoked with the key and value you want to set it to. You can also accept the previous value as the third parameter.

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
var Person = Ember.Object.extend({
  // these will be supplied by `create`
  firstName: null,
  lastName: null,

  fullName: function(key, value, oldValue) {
    // getter
    if (arguments.length === 1) {
      var firstName = this.get('firstName');
      var lastName = this.get('lastName');

      return firstName + ' ' + lastName;

    // setter
    } else {
      var name = value.split(' ');

      this.set('firstName', name[0]);
      this.set('lastName', name[1]);

      return value;
    }
  }.property('firstName', 'lastName')
});

var person = Person.create();

person.set('fullName', 'Peter Wagenet');
person.get('firstName'); // 'Peter'
person.get('lastName');  // 'Wagenet'
Show:

Methods

Show:

cacheable

(aFlag) Ember.ComputedProperty

Properties are cacheable by default. Computed property will automatically cache the return value of your function until one of the dependent keys changes.

Call volatile() to set it into non-cached mode. When in this mode the computed property will not automatically cache the return value.

However, if a property is properly observable, there is no reason to disable caching.

Parameters:

aFlag Boolean
optional set to `false` to disable caching

Returns:

Ember.ComputedProperty
this

get

(keyName) Object

Access the value of the function backing the computed property. If this property has already been cached, return the cached result. Otherwise, call the function passing the property name as an argument.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var Person = Ember.Object.extend({
  fullName: function(keyName) {
    // the keyName parameter is 'fullName' in this case.
    return this.get('firstName') + ' ' + this.get('lastName');
  }.property('firstName', 'lastName')
});


var tom = Person.create({
  firstName: 'Tom',
  lastName: 'Dale'
});

tom.get('fullName') // 'Tom Dale'

Parameters:

keyName String
The key being accessed.

Returns:

Object
The return value of the function backing the CP.

meta

(meta)

In some cases, you may want to annotate computed properties with additional metadata about how they function or what values they operate on. For example, computed property functions may close over variables that are then no longer available for introspection.

You can pass a hash of these values to a computed property like this:

1
2
3
4
person: function() {
  var personId = this.get('personId');
  return App.Person.create({ id: personId });
}.property().meta({ type: App.Person })

The hash that you pass to the meta() function will be saved on the computed property descriptor under the _meta key. Ember runtime exposes a public API for retrieving these values from classes, via the metaForProperty() function.

Parameters:

meta Hash

property

(path) Ember.ComputedProperty

Sets the dependent keys on this computed property. Pass any number of arguments containing key paths that this computed property depends on.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var President = Ember.Object.extend({
  fullName: computed(function() {
    return this.get('firstName') + ' ' + this.get('lastName');

    // Tell Ember that this computed property depends on firstName
    // and lastName
  }).property('firstName', 'lastName')
});

var president = President.create({
  firstName: 'Barack',
  lastName: 'Obama'
});

president.get('fullName'); // 'Barack Obama'

Parameters:

path String
zero or more property paths

Returns:

Ember.ComputedProperty
this

readOnly

Ember.ComputedProperty

Call on a computed property to set it into read-only mode. When in this mode the computed property will throw an error when set.

1
2
3
4
5
6
7
8
9
var Person = Ember.Object.extend({
  guid: function() {
    return 'guid-guid-guid';
  }.property().readOnly()
});

var person = Person.create();

person.set('guid', 'new-guid'); // will throw an exception

Returns:

Ember.ComputedProperty
this

set

(keyName, newValue, oldValue) Object

Set the value of a computed property. If the function that backs your computed property does not accept arguments then the default action for setting would be to define the property on the current object, and set the value of the property to the value being set.

Generally speaking if you intend for your computed property to be set your backing function should accept either two or three arguments.

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
var Person = Ember.Object.extend({
  // these will be supplied by `create`
  firstName: null,
  lastName: null,

  fullName: function(key, value, oldValue) {
    // getter
    if (arguments.length === 1) {
      var firstName = this.get('firstName');
      var lastName = this.get('lastName');

      return firstName + ' ' + lastName;

    // setter
    } else {
      var name = value.split(' ');

      this.set('firstName', name[0]);
      this.set('lastName', name[1]);

      return value;
    }
  }.property('firstName', 'lastName')
});

var person = Person.create();

person.set('fullName', 'Peter Wagenet');
person.get('firstName'); // 'Peter'
person.get('lastName');  // 'Wagenet'

Parameters:

keyName String
The key being accessed.
newValue Object
The new value being assigned.
oldValue String
The old value being replaced.

Returns:

Object
The return value of the function backing the CP.

volatile

Ember.ComputedProperty

Call on a computed property to set it into non-cached mode. When in this mode the computed property will not automatically cache the return value.

1
2
3
4
5
var outsideService = Ember.Object.extend({
  value: function() {
    return OutsideService.getValue();
  }.property().volatile()
}).create();

Returns:

Ember.ComputedProperty
this