observable extension

This is a light abstraction around the ES6 "Harmony" specification for Object.observe().

An instance of a sudo.Observable class (or any object implementing the sudo.ext.observable) exposes these methods:

###observe(fn)

Call the observe method on an object mixing-in the observable extension, passing in a function that you want to be called with the 'changeRecord'.

var model = $.extend(new sudo.Model(), sudo.extensions.observable);

var cb = function(changeRecord) { // do stuff with changeRecord };

// cb will now become a target for notifications	 	
model.observe(cb);

model.set('foo', 'bar');	 	
// cb would then have been called with	 	
// = > {name: 'foo', object: Object, type: 'new'};

Note that the object: Object in this case would be the actual data hash of the model, so to access the value located at name you simply need to use object[name] in your callback. If we were to set a different value to the key:

model.set('foo', 'baz');

// the changeRecord type reflects an update, and includes the old value	 	
=> {name: 'foo', object: Object, type: 'updated', oldValue: 'bar'}

Use of unset will result in a notification:

model.unset('foo');

// the changeRecord type reflects a delete	 	
=> {name: 'foo', object: Object, type: 'deleted'}

Multiple keys set via sets will cause the notifier to be called multiple times. Remember that the object returned will reflect the state of all of the operations of sets. This is true because the sudo implementation does not call the callbacks until after sets has finished. If you want to change the default behavior (calling callbacks multiple times for a sets) override the deliverChangeNotifications method on the observable object (see the observable.spec.js spec for an example).

###observes(ary)

Pass in an array of functions to register as callback targets for 'changeRecords'. Returns the Array passed in.

Use With Paths

This works the same as keys, only that the name property of the change record will be the path that was set to cause the callback to be fired.

model.setPath('Robert.shrubber', true)	 	
// cb would then have been called with	 	
= > {name: 'Robert.shrubber', object: Object, type: 'new'});

The value set at the path can the be fetched via getPath (by passing the path, and the object):

this.getPath(object.name, object)

###unobserve(fn)

Call unobserve with a function to stop that function from recieving change notifications.

model.unobserve(observer);

To make it easier to pass the correct function to unobserve, observe returns the funtion passed to it. This is particularly useful in the common use case scenario that a bound, named function is being passed:

// assuming you are in the scope of some object with a method named someFunction	 	
var observer = model.observe(this.someFunction.bind(this));

###unobserves(ary)

Pass in an array of functions to unregister as callback targets for 'changeRecords'. Returns this.

###Change Delegate

The Change Delegate class is designed to remove some boilerplate code when using the observable extension.