LoaderEvents Overview
In Yellowfin 9.4 we enabled the option to add customized loaders to the Javascript API through the “loaderEvents” API.
This allows a developer to listen for instances where an element within a Yellowfin element has a loader added to it or removed from it and then reacts to that event.
There are a number of different actions that could be taken. They include:
- prevent the Yellowfin loader from being added, and add a custom loader onto the same element;
- attach a loader to a different, related element; and.
- log the loader being added or removed (useful during development).
For example, a business using a white-label version of Yellowfin software might prefer to use their own loader icon to match their brand rather than the default blue circle that ships with Yellowfin.
Note: due to the nature of the LoaderEvents API, it has no properties nor events associated specifically with it.
Function Reference
yellowfin.loaderEvents
After the Yellowfin API init()
call has completed, the yellowfin.loaderEvents
function will become available. This provides two functions — listen
and stopListening
— which allow you to setup and remove loader events as you require.
listen(listenObject)
This creates a loader event listener with the passed listenObject
object.
The listenObject object
should contain the following parameters.
Parameter | Type | Description | Extra info |
---|---|---|---|
| String | The CSS selector for the object you wish to create the listener on. If you wish to intercept all loaders you can use the selector | If no |
| Function | The function that is called immediately before Yellowfin adds a loader to an element that matches the selector. A | Either |
| Function | A callback function which is immediately before Yellowfin code removes a loader from an element that matches the selector. A | Either |
stopListening(listenObject)
Removes a loader event, the passed listenObject
must be the exact same object that was passed into the listen function. Otherwise the listener will not be removed.
LoaderEvent
Each time an onAdd
or onRemove
function is called, a LoaderEvent
object will be created. This contains the element the loader is going to be added to, as well as some functions which allow manipulation of how the event is handled.
LoaderEvent.element
This is the element which the loader is going to be added to or removed from.
LoaderEvent.preventDefault()
This event prevents the loader from being added to or removed from the element.
For example, you could initialize your event listener like this:
yellowfin.loaderEvents.listen({ selector: ‘html *’, onAdd: function(event) { event.preventDefault(); } });
This would cause no loaders to be added to any Yellowfin elements. This by itself isn’t particularly useful, however you could combine the preventDefault with code that adds your own customized loader.
If you were to create an event listener that only contained an onRemov
e function that prevented default, like this:
yellowfin.loaderEvents.listen({ selector: ‘html *’, onRemove: function(event) { event.preventDefault(); } });
This would prevent the loader from being removed from the element. As such you should generally only use preventDefault
on removal when you are handling the loader removal yourself in the onRemove
function.
LoaderEvent.setOverrideElement(element)
Defines an element to append the standard Yellowfin loader to, rather than the element that has been passed in the LoaderEvent
object.
This means that if you wish the standard Yellowfin loader to be on a parent element it can be. When using this function, you must define the setOverideElement
in both the onAdd
and onRemove
functions.
yellowfin.loaderEvents.listen({ selector: ‘report-output > div’, //Listen for loaders on immediate children of all reports onAdd: function(event) { event.setOverrideElement(event.element.parentNode); //Adds a loader to the parent node of the passed element }, onRemove: function(event) { event.setOverrideElement(event.element.parentNode); //Removes the loader from the parent node } });