events

This block provides a set of JS classes for working with events.

Overview

Classes provided by the block

Properties and methods of the class object

Elements of the block

Functions provided by block elements

Public block technologies

The block is implemented in:

• vanilla.js

Description

Event class

You can use this class to instantiate an event object by indicating its type and source. To do this, use the Event constructor function.

Accepted arguments:

• type {String} – Type of event. Required argument.
• target {Object} – Object (source) where the event occurred. Required argument.

Return value: Event. The event object.

Properties and methods of the class object

type property

Type: String.

Type of event.

modules.require(['events'], function(events) {

    var myevent = new events.Event('myevent', this);
    console.log(myevent.type); // 'myevent'

});

target property

Type: Object.

The object where the event occurred.

result property

Type: *.

Contains the data returned by the event's last handler function.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();
    myEmitter.on('myevent', function() { return 'hi-hi-hi'; });

    var myEvent = new events.Event('myevent');
    myEmitter.emit(myEvent)

    console.log(myEvent.result);    // 'hi-hi-hi'
});

data property

Type: *.

Contains the data passed to the event's handler function as an argument.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();
    myEmitter.on('myevent', 'my-data', function(e) { console.log(e.data); });

    myEmitter.emit('myevent'); // my-data
});

preventDefault method

Allows you to prevent execution of the default action for the event.

Doesn't accept arguments.

No return value.

isDefaultPrevented method

Allows you to check whether the default action for the event was prevented from being executed.

Doesn't accept arguments.

Return value: Boolean. If the default action for the event was prevented from being executed, it is true.

stopPropagation method

Allows you to stop event propagation.

Doesn't accept arguments.

No return value.

isPropagationStopped method

Allows you to check whether event propagation was stopped.

Doesn't accept arguments.

Return value: Boolean. If event propagation was stopped, it is true.

Emitter class

This class instantiates objects that you can use for generating events and subscribing to them.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

});

Properties and methods of the class object

on method

Subscribes to a specific type of event.

Accepted arguments:

• type {String} – The type of event being subscribed to. Required argument.
• [data {Object}] – Additional data available to the handler as the value of the e.data field in the event object.
• fn {Function} – The handler function to call for the event. Required argument.
• [ctx {Object}] – Context for the handler function.

Returns the this object.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent', function() { console.log('foo'); });
    myEmitter.emit('myevent'); // 'foo'
});

In addition, the value of the type argument may be:

• Multiple event types separated by spaces, in order to set a single handler function for all of them.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent1 myevent2', function(e) { console.log(e.type) });

    myEmitter.emit('myevent1'); // 'myevent1'
    myEmitter.emit('myevent2'); // 'myevent2'
});

• A hash of { 'event-1' : handler-1, ... , 'event-n' : handler-n }, in order to set multiple handlers for different event types.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on({
        myevent1 : function(e) { console.log(e.type) },
        myevent2 : function(e) { console.log(e.type) }
    });  

    myEmitter.emit('myevent1'); // 'myevent1'
    myEmitter.emit('myevent2'); // 'myevent2'
});

The same is true for the once and un methods.

once method

Identical to the on method, but it only executes once. After the first event, the subscription is removed.

Accepted arguments:

• type {String} – The type of event being subscribed to. Required argument.
• [data {Object}] – Additional data available as the value of the e.data field in the event object.
• fn {Function} – The handler function to call for the event. Required argument.
• [ctx {Object}] – Context for the handler function.

Returns the this object.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent', function() { console.log('foo') });

    myEmitter.emit('myevent'); // 'foo'
    myEmitter.emit('myevent'); //handler isn't called
});

un method

Removes a previously set subscription to a specific type of event.

Accepted arguments:

• type {String} – The type of event being unsubscribed from. Required argument.
• [fn {Function}] – The handler to delete.
• [ctx {Object}] – The handler context.

The method returns a reference to the this object.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter(),
        shout = function() { console.log('foo') };

    myEmitter.on('myevent', shout);
    myEmitter.emit('myevent'); // 'foo'

    myEmitter.un('myevent', shout);
    myEmitter.emit('myevent'); //handler isn't called
});

emit method

Generates an event.

This method calls all the handler functions set for the event.

Accepted arguments:

• type {String|events:Event} – The event to generate, in the form of a string or a prepared event object. Required argument.
• [data {Object}] – Additional data available as the second argument of the handler function.

Returns the this object.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent', function(e, data) { console.log(data) });
    myEmitter.emit('myevent', 'ololo');  // 'ololo'
});

Static methods of the class

The set of static methods and their signatures is exactly the same as for the methods of the object being instantiated by the class.

channels element in the events block

Use the channels element in the events block for working with named event channels. Named channels allow you to work with events using the observer pattern (also known as the publish-subscribe pattern).

This element implements a function to:

• Get a reference to a named channel by its id.
• Get a reference to a standard channel.
• Remove a standard channel or a named channel with an id.

Accepted arguments:

• [id {String}] – Channel ID. If omitted, the default channel is used ('default').
• [drop {Boolean}] – A boolean flag to remove the channel (when true). By default, false.

Returned value:

• Object. Object of the Emitter "class" – a named channel.
• undefined. If the function was called with the drop parameter set to true.

Example:

modules.require(['events__channels'], function(channels) {

var myChannel = channels('my-channel');
myChannel.on('test', function(e, data) { console.log(data.foo) });

myChannel.emit('test', { foo : 'bar' }); // 'bar'

});