Object.Event & Extensions

Event based programming model and Prototype Event/Element extensions.

livepipe.js source
Tutorial
API
Extensions

Object.Event is the core of LivePipe UI and is used by all classes. It allows you to create / notify() and observe() custom events on any object, which mimic the behavior of events in Element / Event. In addition to instance (object) observers, it introduces the concept of class observers, which observe all instances of a class.

In Action

You’ve clicked the ratings controls below 0 times. These ratings have a total value of 0.

	I don’t have an instance observer.
	Neither do I!
	But I have an instance observer, and I haven’t been rated yet.

var rating_one = new Control.Rating('rating_one',{multiple:true});  var rating_two = new Control.Rating('rating_two',{multiple:true});  var rating_three = new Control.Rating('rating_three',{multiple:true});    rating_three.observe('afterChange',function(new_value){      $('rating_three_result').update('have been rated ' + new_value);  });    var number_of_times_rated = 0;  var total_container = $('rating_total');  var times_container = $('rating_times');    Control.Rating.observe('afterChange',function(rating_instance,new_value){      ++number_of_times_rated;      times_container.update(number_of_times_rated + ' time' + (number_of_times_rated == 1 ? '' : 's'));      total_container.update(parseInt(total_container.innerHTML) + new_value);  });

The function registered via Control.Rating.observe() will be called whenever any rating’s value changes. Note that the instance that triggered the event is always prepended to the argument list when registering a class observer. The function registered via rating_three.observe() will only be called when the third rating changes.

When afterChange is fired…

The diagram below shows what happened when a Control.Rating instance fires an afterChange event. Note that the function registered by observe() is called, not observe() itself.

Triggering Events & $break

All events are triggered via the notify() method. Any arguments passed into this function will be passed to all observers. This method will return an array of the collected return values from all observers. notify() is meant to be called inside of the class or object being observed (the instance is going to notify() observers when there is an event, you are not going to notify() the object of an event). To further clarify the matter, if JavaScript had private methods, notify() would be one.

When observing an event on a DOM object, Event.stop() is used to stop event execution / bubbling. Since there is no event object to stop, the $break variable can be thrown inside an event handler to accomplish the same thing. If any event handler throws $break, the notify() method will return false instead of an array of collected return values. Control.Modal has beforeOpen and beforeClose events that will look for this. If $break is thrown, the action will be prevented (in this case, open()).

Click to Open Modal Allow modal window to open?

new Control.Modal('modal_test',{      className: 'modal',      beforeOpen: function(){          if(!$('modal_checkbox').checked)              throw $break;      }  });

Observers in Object.options

If an object has an options property (every LivePipe UI object does) that contains a callable function with the same name as an event triggered with notify(), it will be treated just like an instance observer. So the falling code is equivalent.

var rating_one = new Control.Rating('rating_one',{      afterChange: function(new_value){}    });    var rating_two = new Control.Rating('rating_two');  rating_two.observe('afterChange',function(new_value){});

Utility Methods

$proc() and $value() are utility methods which are included in the livepipe.js file. They are used by various control scripts so that end users can specify many options as either scalar values (strings, numbers, booleans) or functions. If $proc() is given a function, it returns that function otherwise it returns a function that returns that value. If $value() is given a function, it calls that function returning the response, otherwise it acts as an Identity Function (or Prototype.K()).

$proc(5) == function(){return 5;}  $proc(function(){return 5;}) == function(){return 5;}    $value(5) == 5  $value(function(){return 5;}) == 5    $value($proc(5)) == 5