Events

The Events module provides a mechanism for emitting and receiving events.

A event emitted by emit method will only be received by the modules defined in the same add-on.
Public events that emitted by emitPublic are used for cross add-on communication. They can be received by any add-on modules that are currently presented on the page.

This module is currently not supported on mobile. See JRACLOUD-79910 for more details.

Basic example

Add-on A:

1
2
3
4
5
6
7
8
// The following will create an alert message every time the event `customEvent` is triggered.
AP.events.on('customEvent', function(){
  alert('event fired');
});


AP.events.emit('customEvent');
AP.events.emitPublic('customPublicEvent');

Add-on B:

1
2
3
4
// The following will create an alert message every time the event `customPublicEvent` is triggered by add-on A.
AP.events.onPublic('customPublicEvent', function(){
  alert('public event fired');
});

Methods

on (name, listener)

Adds a listener for all occurrences of an event of a particular name.
Listener arguments include any arguments passed to events.emit, followed by an object describing the complete event information.

Parameters

NameTypeDescription
name

String

The event name to subscribe the listener to

listener

function

A listener callback to subscribe to the event name


onPublic (name, listener, filter)

Adds a listener for all occurrences of a public event of a particular name.
Listener arguments include any arguments passed to events.emitPublic, followed by an object describing the complete event information.
Event emitter's information will be passed to the first argument of the filter function. The listener callback will only be called when filter function returns true.

Parameters

NameTypeDescription
name

String

The event name to subscribe the listener to

listener

function

A listener callback to subscribe to the event name

filter

function

A filter function to filter the events. Callback will always be called when a matching event occurs if the filter is unspecified


once (name, listener)

Adds a listener for one occurrence of an event of a particular name.
Listener arguments include any argument passed to events.emit, followed by an object describing the complete event information.

Parameters

NameTypeDescription
name

String

The event name to subscribe the listener to

listener

function

A listener callback to subscribe to the event name


oncePublic (name, listener, filter)

Adds a listener for one occurrence of a public event of a particular name.
Listener arguments include any argument passed to events.emit, followed by an object describing the complete event information.
Event emitter's information will be passed to the first argument of the filter function. The listener callback will only be called when filter function returns true.

Parameters

NameTypeDescription
name

String

The event name to subscribe the listener to

listener

function

A listener callback to subscribe to the event name

filter

function

A filter function to filter the events. Callback will always be called when a matching event occurs if the filter is unspecified


onAny (listener)

Adds a listener for all occurrences of any event, regardless of name.
Listener arguments begin with the event name, followed by any arguments passed to events.emit, followed by an object describing the complete event information.

Parameters

NameTypeDescription
listener

function

A listener callback to subscribe for any event name


onAnyPublic (listener, filter)

Adds a listener for all occurrences of any event, regardless of name.
Listener arguments begin with the event name, followed by any arguments passed to events.emit, followed by an object describing the complete event information.
Event emitter's information will be passed to the first argument of the filter function. The listener callback will only be called when filter function returns true.

Parameters

NameTypeDescription
listener

function

A listener callback to subscribe for any event name

filter

function

A filter function to filter the events. Callback will always be called when a matching event occurs if the filter is unspecified


off (name, listener)

Removes a particular listener for an event.

Parameters

NameTypeDescription
name

String

The event name to unsubscribe the listener from

listener

function

The listener callback to unsubscribe from the event name


offPublic (name, listener)

Removes a particular listener for a public event.

Parameters

NameTypeDescription
name

String

The event name to unsubscribe the listener from

listener

function

The listener callback to unsubscribe from the event name


offAll (name)

Removes all listeners from an event name, or unsubscribes all event-name-specific listeners if no name if given.

Parameters

NameTypeDescription
name

String

The event name to unsubscribe all listeners from


offAllPublic (name)

Removes all listeners from a public event name, or unsubscribes all event-name-specific listeners for public events if no name if given.

Parameters

NameTypeDescription
name

String

The event name to unsubscribe all listeners from


offAny (listener)

Removes an any event listener.

Parameters

NameTypeDescription
listener

function

A listener callback to unsubscribe from any event name


offAnyPublic (listener)

Removes an anyPublic event listener.

Parameters

NameTypeDescription
listener

function

A listener callback to unsubscribe from any event name


emit (name, args)

Emits an event on this bus, firing listeners by name as well as all 'any' listeners.
Arguments following the name parameter are captured and passed to listeners.

Parameters

NameTypeDescription
name

String

The name of event to emit

args

[ 'Array' ].<String>

0 or more additional data arguments to deliver with the event


emitPublic (name, args)

Emits a public event on this bus, firing listeners by name as well as all 'anyPublic' listeners.
The event can be received by any add-on modules that are currently presented on the page.
Arguments following the name parameter are captured and passed to listeners.

Parameters

NameTypeDescription
name

String

The name of event to emit

args

[ 'Array' ].<String>

0 or more additional data arguments to deliver with the event