Observer

Observer is a shared drop-in base class that implements the observer pattern. It is used in many places all over the framework and defines the common interface for all observable units.

Usage

Generally, Observer is a normal class. You can use it by itself or as an ancestor for your own classes.

var observer = new Observer();
observer.on('something', function() {....});
//....
observer.fire('something');

var MyObserver = new Class(Observer, {
// ....
});
var my_observer = new MyObserver();

Or, if you don’t have an ability to inherit the class directly, you can use its static method called create to make practically any object behave like an observer.

var Klass = new Class(AnotherKlass, {
initialize: function() {
Observer.create(this);
}
});

var klass = new Klass();
klass.on('something', function() {....});


// or even like that.
var object = {....};
Observer.create(object);

object.on('something', function() {.....});

Shortcuts

The Observer unit provides the ability to generate elegant shortcut methods to process events your observer is supposed to handle. To do so, you need to specify an instance or class level attribute EVENTS in your class. RightJS will watch the name and if found, will generate the shortcuts automatically.

var Klass = new Class(Observer, {
EVENTS: $w('start stop')
});

var klass = new Klass();
klass.onStart(function() {...});

NOTE: If your class has intersecting methods, the shortcuts generator will keep them alive and simply skipping those names.

Call By Name

The Observer class follows the general ‘call by name’ feature of RightJS. This means that instead of specifying a particular function to observe, you can specify a method name and some attributes which will be called on the event.

var Kid = new Class(Observer, {
callMommy: function(message) {
alert(message);
}
});

var kid = new Kid();

kid.on('troubles', 'callMommy', 'Mommy!');

// ...
kid.fire('troubles');

// now the 'callMommy' method of the kid instance will be called

Methods

create, createShortcuts, initialize, fire, listeners, observes, on, stopObserving

top ↑create

Observer.create(Object object[, Array events_list]) -> Object observable

Description

The static observer builder, adds observer functionality to any object.

Example

var object = {....};

Observer.create(object);

object.on('something', function() {.....});

top ↑createShortcuts

Observer.createShortcuts(Observer object, Array names) -> Object

Description

Generates the observer shortcuts on the given observable unit.

Example

var observer = new Observer();

Observer.createShortcuts(observer, ['start', 'stop']);

observer.onStart(function() {...});

top ↑initialize

initialize([Object options])

Description

The generic constructor: If you call it with a hash of option keys like 'onSomething', the observer will automatically wire it to the to the ‘something’ event.

NOTE: If you create a subclass of Observer and overload its constructor, don’t forget to call this.$super(options); inside of it to bypass the event handlers.

Example

var observer = new Observer();
var observer = new Observer({
onStart: function() {},
onFinish: 'clear'
});

top ↑fire

fire(String name[, arguments, ...]) -> Observer self

Description

Triggers an event processing.

Example

var observer = new Observer();

observer.on('something', function() {});

observer.fire('something');

// that function was called

top ↑listeners

listeners([String name]) -> Array of callbacks

Description

Returns the list of registered listeners for the given event.

Example

var observer = new Observer();
var callback = function() {};

observer.on('something', callback);

observer.listeners('something'); // -> [callback]

top ↑observes

observes(String name) -> boolean
observes(Function callback) -> boolean
observes(String name, Function callback) -> boolean

Description

Checks if the observer watches the given event or/and callback.

Example

var observer = new Observer();
var callback = function() {};

observer.on('event', callback);

observer.observes('event'); // -> true
observer.observes(callback); // -> true
observer.observes('event', callback); // -> true

observer.observes('another_event'); // -> false
observer.observes(another_calback); // -> false
observer.observes('another', callback); // -> false

top ↑on

on(String name, Function callback[, arguments]) -> Observer self
on(String name, String method_name[, arguments]) -> Observer self
on(String name, Array callbacks[, arguments]) -> Observer self
on(Object hash) -> Observer self

Description

Binds an event listener to the observer.

Example

var observer = new Observer();

observer.on('something', function() {...});

// or by name
observer.on('something', 'observer_method_name', arg1, arg2);

// or a whole list
observer.on('something', [func1, func2, func3, ...]);

// or using a hash
observer.on({
one: function() {},
two: 'something'
});

top ↑stopObserving

stopObserving(String name) -> Observer self
stopObserving(Function callback) -> Observer self
stopObserving(String name, Function callback) -> Observer self
stopObserving(Object events) -> Observer self

Description

Tells the observer to stop observing a certain callback, the whole event or some particular callback for some particular event.

Example

var observer = new Observer();
var callback = function() {};

observer.on('event', callback);

observer.stopObserving('event');

observer.observes('event'); // -> false
observer.observes(callback); // -> false