Experience the power of Luzmo. Talk to our product experts for a guided demo or get your hands dirty with a free 10-day trial.
September 8, 2022
Tuana Çelik
Learn how to develop dashboards that interact with your application.
🚨 Our embedded analytics platform, formerly called Cumul.io, is now Luzmo! You can read all about our rebranding here. To avoid confusion: the GitHub repos and code snippets used in this tutorial will reference Cumul.io. But fear not! Any code you'll leverage in this tutorial is fully functional. So simply follow along, and if you'd happen to run into any issues, you can reach us at support@luzmo.com.
The time has come to share a demo on Custom Events on Luzmo (formerly Cumul.io). A great feature you can use to make your creativity shine and bring dashboards to life. By the end of this blogpost, you’ll be able to create your own custom events, and use them in your application.
For the purpose of this walkthrough, we’ve created a fun demo using the Spotify Web API. Here, we use our dashboard as an insight into playlist and song characteristics. We’ve added some custom events that will allow any end user visiting our dashboards to select songs from a chart and add them to one of their own Spotify playlists. They can also select a song to display more info on them, and play them from within the application. You can try all of this out here! And the code is also publicly available in an open repository.
Here’s a sneak peak into what the end result for the full version looks like:
Simply put, custom events are a way to trigger an event from your dashboard, to be used in your own application. You can add custom events into selected charts in your dashboard, and have your application listen for these events. Once the event is triggered and your application is notified of this, you will have access to info such as the ID of the dashboard the event was triggered from, the name of the event and the values of the point in the chart it was triggered from. Now, you are free to implement any custom functionality you may want.
The power of this tool is in how it allows you to reuse data from your dashboards within your application. It gives you the freedom to define actions based on data, that can be triggered straight from within an integrated dashboard. A simple example might be a chart about employees/colleagues, and an event that you define that means when you click on a data point representing a person, you switch tabs to see that person’s profile. Or, you may want to have a few options: to see their profile, or to send them an email for example.
An important thing to note is that custom events are attached to charts rather than dashboards as a whole. So the information an event has is limited to the information a chart has. In other words, the data that an event has is limited to the data made available to the chart.
An event is simply put a JSON object. This object will contain fields such as the ID of the dashboard that triggered it, the name of the event and a number of other fields depending on the type of chart that the event was triggered from. For example, if the event was triggered from a scatter plot, you will receive the x-axis and y-axis values of the point it was triggered from. On the other hand, if it were triggered from a table, you would receive column values for example. See examples of what these events will look like from different charts:
The possibilities with this functionality are virtually limitless. Granted, depending on what you want to do, you may have to write a couple more lines of code, but it is unarguably quite a powerful tool!
We’ve chosen to build a demo that uses the Spotify Web API. The idea is to build a dashboard that’s integrated into a simple web application, which can be used to add songs to your own Spotify playlists. We have a dashboard that displays playlist analytics, such as the energy, acousticness, danceability of its songs (all metrics accessible via the Spotify Web API). Custom events, in turn, create the appropriate API calls to Spotify from within the application.
Another thing we do is to integrate yet another dashboard within the application that displays further information on the song that was clicked. This is an example of a drill through dashboard. It zooms into a certain part of a chart to display a dashboard with more detail on that point.
Note: We have already added the custom events to the dashboard used in this demo. If you want to go through this step, feel free to create your own dashboards too!
First thing you need to do will be to add custom events to a chart. To do this, first select a chart in your dashboard you’d like to add an event to. In the chart settings, select Interactivity and turn Custom Events on:
To add an event, click edit and define its Event Name and Label. Event Name is what your application will receive and Label is the one that will show up on your dashboard. In our case, we’ve added 2 events; ‘Add to Playlist’ and ‘Song Info’:
This is all the setup you need for your dashboard to trigger an event on a chart level. Before you leave the editor, you will need your dashboard ID to integrate the dashboard later. You can find this in the Settings tab of your dashboard. The rest of the work remains on application level. This will be where we define what we actually want to do once we receive any of these events.
Now that you’ve added some events to the dashboard, the next step is to use them. The key point here is that, once you click an event in your dashboard, your application that integrates the dashboard receives an event. Our Integration API provides a function to listen to these events, and then it’s up to you to define what you do with them. For more information on the API and code examples for your SDK, you can also check out the relevant developer docs.
For this section, we’re also providing an open GitHub repository (separate to the repository for the main application) that you can use as a starting project to add custom events to.
The cumulio-spotify-datatalks repository is structured so that you can checkout on the commit called skeleton to start from the beginning. All the following commits will represent a step we go through here. It’s a boiled down version of the full application, focusing on the main parts of the app that demonstrates Custom Events. I’ll be skipping some steps such as the Spotify API calls which are in src/spotify.js, so as to limit this tutorial to the theme of ‘adding and using custom events’. To run this project with all of its capabilities, you can register an application on the Spotify Developer Dashboard and use the instructions at the bottom of this article to locally run the project.
Let’s have a look at what happens in our case. We had created 2 events; ‘add_to_playlist’ and ‘song_info’. We want visitors of our dashboard to be able to add a song to their own playlist of choice in their own Spotify account. In order to do so, we take the following steps:
First, we need to add a dashboard to our application. Here we use the Luzmo Spotify Playlist dashboard as the main dashboard and the Song Info dashboard as the drill through dashboard. If you have checked out on the commit called skeleton and npm run start, the application should currently just open up an empty ‘Cumul.io Favorites’ tab, with a Login button at the top right. For instructions on how to locally run the project, go to the bottom of this blogpost.
To integrate a dashboard, we will need to use the Cumulio.addDashboard() function. This function expects an object with dashboard options. Here’s what we do to add the dashboard.
In src/app.js, we create an object that stores the dashboard IDs for the main dashboard and the drill through dashboard that displays song info alongside a dashboardOptions object:
We create a loadDashboard() function that calls Cumulio.addDashboard(). This function optionally receives a container and modifies the dashboardOptions object before adding dashboard to the application.
Finally, we use this function to add our playlist dashboard when we load the Cumul.io Favorites tab:
At this point, we’ve integrated the playlist dashboard and when we click on a point in the Energy/Danceability by Song scatter plot, we get 2 options with the custom events we added earlier. However, we’re not doing anything with them yet.
Now that we’ve integrated the dashboard, we can tell our app to do stuff when it receives an event. The two charts that have ‘Add to Playlist’ and ‘Song Info’ events here are:
First, we need to set up our code to listen to incoming events. To do so, we need to use the Cumulio.onCustomEvent() function. Here, we chose to wrap this function in a listenToEvents() function that can be called when we load the Cumul.io Favorites tab. We then use if statements to check what event we’ve received:
This is the point after which things are up to your needs and creativity. For example, you could simply print a line out to your console, or design your own behaviour around the data you receive from the event. Or, you could also use some of the helper functions we’ve created that will display a playlist selector to add a song to a playlist, and integrate the Song Info dashboard. This is how we did it;
Here, we will make use of the addToPlaylistSelector() function in src/ui.js. This function expects a Song Name and ID, and will display a window with all the available playlists of the logged in user. It will then post a Spotify API request to add the song to the selected playlist. As the Spotify Web API requires the ID of a song to be able to add it, we’ve created a derived Name & ID field to be used in the scatter plot.
An example event we receive on ‘add_to_playlist’ will include the following for the scatter plot:
And these columns for the table:
We extract the Name and ID of the song from the event via the getSong() function, then call the ui.addToPlaylistSelector() function:
Now, the ‘Add to Playlist’ event will display a window with the available playlists that a logged in user can add the song to:
The final thing we want to do is to make the ‘Song Info’ event display another dashboard when clicked. It will display further information on the selected song, and include an option to play the song. For this step, we make use of Parameterizable Filters. The idea is to create a parameter on your dashboard, for which the value can be defined while creating an authorization token. We include the parameter as metadata while creating an authorization token.
For this step, we have created a songId parameter that is used in a filter on the Song Info dashboard:
Then, we create a getDashboardAuthorizationToken() function. This expects metadata which it then posts to the /authorization endpoint of our server in server/server.js:
Finally, we use the load the songInfo dashboard when the ‘song_info’ event is triggered. In order to do this, we create a new authorization token using the song ID:
We make some modifications to the loadDashbord() function so as to use the new token:
Then call the ui.displaySongInfo(). The final result looks as follows:
And voila! We are done! In this demo we used a lot of helper functions I haven’t gone through in detail, but you are free clone the demo repository and play around with them. You can even disregard them and build your own functionality around the custom events.
Before you start:
Then take the following steps:
The Playlist Generator App
Academy article on Custom Events
Webinar on Custom Events
Academy article on Parameterizable Filters
Quick Start for the Spotify Web API
Experience the power of Luzmo. Talk to our product experts for a guided demo or get your hands dirty with a free 10-day trial.
