Class: SC.Observable

Key-Value-Observing (KVO) simply allows one object to observe changes to a property on another object. It is one of the fundamental ways that models, controllers and views communicate with each other in a SproutCore application. Any object that has this module applied to it can be used in KVO-operations.

This module is applied automatically to all objects that inherit from SC.Object, which includes most objects bundled with the SproutCore framework. You will not generally apply this module to classes yourself, but you will use the features provided by this module frequently, so it is important to understand how to use it.

Enabling Key Value Observing

With KVO, you can write functions that will be called automatically whenever a property on a particular object changes. You can use this feature to reduce the amount of "glue code" that you often write to tie the various parts of your application together.

To use KVO, just use the KVO-aware methods get() and set() to access properties instead of accessing properties directly. Instead of writing:

var aName = contact.firstName;
  contact.firstName = 'Charles';

use:

var aName = contact.get('firstName');
  contact.set('firstName', 'Charles');

get() and set() work just like the normal "dot operators" provided by JavaScript but they provide you with much more power, including not only observing but computed properties as well.

Observing Property Changes

You typically observe property changes simply by adding the observes() call to the end of your method declarations in classes that you write. For example:

SC.Object.create({
    valueObserver: function () {
      // Executes whenever the "Value" property changes
    }.observes('value')
  });

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

To add an observer for a property, just call:

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

This will call the 'targetAction' method on the targetObject to be called whenever the value of the propertyKey changes.

Observer Parameters

An observer function typically does not need to accept any parameters, however you can accept certain arguments when writing generic observers. An observer function can have the following arguments:

propertyObserver(target, key, value, revision);

Implementing Manual Change Notifications

Sometimes you may want to control the rate at which notifications for a property are delivered, for example by checking first to make sure that the value has changed.

To do this, you need to implement a computed property for the property you want to change and override automaticallyNotifiesObserversFor().

The example below will only notify if the "balance" property value actually changes:

automaticallyNotifiesObserversFor: function (key) {
    return (key === 'balance') ? NO : sc_super();
  },

  balance: function (key, value) {
    var balance = this._balance;
    if ((value !== undefined) && (balance !== value)) {
      this.propertyWillChange(key);
      balance = this._balance = value;
      this.propertyDidChange(key);
    }
    return balance;
  }

Implementation Details

Internally, SproutCore keeps track of observable information by adding a number of properties to the object adopting the observable. All of these properties begin with "_kvo_" to separate them from the rest of your object.

Defined in: observable.js

Since:
SproutCore 1.0

Field Summary