Observable.js

Mixin function that adds observer functionality to an object.

Download

Development

Production ~500 bytes Minified and Gzipped

API

observable( [obj] )

Adds observer functions to the target object.

Parameters

• obj Object Target object to receive observer functions. If not passed, a new object will be created and returned.

Returns Object The target object.

Applied to an existing object

var myobj = { /*...*/ };
observable(myobj);

var myobj = new Widget;
observable(myobj);

Used to initialize an object

var myobj = observable({ /*...*/ });

Used to create a new object

var myobj = observable();

With a function constructor - each instance will have it's own events collection

function Widget() {};
observable(Widget.prototype);

var myobj = new Widget;

Observable Functions

Four functions are added to the target object: on, off, fire, and getEvents

#on( eventName, callback [, callbackN] )
#on( eventName, callbackArray )

Binds one or more callbacks to eventName

Parameters

• eventName String Event identifier.
• callback Function | Array Either one or more callback functions to bind or an array thereof.

Returns Object The target object.

myobj.on('widgetLoaded', function(){
  /*...*/
});

function init(){};
function populate(){};

myobj.on('widgetLoaded', init, populate);

myobj.on('widgetLoaded', [init, populate]);

#off( eventName, callback [, callbackN] )
#off( eventName, callbackArray )

Removes one or more callbacks bound to eventName

Parameters

• eventName String Event identifier.
• callback Function One or more callback function references to unbind or an array thereof.

Returns Object The target object.

function init(){};
function populate(){};

myobj.off('widgetLoaded', init, populate);

myobj.off('widgetLoaded', [init, populate]);

#off( eventName )

Removes all callbacks bound to eventName

Parameters

• eventName String Event identifier.

Returns Object The target object.

myobj.off('widgetLoaded');

#off()

Removes all events.

Returns Object The target object.

myobj.off();

#fire( eventName [, args] )

Invokes all callbacks for eventName

Parameters

• eventName String Event identifier.
• args Mixed Optional arguments (comma separated) passed to callbacks.

Returns Object The target object.

myobj.fire('widgetLoaded');

myobj.fire('widgetLoaded', 'some', /args/, 4, 'you');

#getEvents()

Returns a copy of the events collection.

Returns Object The events collection.

myobj.getEvents();

observable.noConflict()

var myobservable = observable.noConflict();

// Former `observable` has now been restored.

Extended Examples

var widget = observable({
  title:  'Blerg',
  render: function(){}
});

/*
 * Bind some callbacks to an event.
 */
widget.on('widget:update', function() {
  /*...*/
});

var highlightChange = function() { /*...*/ };
var save            = function() { /*...*/ };

myobj.on('widget:update', highlightChange, save);

/*
 * Fire the 'widget:update' event
 */
myobj.fire('widget:update');

/*
 * Unbind the 'save' handler for the 'widget:update' event
 */
myobj.off('widget:update', save);

Custom event

function Widget() {
  /*...*/
};
observable(Widget.prototype);

Widget.prototype.onError = function() {
  var callbacks = [].slice.call(arguments);
  this.on('widget:error', callbacks);
  return this;
};

Widget.prototype.error = function(msg) {
  this.fire('widget:error', msg);
};

var w = new Widget;

w.onError(
  function(msg) { /* Update UI */ },
  function(msg) { /* Log error */ }
);

w.error('Something went wrong.');

PubSub

A working example can be found at http://jsfiddle.net/QxWt4/3/.

var pubsub = observable();

var todosInputWidget = {
  /*...*/
  saveTodo : function(todoData) {
    pubsub.fire('todos:new', todoData);
  }
  /*...*/
};

var todosDisplayWidget = {
  init : function(){
    pubsub.on('todos:new', this.showTodo);
  },
  /*...*/
  showTodo : function(todoData) {
    // Display new todo
  }
  /*...*/
};