Skip to content

Latest commit

 

History

History
367 lines (318 loc) · 12.6 KB

reference.md

File metadata and controls

367 lines (318 loc) · 12.6 KB
Raw

Mixins

Events

Events mixin. Just mix it into your prototypes

Functions

setInterop(type, interop) ⇒ void

Registers interop for given type. There is a default interop which tries to use on and off It will be applied if there is no any suitable registered interop

Events

Events mixin. Just mix it into your prototypes

Kind: global mixin

Events.on(event, [callback], [context]) ⇒ *

Registers event(s) with given callback

Kind: static method of Events
Returns: * - this, chainable

Param Type Description
event string | object event name(s) or events hash
[callback] function | object optional if event is events hash
[context] object event callback context

Example (single event with default context)

let callback = function() { }
instance.on('some:event', callback);

Example (single event with provided context)

let callback = function() { }
let context = { some: 'context'};
instance.on('some:event', callback, context)
// `this` will be equal to `context`

Example (multiple events with single callback)

let callback = function() { }
instance.on('event1 event2', callback);
// will registers both `event1` and `event2` with `callback` and instance as context

Example (multiple events by hash with default context)

instance.on({
  event1: callback1,
  event2: callback2
});
// will registers `event1` with callback1 and `event2` with callback2 and instance as context for both

Events.once(event, [callback], [context]) ⇒ *

Registers event(s) with given callback which will be invoked only once

Kind: static method of Events
Returns: * - this, chainable
See: Events.on

Param Type Description
event string | object event(s) name or events hash
[callback] function | object optional if event is events hash
[context] object event callback context

Events.listenTo(emitter, event, [callback], [context]) ⇒ *

Registers event(s) callback(s) which should happens on given instance. Just like on but first argument is an object which will trigger the event.

Kind: static method of Events
Returns: * - this, chainable

Param Type Description
emitter object instance you want to listen
event string | object event(s) name or events hash
[callback] function | object callback if events is a string or optional context if events is a hash
[context] object default event callback context if event is a string

Example

listener.listenTo(emitter, 'event', callback);
listener.listenTo(emitter, 'event1 event2', callback, context);
listener.listenTo(emitter, { event1: callback1, event2: callback2 });
listener.listenTo(emitter, { event1: callback2, event2: context2 }, context);

Events.listenToOnce(emitter, event, [callback], [context]) ⇒ *

Registers event(s) callback(s) which should happens on given instance only once. Just like once but first argument is an object which will trigger the event.

Kind: static method of Events
Returns: * - this, chainable
See: Events.listenTo

Param Type Description
emitter object instance you want to listen
event string | object event(s) name or events hash
[callback] function | object callback if events is a string or optional context if events is a hash
[context] object event callback context if event is a string

Events.off([event], [callback], [context]) ⇒ *

Will removes all registered events by given arguments. Note that if some other instance listens for events on this object then those events will be unregistered too.

Kind: static method of Events
Returns: * - this, chainable

Param Type Description
[event] string | object event name(s) or events hash
[callback] function callback
[context] object callback context

Example (Without arguments)

emitter.off();
// will remove all regsitered events

Example (By event name)

emitter.on('this:event that:event', callback);
emitter.off('that:event');
// will remove `that:event` but `this:event` will be still there
// also multiple events woorks too:
emitter.off('that:event this:event');

Example (By callback)

emitter.on({
  event1: callback1,
  event2: callback2,
  event3: callback2,
});
emitter.off(null, callback2);
// will remove `event2` and `event3` but `event1` will be still there

Example (By combination)

emitter.off('event', callback);
// removes all `event` with registered `callback`

Example (With event hash)

emitter.off({ event1: callback1, event2: null });
// will remove all `event1` with callback `callback1` and all `event2`

Example (With event hash and context)

emitter.off({ event1: callback1, event2: null }, callbackContext);
// will remove:
// 1) all `event1` with callback `callback1` and context `callbackContext`
// 2) all `event2` with any callback and context `callbackContext`

Example (With just context)

emitter.on('event1 event2', callback1, context);
emitter.on('event3', callback1);
emitter.off(null, null, context);
// will remove event1 and event2

Events.stopListening([emitter], [event], [callback], [context]) ⇒ *

Removes listening events by given arguments. If no arguments was passed, then removes all registered listenTo events

Kind: static method of Events
Returns: * - this, chainable

Param Type Description
[emitter] object emitter instance
[event] string | object event name or events hash
[callback] callback | object callback in case its a string event and context if its an events hash
[context] object context in case it's a string event

Example

listener.listenTo(emitter, 'event', callback1);
listener.listenTo(anotherEmitter, 'another:event', callback2);
listener.stopListening();
// will removes both

Example (Remove all for given emitter)

listener.listenTo(emitter, 'event1', callback1);
listener.listenTo(emitter, 'event2', callback2);
listener.listenTo(anotherEmitter, 'event1', callback2);
listener.stopListening(emitter);
// will remove events registered on emitter

Example (when emitter not specified)

listener.listenTo(emitter, 'event1', callback1);
listener.listenTo(emitter, 'event2', callback2);
listener.listenTo(anotherEmitter, 'event1', callback2);
listener.stopListening(null, 'event1');
// will remove all `event1`

Example (With events hash and specified emitter)

listener.stopListening(emitter, {
  event1: callback,
  event2: null,
});
// will remove
// 1) event1 with callback for emitter
// 2) all event2 for emitter

Example (With events hash and not specified emitter)

listener.stopListening(null, {
  event1: callback,
  event3: null
});
// will remove
// 1) event1 with callback for all emitters
// 2) all event2 for all emitters

Events.trigger(event, [...args]) ⇒ *

Trigger callbacks for the given events

Kind: static method of Events
Returns: * - this, chainable

Param Type Description
event string | object event names or event hash
[...args] * arguments to be passed, if event is a string

Example

emitter.on('event', (...args) => console.log(args));
emitter.trigger('event', 1,2,3);
// will triggers registered callback
// console output: [1,2,3]

Example (multiple events with same arguments)

emitter.trigger('event1 event2', 1,2,3);
// will trigger event1 and event2 callbacks with given arguments

Example (multiple events with different arguments)

emitter.trigger({
 event1: ['bar'],
 event2: null,
})
// will trigger `event1` with `bar`
// and event2 without arguments

Events.triggerMethod(event, [...args]) ⇒ *

Same as trigger but also in first will try to invoke instance method(s) associated with eventName. by default its a camel cased event name with prefix on, but you can override this behavior with providing your own version of getOnMethod

Kind: static method of Events
Returns: * - last (in case of multiple events) result of invoked method

Param Type Description
event string | object event names or event hash
[...args] * arguments to be passed if event is a string

Example

emitter.triggerMethod('event:one');
//in first will tries to invoke emitter.onEventOne method and returns its result

emitter.on({
 event1: callback1,
 event2: callback2,
})
emitter.triggerMethod('event1 event1');
//execution order will be
// 1) emitter.onEvent1
// 2) callback1
// 3) emitter.onEvent2
// 4) callback2
// will return the result of `onEvent2`

Events.getOnMethod(eventName, methodName) ⇒ function | falsy

Will returns emitter's own method for given eventName. Internally used by triggerMethod, feel free to override

Kind: static method of Events
Returns: function | falsy - - returns method for triggerMethod

Param Type Description
eventName string triggered event name
methodName string suggested method name: for event:one it will be onEventOne

Example (override to respect emitter's `options`)

emitter.getOnMethod = function(eventName, methodName) {
 if (typeof this.options[methodName] === 'function') {
   return this.options[methodName]; //no need to bind, it will be called with emitter as context
 }
 return typeof this[methodName] === 'function' && this[methodName];
}

setInterop(type, interop) ⇒ void

Registers interop for given type. There is a default interop which tries to use on and off It will be applied if there is no any suitable registered interop

Kind: global function

Param Type Description
type Class interop type
interop interop interop handler

Example

// registering interop for Backbone's Model
setInterop(Backbone.Model, {
 on(emitter, listener, eventName, callback) {
   emitter.on(eventName, callback, listener);
 },
 off(emiter, listener, eventName, callback) {
   emitter.off(eventName, callback, listener);
 }
});