Observable

Overview

This mixin provides properties and property observing functionality, core features of the Ember object model.

Properties and observers allow one object to observe changes to a property on another object. This is one of the fundamental ways that models, controllers and views communicate with each other in an Ember application.

Any object that has this mixin applied can be used in observer operations. That includes Ember.Object and most objects you will interact with as you write your Ember application.

Note that you will not generally apply this mixin to classes yourself, but you will use the features provided by this module frequently, so it is important to understand how to use it.

Using get() and set()

Because of Ember's support for bindings and observers, you will always access properties using the get method, and set properties using the set method. This allows the observing objects to be notified and computed properties to be handled properly.

More documentation about get and set are below.

Observing Property Changes

You typically observe property changes simply by using the Ember.observer function in classes that you write.

For example:

Ember.Object.extend({
  valueObserver: Ember.observer('value', function(sender, key, value, rev) {
    // Executes whenever the "value" property changes
    // See the addObserver method for more information about the callback arguments
  })
});

Although this is the most common way to add an observer, this capability is actually built into the Ember.Object class on top of two methods defined in this mixin: addObserver and removeObserver. You can use these two methods to add and remove observers yourself if you need to do so at runtime.

To add an observer for a property, call:

object.addObserver('propertyKey', targetObject, targetAction)

This will call the targetAction method on the targetObject whenever the value of the propertyKey changes.

Note that if propertyKey is a computed property, the observer will be called when any of the property dependencies are changed, even if the resulting value of the computed property is unchanged. This is necessary because computed properties are not computed until get is called.