Object.Event & 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.

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
	

Utility Methods

Object.Event Class Methods

Object.Event has only one method, Object.Event.extend(), which gives the object, and it's prototype Object.Event methods.

Object.Event Inherited Methods

The methods in this table become part of the object that you extend. By design notify() is to be implemented inside the class or object. You should not trigger notify() calls outside the class definition.

Element.observeOnce()

This works just like Element.observe(), but the observe will only be called once. It will then unregister itself via Element.stopObserving().

		$('element').observeOnce('click',function(){
			//after element is clicked once, this observer will be unregistered
		});
	

mouseenter & mouseleave Events

Native implementation is used in IE. Control.Window (hoverbox/tooltips) and Control.Selection (selection containment) are the only classes that depend on these events. The Prototype core team has stated they don't think these should be in the core. It is my recommendation that the Prototype core adopt these methods until the browser vendors decide to implement them. They can only be used with the Event/Element classes.

		$('element').observe('mouseenter',function(){});
		$('element').observe('mouseleave',function(){});
	

mouse:wheel Event

Control.ScrollBar is the only class that depends on this event.

		$('element').observe('mouse:wheel',function(event){
			event.memo.delta; //contains the wheel delta
		});