Forum

Methodology

Toolbox

Platform

Community

desktop
touch-pad
touch-phone

events

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

Overview

Classes provided by the block

Class Constructor Description
Event Event(
type {String},
target {Object})
Creates the event object and changes and checks its states.
Emitter - Generates events and subscriptions to them.

Properties and methods of the class object

Class Name Type or return value Description
Event type String Type of event.
result * The result returned by the event's last handler.
target Object The object where the event occurred.
data * Data to pass to the handler as an argument.
preventDefault() - Allows you to prevent execution of the default action for the event.
isDefaultPrevented() Boolean Checks whether the default action for the event was prevented from being executed.
stopPropagation() - Allows you to stop event propagation.
isPropagationStopped() Boolean Checks whether event propagation was stopped.
Emitter on(
type {String},
[data {Object}],
fn {Function},
[ {Object} ctx])
- Subscribes to a specific type of event.
once(
type {String},
[data {Object}],
fn {Function},
[ctx {Object}])
- Subscribes to a specific type of event. The handler executes only once.
un(
type {String},
fn {Function},
[ctx {Object}])
- Unsubscribes to a specific type of event.
emit(
type {String|events:Event},
[data {Object}])
- Generates an event.

Elements of the block

Element Usage Description
channels JS Used for working with named event channels.

Functions provided by block elements

Element Function Return type Description
channels channels(
[id {String}],
[drop {Boolean}])
Object|undefined Creates or deletes a named event channel.

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'

});
Instance methods:
on
once
un
emit
Object methods:
Event
Emitter
Class Event
Instance methods:
preventDefault
isDefaultPrevented
stopPropagation
isPropagationStopped
Members
type
target
data
Constructor
Class Emitter
Instance methods:
on
once
un
emit

Module events

Instance methods:

on(e, [data], fn, [ctx]):Emitter
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
once(e, [data], fn, [ctx]):Emitter
description
Adds a one time handler for the event. Handler is executed only the next time the event is fired, after which it is removed.
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
un([e], [fn], [ctx]):Emitter
description
Removes event handler or handlers
parameters
e
String
Event type
fn
Function
Handler
ctx
Object
Handler context
emit(e, [data]):Emitter
description
Fires event handlers
parameters
e
String, events:Event
Event
data
Object
Additional data

Object methods:

Event()
Emitter()

Class Event

Instance methods:

preventDefault()
description
Prevents default action
isDefaultPrevented():Boolean
description
Returns whether is default action prevented
stopPropagation()
description
Stops propagation
isPropagationStopped():Boolean
description
Returns whether is propagation stopped

Members

type()
description
Type
target()
description
Target
data()
description
Data

Constructor

parameters
type
String
target
Object

Class Emitter

Instance methods:

on(e, [data], fn, [ctx]):Emitter
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
once(e, [data], fn, [ctx]):Emitter
description
Adds a one time handler for the event. Handler is executed only the next time the event is fired, after which it is removed.
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
un([e], [fn], [ctx]):Emitter
description
Removes event handler or handlers
parameters
e
String
Event type
fn
Function
Handler
ctx
Object
Handler context
emit(e, [data]):Emitter
description
Fires event handlers
parameters
e
String, events:Event
Event
data
Object
Additional data

events__channels

Returns/destroys a named communication channel
parameters
id
String
Channel ID
drop
Boolean
Destroy the channel
returns
events:Emitter, undefined
Communication channel

events__observable

Creates new observable

Instance methods:

on(e, [data], fn, [fnCtx]):Observable
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
fnCtx
Object
Context
once(e, [data], fn, [fnCtx]):Observable
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
fnCtx
Object
Context
un([e], [fn], [fnCtx]):Observable
description
Removes event handler
parameters
e
String
Event type
fn
Function
Handler
fnCtx
Object
Context
parameters
emitter
events:Emitter
returns
Observable

events__observable_type_bem-dom

Creates new observable
parameters
bemEntity
i-bem-dom:Block, i-bem-dom:Elem, events:Emitter
returns
Observable