Events

ChartFactor handles many processes through events. These events are triggered from different objects at different moments and we can subscribe to them in order to enrich our application.

The events are mainly fired from the aktive instance and the visualization (chart) inside the aktive instance. When the aktive is only used for querying, the visualization events won't be triggered.

The global ChartFactor object ( the cf object) also triggers some generic events we can subscribe to. In addition we can create our custom events by using this object in our applications.

Here is a list of the supported events:

Event	Object / Visualization
aktive:added	CF Object
aktive:removed	CF Object
execute:start	Aktive Object
execute:stop	Aktive Object
error	Aktive Object
click	All visuals
mousemove	All visuals
mouseleave	All visuals
notification	All visuals
slicerfilter	Slicer
customchartfilter	Custom Chart
datazoom	Bars, Trend, Area Line, (charts with axis)
timefilter	Time Slider, Time Picker, Time Range
textfilter	Text Search
rangefilter	Range Filter
filter:before-add	Interaction Manager
filter:added	Interaction Manager
filter:before-remove	Interaction Manager
filter:removed	Interaction Manager
filter:viz-finish	Interaction Manager
filter:text	Interaction Manager
field-selected	Field Selector
mapzoomstart	Geo Map GL. Triggered when the mapzoom process starts.
mapzoom	Vector Map, Geo Map, Geo Map V2, Geo Map GL. Triggered when the mapzoom process ends.
mapmove	Vector Map, Geo Map, Geo Map V2, Geo Map GL
mappitch	Geo Map GL
maprotate	Geo Map GL
geo:layer-added	Geo Map V2, Geo Map GL
geo:layer-changed	Geo Map V2, Geo Map GL
geo:layer-removed	Geo Map V2, Geo Map GL
geo:layers-execution-start	Geo Map V2, Geo Map GL
geo:layers-execution-stop	Geo Map V2, Geo Map GL
geo:layers-control-changed	Geo Map V2, Geo Map GL
player-conf-changed	Time Slider
player:start	Time Slider
player:stop	Time Slider
sort-changed	Slicer, RDT, Pivot Table
rdt:data-updated	RDT
rdt:columnMoved	RDT
rdt:dragStopped	RDT
rdt:columnPinned	RDT
rdt:col-stats-rendered	RDT
rdt:col-stats-rendered	RDT
text:change	Markup, Markdown
text:enable-editor	Markup
text:background-editor	Markup
text:editor	Markdown

Suscribing to events

All events (cf, aktive and visualizations) are suscribed in the following way:

object.on('eventname', callback)

We can do a one time suscription to events so they will be listened only once:

object.once('eventname', callback)

We can suscribe to the same event with different callbacks. It's important to mention that an aktive instance only accepts up to 10 event suscriptions.

Unregistering events

We can unsubscribe from any of the previous events with the off method.

object.off('eventname', myCallback)

The callback parameter is optional. If not provided, the off function removes all handlers matching the event name provided.

Get the suscribed events

To know what events we are subscribed to for an aktive instance use the following:

chart.get('events')

For the case of the cf global object you can obtain the events like this:

cf.getEvents()

Event data

The content returned by the event differs on the object that triggered it and the visualization type. Most of them provide information about the type of visual, element (if any) and errors. Each specific visual event is explained on the visualization documentation page. Lets take a look:

var myCallback = function(e){
    console.log("I'm the event:", e.name)
    console.log('I belongs to this element:', e.chart)
    console.log('I have the data:', e.data)
    console.log('I have other metadata', e.nativeData)
}
myChart.execute()
myChart.on('click', myCallback)
myChart.on('mouseover', myCallback)
myChart.on('mouseleave', myCallback)

As we can see, these 3 events return the same structure. So in event.data we can find the data for the element being hovered, clicked or zoomed. This is what we use to build filters and apply them to other visuals and queries. Specifically the click event. You can see how to build filters here.

event.nativeData will differ from one event to another and it contains a set of metadata related to the visual, like the seriesIndex, componentTypes and others.

The global CF events

The cf object comes with 3 events by default:

1. aktive:added which is triggered when a new Aktive object is created using the cf.create() or the cf.provider() methods.

2. aktive:removed Same as above but called when an Aktive object is removed using the cf.remove('id') or the aktive.remove() methods.

Custom Events

As mentioned at the beginning, you can create your own events by using the global cf object. These events are not related with inner workings of ChartFactor but with your own logic. This can be very useful for example if you are working with Angular or React and you need to notify siblings components in an easier way:

// Subscribe to the event
cf.on('my-custom-event', (event) => {
      console.log('Hey my custom event was fired with this data:' event.data)
})

// Trigger the event from anywhere:
cf.dispatch({ name: 'my-custom-event', data: {...} })

Notifications Event

This event can be triggered from any visualization and is used to display different levels of notifications to the user:

myChart.on('notification', event => {
    const msg = `${event.type}: ${event.message}`
    alert(msg);
})

These notifications can be one of the following types: info, success, warning or error.

Aktive Execution Events

There are two events that control the entire execution process which involves data querying and visualization rendering (if any):

const callback = event => { 
  console.log(event) 
}

myChart.on('execute:start', callback)
myChart.on('execute:stop', callback)

The first one is triggered the moment .execute() is invoked. These can be used for example to display a loading indicator.

The second comes in when the aktive instance processing is finished. It can be fired according to these rules:

1. If the aktive represents just a query, the event is triggered when data is ready to be used.
2. If the aktive represents a visualization, it will be triggered when the data has been injected into the visualization and the render process is completed.
3. If the aktive processing fails at any stage for any reason (user error in the aql configuration, provider or data errors, visualization errors, etc) it will be triggered notifiying the user with the flag error as true.

For the cases 1 and 2, the event payload will bring the data retrieved in the data parameter. For the 3rd case data will contain the error information. Here is an example:

myChart.on('execute:stop', event => {
    console.log(`Visualization ${event.element} is ready`)
    if (event.error) {
      console.log('An error has occurred: ', event.data)
    } else {
      console.log('Data fetched: ', event.data)
    }
})

Additionally, you can subscribe to the Aktive error event to handle any error that may occur during the execution of a query or visualization. The event includes the following properties:

• The elementId
• The exception message
• The excpetion itself

Example:

myChart.on("error", e => handleError(e.element, e.error))

Events Persistency

As explained here, visuals are re-used based on the their elements. Any event attached to a visual, will persist over any other re-usage of the element as long as the initial visual is not removed. So for example, if we have a Bars chart, and then we modify it by adding a couple of options or changing filters, metrics…etc, and on top of that we switch to use a Pie chart instead, after the .execute() method all events that were subscribed to the Bars will be fired for the Pie as well, so there’s no need to register them again.