Skip to content

JavaScript class for creating custom objects with events support

License

Notifications You must be signed in to change notification settings

burdiuz/js-event-dispatcher

Repository files navigation

EventDispatcher

Build Status Coverage Status

Just another EventDispatcher/EventTarget implementation.

Installation

Easy to install with npm package manager

npm install --save @actualwave/event-dispatcher

with yarn package manager

yarn add @actualwave/event-dispatcher

Usage

Note: EventDispatcher distribution package contains dist/ folder with package wrapped into UMD wrapper, so it can be used with any AMD module loader, nodejs require() or without any.

To start using EventDispatcher, just instantiate it on its own

class MyClass {
  constructor() {
    this._dispatcher = new EventDispatcher();
  }
  addListener(handler) {
    this._dispatcher.addEventListener('didSomething', handler);
  }
  doSomething() {
	  this._dispatcher.dispatchEvent('didSomething');
  }
}

extend it with your class

class MyClass extends EventDispatcher {
  doSomething() {
    this.dispatchEvent('didSomething');
  }
}

After instantiating MyClass, every call of doSomething() will fire event didSomething and every listener attached to this event will be called with event object as argument.

var myObj = new MyClass();
myObj.addEventListener('didSomething', function(event) {
  console.log('My Listener', event.type);
});
myObj.doSomething();

When adding listeners they will be executed in same order as they where added. To change order you can use optional priority argument to addEventListener() method.

myObj.addEventListener('didSomething', function(event) {
  console.log('Prioritized Listener', event.type);
}, 1);
myObj.doSomething();

By default priority is set to 0, and you can specify higher priority >0 or lower <0, only integer values are allowed.

To fire event you should use dispatchEvent() method, it can be used in three ways: You can pass only event type string. In this case event object will be created by EventDispatcher

var dispatcher = new EventDispatcher();
dispatcher.dispatchEvent('eventType');

With event type you can specify any data, as second argument, that should be passed with event

dispatcher.addEventListener('eventType', function(event) {
  console.log('My Listener', event.type, event.data);
});
dispatcher.dispatchEvent('eventType', {myData: 'something'});

Also you can pass event object, it must contain type:String property

dispatcher.dispatchEvent({type: 'eventType', data: 'data is optional'});

If you want full control of events that fire from your EventDispatcher, you can specify event pre-processor function that will be called for each event before it fired. This function should return same or new event object.

function eventPreprocessor(event){
  event.data = event.data || {};
  return event;
}
var dispatcher = new EventDispatcher(eventPreprocessor);
dispatcher.dispatchEvent('eventType');

eventPreprocessor() function will be called with event object and returned object will be used.

Example available in project's example folder. To try example first run server

npm run server

And then go to http://localhost:8081/index.html

API

EventDispatcher

  • addEventListener(eventType:String, listener:Function, priority:int=0):void - Add listener to event type. Additionally priority can be set, higher values allow call listeners before others, lower -- after. Same listener can be added to event type using different priorities. By default, 0.
  • hasEventListener(eventType:String):void - Check if listener was added to event type.
  • removeEventListener(eventType:String, listener:Function):void - Remove event listener from event of specified type.
  • removeAllEventListeners(eventType:String):void - Remove all listeners from event of specified type.
  • dispatchEvent(eventType:String, data:Object=null):void - Dispatch event of eventType and pass data. Will create object of built-in class Event and pass it as first argument to listeners.
  • dispatchEvent(event:Object):void - Event object that should be fired, can be any object. Only requirement -- it must contain field type with event type.

EventDispatcher constructor accepts optional argument eventPreprocessor(event:Object):Object, function that receive event object as argument and should return same or new/changed event object that will be passed to event listeners.

Event

Built-in class to represent dispatched event. Objects of Event class are used when dispatchEvent() method is called with eventType.

  • type:String - Event type.
  • data:Object - Data object passed to EventDispatcher.dispatchEvent() method.
  • preventDefault():void - Will change "prevented" flag from FALSE to TRUE, it can be requested via isDefaultPrevented() method.
  • isDefaultPrevented():Boolean - Will return TRUE if preventDefault() was called.

Any event(instance of built-in Event class or any other object passed as event) gains additional methods when its being dispatched. After cycle finished, these methods will be removed from event object.

  • stopPropagation():void - Stop event propagation after processing all listeners of same priority.
  • stopImmediatePropagation():void - Stop event propagation on current listener.

Written with StackEdit.