JavaScript Events API

The ai JavaScript object offers a few methods to register event types, add and remove event listeners to events of these types and trigger the registered listeners by firing a respective event.

Enabling

To use the event api you have to enable it in your config:

<config>
  <js-api>
    <event/>
  </js-api>
</config>

The Events API is implicitly enabled (even if explicitly disabled via <event enable="false"/>) by enabling one of

in config.xml or by registering an Adaptive Component.

Activating this feature will also activate the load events!

Adding an event type

To add a new event type you need to call the ai.addEventType function:

ai.addEventType(eventType)
//example: 
ai.addEventType('scriptReady');

Arguments

One of:

  • eventType
    • String, name of the event type
  • eventType
    • Object, with properties
      • name
        • String, name of the event type
      • triggerOnRegister
        • Boolean, if true every listener registered to this event will be fired once instantly with the data of the last recorded event
      • clearOnPPLRequest
        • Boolean, if true every listener registered to this event will be cleared with the next pplstart event

FIT tries to behave as similarly and consistent as possible, whether PPL is enabled or not.

To achieve this consistent behaviour, some event listeners (e.g. ready and load or stageinit) have to be removed when the visitor navigates from one page to another.

The clearOnPPLRequest option tells fit whether or not the registered event type must have the list of listeners cleared when a PPL request starts, so neither the provider nor the user of the event have to further worry about it.

Return Value

  • Boolean
    • true if event type was added
    • false if event type was not added (i.e. was already defined)

Adding an event listener

To add a new listener for a specific event you need to call the ai.addEventListener function.

ai.addEventListener(eventType, listenerFunction)
//example:
function initSliders() {
  //...
}
ai.addEventListener('scriptReady', initSliders);

Arguments

  • eventType
    • String, name of the event type
  • listenerFunction
    • Function reference, the function that should be executed when the event is triggered

Return Value

  • Mixed
    • Function reference to the passed listenerFunction if listener was added
    • Boolean false if function was not added (i.e. was already registered for the event)

Note: addEventListener implicitly registers the event type if it is not already registered via addEventType.

Removing an event listener

To remove a registered listener for a specific event you need to call the ai.removeEventListener function.

ai.removeEventListener(eventType, listenerFunction)
//example:
ai.removeEventListener('scriptReady', initSliders);

Arguments

  • eventType
    • String, name of the event type
  • listenerFunction
    • Function reference, the function that must no longer be executed when the event is triggered

Return Value

  • Mixed
    • Function reference to the passed listenerFunction if listener was removed
    • Boolean false if function was not removed (i.e. was not registered for the event, or the event type was not registered)

Triggering an event

To trigger an event and make all the functions that are registered as listeners execute you have to call the ai.fireEvent function.

ai.fireEvent(eventType, eventData)
//example:
ai.fireEvent('scriptReady', {time: new Date().getTime()});

Arguments

  • eventType
    • String, name of the event type
  • eventData
    • Object containing the data that will be passed to the listener functions

Attention! This object will be altered by the fireEvent function! It will add a type property, with the value of eventType.

Attention! This object can be altered by the listener functions it is passed to.

Return Value

  • Mixed
    • Object The object that was passed to the listener functions
    • Boolean false if the event type was not registered

Reserved event types

Comprehensive list of reserved event types:

  • ready
  • load
  • detectioninit
  • dcupdate
  • orientationchange
  • hqimageloaded
  • delayedimagesloaded
  • delayediframeloaded
  • delayediframesloaded
  • userscripterror
  • stageinit
  • pplinit
  • pplstart
  • pplnavstart
  • pplcontentready
  • pplend
  • pplnavend
  • xhrstart
  • xhrnetworkerror
  • xhrerror
  • xhrabort
  • xhrtimeout
  • xhrbadhttpstatus
  • xhrend
  • _resourceloaderfinished
  • _stagedestroy
  • _pplcontentreplaced