Events

Nuggets has its own listeners and can receive events.

Notification propagation is therefore isolated and does not mix with events emitted by the Storyline reader or the HTML document.

Storyline player events

For certain functions, Nuggets implements an event interface to report the behaviour of certain HTML elements in the Storyline player.

On request, Nuggets can trigger an event to propagate a notification when an element changes. A notification can be emitted :

  • when a transition between two slides is performed;
  • when the subtitles are displayed, refreshed or cleared;
  • when the Lightbox is opened or closed.

Initialisation

In order to receive notifications about any of these elements, you need to initialise an observer for each of them. Without this, even if you attach a callback function to one of the listeners, nothing will happen.

JavaScript
// Initialise to listen to the 'Slide' element
storyline.watchSlide();

// Initialise to listen to the 'Caption' element
storyline.watchCaption();

// Initialise to listen to the 'Lightbox' element
storyline.watchLightbox();

We can then link a callback function so that it is invoked when the notification is issued:

JavaScript
const onSlideChanged = (event) => { /* instructions */ }
nuggets.addEventListener(STORYLINE_EVENTS.SLIDE_CHANGE,onSlideChanged);

const parseCaption = (event) => { /* instructions */ }
nuggets.addEventListener(STORYLINE_EVENTS.DISPLAY_CAPTION,parseCaption);


Now let's look at the events for each of the observers. All event types are contained in a single STORYLINE_EVENTS object.

Slide events

Types Arguments Propagation
SLIDE_CHANGE 'onSlideChange' slideId Emitted when two slides are sequenced.
SCENE_CHANGE 'onSceneChange' sceneId When two slides are sequenced, emitted when they are not on the same stage.

Caption events

Types Arguments Propagation
DISPLAY_CAPTION 'displayCaption' - Emitted when a subtitle appears.
CHANGE_CAPTION 'changeCaption' - Emitted when two captions follow each other.
If there is a blank interval between two captions, the events REMOVE_CAPTION and DISPLAY_CAPTION, in this order, which are notified instead.
REMOVE_CAPTION 'removeCaption' - Emitted when the displayed caption disappears.

Lightbox events

Types Arguments Propagation
OPEN_LIGHTBOX
'openLightBox'		 - Emitted when the Lightbox is open.
CLOSE_LIGHTBOX
'closeLightBox'		 - Emitted when the Lightbox is closed.


Data transmission

By enabling the creation of customised events with specific data, the library offers a flexible and elegant way of connecting the different parts of one or more functionalities, while promoting the modularity and reusability of the code. This helps to reduce coupling between the different functionalities that make up Nuggets, as well as with the Storyline player.

Functionalities can communicate asynchronously without having to know the internal details of each other. This favours a modular architecture and makes code maintenance easier.

When Nuggets needs to transmit data, the library automatically uses a CustomEvent. The data is then encapsulated in the event's detail object.

JavaScript
// To send data
const data = { myVar: 'valeur' };
nuggets.dispatchEvent( 'typeEvent', data );

// To receive data
const callback = (event) => console.log(event.detail.myVar );
nuggets.addEventListener( 'typeEvent', callback );