BoundListenerMgr

import BoundListenerMgr from '@bbc/front-end-kit/js/managers/BoundListenerMgr';

Sometimes it can be tough to keep access to the original scope when listeners are called by events. Luckilly there is a way to bind the scope to a function before it is executed.

The downside of this is when listeners need to be cleaned up to avoid double executions later. When binding a method, a new method is returned and passed to the subscribe methods like addEventListener or on. This means that the new method is the subscibed one and needs to be passed to the unsubscribe methods like removeEventListener or off and thus needs to be kept in memory and accessible untill the clean up process takes place.

This is where BoundListenerMgr comes in.

It will track all the bound methods in a single manager instance within the scope that it is operating while keeping the scope it is working in as clean as possible.

Getting started

class CustomClass {
    constructor () {

        // ...

        // initialise the manager
        this._blm = new BoundListenerMgr({
            scope: this
        });

        // add listeners to dom elements
        this._$button.addEventListener('click', this._blm.add('onButtonClick', onButtonClick));

        // ...

    }

    destroy() {
        // ...

        // remove listeners to dom elements
        this._$button.removeEventListener('click', this._blm.remove('onButtonClick'));

        // destroy the manager
        this._blm.destroy();

        // ...

    }
}

API

Methods

constructor(args = {})

The constructor method initialises the new BoundListenerMgr instance.

Parameters

• args: The configuration object used by the constructor to initialise the BoundListenerMgr in the desired way.
  • scope: The scope it needs to bind to every function it manages

add (key, method, scopeOverride = null)

Adds an method to the list of the given key and binds it to either the scope of the instance or a given scope if provided while the add() method is called.

Parameters

• key: Key on which the listener is stored so it can be retrieved later
• method: Method to bind to the scope
• scopeOverride: Way of overriding the scope the instance would use otherwise

Return

Returns the bound version of the method instantly so it can be passed all at once.

addOnce (key, method, scopeOverride = null)

Adds a method just like add() does but checks if the given key isn't already in use. If it is it will not bind the method and return the previously bound method instead.

Parameters

• key: Key on which the method is stored so it can be retrieved later
• method: Method to bind to the scope
• scopeOverride: Way of overriding the scope the instance would use otherwise

Return

Returns the bound version of the method instantly so it can be passed all at once.

get (key)

Gets the bound method stored on the given key.

Parameters

• key: The key on which the method is stored.

Return

Returns the bound method if found, if not it returns undefined

getDefinition (key)

Gets the full entry definition that is stored on the given key. The returned object contains all the information the instance uses to keep track of the listener in its map

Parameters

• key: The key on which the definition is stored.

Return

Returns an object with the following parameters

• originalMethod: The original method that has been bound to another scope
• boundMethod: The newly created method wrapper that runs originalMethod in the right scope
• scope: The scope that was used

remove (key)

Removes a bound method on the given key and returns the bound method after is done.

Parameters

• key: The key on which the method is stored.

Return

Returns the bound method that was removed from the instance.

destroy ()

Destroys the instance and clears its internal map.

Methods (continued)

map ()

Returns the internal Map in which all the method, bound method and scope data is stored.

Private Properties

_map

The internal Map in which all the method, bound method and scope data is stored.

_scope

The scope the instance will used by default when binding new methods.