pulp javascript Event System for Objects

Below are examples and use cases for the pulp event system for Objects. The pulp event methods are available for all Objects created with pulp.cls.create().

The pulp event system, while inspired by the DOM event handling mechanism, is distinct from and independent of DOM events. Indeed, this system allows the developer to respond to events that aren't necessarily initiated by direct user input like key presses or mouse-button clicks. For example, pulp.ajax instances fire events such as success and timeout.

  1. Introduction
  2. On and After
  3. Bubbling
  4. Defining event options
  5. Subscription events
  6. Debugging

top ^1. On and After

pulp uses an advanced event system that allows firing callbacks before and after an event.

  • When an object fires an event, it first calls on subscribers, then a default action, then after subscribers.
  • The fire method accepts three parameters: The event type, the default action function, and data to pass to subscribers in the event. (See Examples 1.1 and 1.2 at right.) The default action function and data arguments are optional.
  • To subscribe to an event, you can call on() or after(). Callbacks will receive one parameter, an event object, with properties and methods similar to DOM Event objects and data passed from the fire method. (See Example 1.2.)
  • Event objects have a type property telling of the name of the fired event and a target property telling of the firing class. Event objects also have a timing property with a value of "on", "defaultAction" or "after".
  • See the Bubbling Section for information on event object methods.

Example 1.1: Unique Event Firing Pattern

  1. classInstance.fire(eventName, defaultAction, relatedData);

Example 1.2: Firing an Event

  1. var myClass = pulp.cls.create({
  2.   finish: function(arg) {
  3.     this.fire('finish', function(event) {
  4.       // finish up something
  5.     }, {relatedData1: 'hello', relatedData2: 'world', arg: arg});
  6.   }
  7. });

Example 1.3: Subscribing to an Event

  1. var myClass = pulp.cls.create();
  2. var myInstance = new myClass();
  3. myInstance.on('finish', function(event) {
  4.   // do something before the finish action
  5.   event.type == 'finish';
  6.   event.target == this;
  7.   event.timing == 'on';
  8. });
  9. myInstance.after('finish', function(event) {
  10.   // do something else after the finish action
  11.   event.type == 'finish';
  12.   event.target == this;
  13.   event.timing == 'after';	
  14. });

Example 2.4: Subscribing to an Event through options object

  1. var myClass = pulp.cls.create({
  2.   initialize: function(options) {
  3.  
  4.   }		
  5. });
  6. var myInstance = new myClass();
  7. myInstance.on('finish', function(event) {
  8.   // do something before the finish action
  9.   event.type == 'finish';
  10.   event.target == this;
  11.   event.timing == 'on';
  12. });
  13. myInstance.after('finish', function(event) {
  14.   // do something else after the finish action
  15.   event.type == 'finish';
  16.   event.target == this;
  17.   event.timing == 'after';	
  18. });

top ^2. Bubbling

What is the meaning of propagation, bubbling and default actions?

Propagation refers to the process of executing subscriber callbacks in FIFO order.

An event that bubbles is one where a subscriber callback has the power to cancel propagation and prevent subsequent subscriber callbacks from executing.

A default action is a method that is executed after subscribers are executed. For example, in a DOM environment, on a >form< element's "submit" event, the form will submit if not prevented.

Events that are not preventable will always allow default actions to execute.

What properties and methods are available on the event object?

When you subscribe to an event (using the on method), the callback will receive one parameter: an event object. The event object has properties (see the On and After Section), but also has several useful methods:

  • event.preventDefault() prevents the default action but allows other subscribers to still be notified. (See Example 2.1 at right.)
  • event.stopPropagation() cancels other subscribers but allows the default action to execute. (See Example 2.2.)
  • event.halt() prevents the default action and cancels other subscribers. (See Example 2.3.)
  • event.stopImmediatePropagation() cancels other subscribers of the callback's subscription type. In other words, when an on subscriber calls event.stopImmediatePropagation(), no other on subscribers will be notified, but after subscribers will still be executed. Similarly, when an after subscriber calls event.stopImmediatePropagation(), no other after subscribers will be notified. (See Example 2.4.)
  • event.getDefinedEvent() returns a reference to the event definition
  • event.isPrevented() returns true if preventDefault has been called.
  • event.isStopped() returns true if stopPropagation has been called.
  • event.isSuspended() returns true if stopImmediatePropagation has been called.
  • event.type is the type of event (e.g. "finish", "do:something").
  • event.scope is the scope in which the callbacks are executing.
  • event.target is the publisher or other object specifically defined in the event options.
  • event.timing is "debug", "on", "defaultAction" or "after".

Event Data

Events are designed to carry data set by the event publisher. To avoid namespace conflicts, never pass data with any of the aforementioned properties:

  • preventDefault
  • stopPropagation
  • halt
  • stopImmediatePropagation
  • getDefinedEvent
  • isPrevented
  • isStopped
  • isSuspended
  • type
  • scope
  • target
  • timing

Example 2.1: event.preventDefault()

Timing Effect Method Call
on fired event.preventDefault()
on fired
defaultAction not called
after not called
after not called

Example 2.2: event.stopPropagation()

Timing Effect Method Call
on fired event.stopPropagation()
on not called
defaultAction fired
after not called
after not called

Example 2.3: event.halt()

Timing Effect Method Call
on fired event.halt()
on not called
defaultAction not called
after not called
after not called

Example 2.4a: event.stopImmediatePropagation()

Timing Effect Method Call
on fired event.stopImmediatePropagation()
on not called
defaultAction fired
after fired
after fired

Example 2.4b: event.stopImmediatePropagation()

Timing Effect Method Call
on fired
on fired
defaultAction fired
after fired event.stopImmediatePropagation()
after not called

Example 2.4b: event.stopImmediatePropagation()

Timing Effect Method Call
on fired
on fired
defaultAction fired event.stopImmediatePropagation()
after fired
after fired

top ^3. Defining Event Options

Defining Options

As mentioned in Section 2, events can be defined with certain options. See below and Example 3.1 to the right.

  • Setting target will cause event.target to be something other than the calling object.
  • If bubbles is false, observers cannot stop firing of subsequent handlers (through calling stopPropagation or stopImmediatePropagation). Default is true.
  • If preventable is false, observers cannot stop firing of default action (through calling preventDefault). Default is true.
  • If scope is set, subscribers will be called in this scope instead of the calling object's scope.
  • If fireOnce is true, the event will fire only once; callbacks subscribed after firing will be called immediately. Default is false.

Example 3.1: Defining an Event

  1. var myClass = pulp.cls.create({
  2.   initialize: function(arg) {
  3.     this.defineEvent('finish', {
  4.       // these are the default options
  5.       target: this,      // the object that fired the event
  6.       bubbles: true,     // propagation can be stopped
  7.       preventable: true, // default action can be prevented
  8.       scope: this,       // scope of firing function
  9.       fireOnce: false    // if true, fire only once
  10.     });
  11.   }
  12. });

top ^4. Subscription Events

Objects can receive notification every time a new callback is subscribe. The object being subscribed will fire "event:subscribe" event every time an object subscribes.

Callbacks subscribed to the "event:subscribe" event will receive an event object with following properties:

  • eventType: the name of the event (e.g. finish, teardown)
  • eventCallback: references the callback being subscribed
  • eventTiming: "debug", "on", "defaultAction" or "after"

Example 4.1: Monitoring Subscribers

  1. var myClass = pulp.cls.create({
  2.   initialize: function() {
  3.     this.on('event:subscribe', function(event) {
  4.       alert('I see you subscribing to ' + event.type);
  5.     });
  6.   }
  7. });
  8. var myInstance = new myClass();
  9. myInstance.on('finish', myCallback);
  10. // alerts "I see you subscribing to finish"

top ^5. Debug

You can attach a callback using the eventDebug() function that will be triggered every time the object fires any event.

You can only attach one function as the debug listener.

The methods can also be added to other objects or classes by copying all the properties within pulp.cls.event.mixin