Skip to content

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
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
mapzoom Vector Map, Geo Map
mapmove Vector Map, Geo Map
text-change Markup
enable-editor Markup
background-editor Markup
player-conf-changed Time Slider
player:start Time Slider
player:stop Time Slider
sort-changed Slicer, RDT, Pivot Table
rdt:data-updated RDT

Suscribing to events

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

1
object.on('eventname', callback)

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

1
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.

1
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:

1
chart.get('events')

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

1
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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:

1
2
3
4
5
6
7
// 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:

1
2
3
4
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):

1
2
3
4
5
6
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:

1
2
3
4
5
6
7
8
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)
    }
})

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.