Embedding a dashboard in your website with cumulio.min.js
Dashboard id and script import
First, you need to have the ID of the dashboard you want to embed. This ID can be found in the URL of that dashboard in Luzmo, see screenshot below. Copy and paste this ID in the script.
Secondly, add the container element (the div element in the example). Give it an id and so you can refer to it in the script (with the # sign for the selector on id), as shown in the example below: the id of the example container element is dashboard-container, but of course you can use another id.
<div id="dashboard-container"></div>
You can statically load the latest version of the cumulio.min.js library by adding its reference in the html header as follows:
<head>
<script src="https://cdn-a.cumul.io/js/cumulio.min.js"></script>
</head>
Or you can dynamically load cumulio.min.js by adding the following script:
<script type="text/javascript">;
(function(d, a, s, h, b, oa, rd) {
d[b] = d[b] || {}; d[b].addDashboard = function(v) { (d[b].list = d[b].list ||
[]).push(v) }, oa = a.createElement(s), oa.async = 1; oa.src = h;
rd = a.getElementsByTagName(s)[0]; rd.parentNode.insertBefore(oa, rd);
})(window, document, 'script', 'https://cdn-a.cumul.io/js/cumulio.min.js','Cumulio');
</script>
addDashboard
Now is the time to add your dashboard by calling Cumulio's addDashboard function: don't forget to adapt the dashboard Id & the container selector, and add the temporary authorization key and token that was generated in your backend!
It’s good to know that the dashboard will resize automatically to the size(s) of the website it's embedded in: it will take the size of its container.
Cumulio.addDashboard({
dashboardId:'1e991b87-a143-474f-bb5d-3bfe6df69b48',
container:'#dashboard-container',
key:'< The temporary authorization key from the backend >',
token:'< The temporary authorization token from the backend >'
});
You can find a list of all optional parameters for the addDashboard function below:
| Parameter | Description |
|---|---|
| dashboardId | The id of the dashboard that you want to embed. |
| container | The DOM selector of the container in which the dashboard will be embedded e.g. #my-dashboard. The width available for the container will be used to identify which screenmode will be loaded (if screenmode is not set). The DOM element needs to be available in the body when calling the addDashboard function, otherwise the dashboard will be added to the body of the page. You can only have one dashboard per container. |
| key | (optional) The authorization id used for integrating the dashboard. Use this when securely integrating dashboards. Public dashboards (& datasets used) can be embedded without authorization key. To learn how to generate tokens, refer to the Authorization resource in the Core API Authorization. Never use your API key here! |
| token | (optional) The authorization token used for integrating the dashboard. Use this when securely integrating dashboards. Public dashboards (& datasets used) can be embedded without authorization key. Never use your API token here! |
| screenmode | (optional) fixed, mobile, tablet, desktop, largeScreen or auto. The default is auto. If the screenmode is set and available, that screenmode will be used. This also means that the dashboard will not auto-resize or switch to other screenmodes if the size of the container changes. |
| language | (optional) The language of your dashboard that you wish to use. This language needs to be defined in the dashboard, if not it will be ignored. |
| timezoneId | (optional) The timezone you you wish to use in your dashboard. This timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York. |
| chartId | (optional) The id of the chart that you want to embed. Use it when you just want to embed a single chart from your dashboard. |
| chartDimensions |
(optional) The desired dimensions of the single chart that you want to embed. By default it uses the dimensions of the chart in the dashboard.
For this parameter it is required to specify a chartId. Specified as an object with the width and height properties, e.g. { width: '800px', height: '400'px' }
width: The width in pixels, e.g. 600px or auto. When auto is used, the chart will take up the available width or the container and resize when the container resizes.
height: The height in pixels, e.g. 400px. When auto is used, the chart height will be sized according to the current screenmode of the dashboard, which is determined by the current width of the container.
|
| loader |
(optional) These parameters style the container while loading the dashboard. Specified as an object (e.g. { background: 'rgb(41, 41, 41)', spinnerColor: 'rgb(118, 166, 0)' } with the following properties:
background: (optional) The background color (hex, rgb or rgba) of the container while loading the dashboard.
fontColor: (optional) The font color (hex, rgb or rgba) of the messages while loading the dashboard.
spinnerColor: (optional) The color (hex, rgb or rgba) of the spinner while loading the dashboard.
spinnerBackground: (optional) The background (hex, rgb or rgba) of the spinner while loading the dashboard.
|
removeDashboard
You can also remove a dashboard again from a container, using the removeDashboard function:
Cumulio.removeDashboard({
container: '< DOM selector of the container >'
});
setAuthorization
The setAuthorization function allows you to change the authorization token in a dashboard. This can be useful for example if you want to change the value of one of the parameters used in the dashboard. After using setAuthorization you will always want to do either a reloadDashboard if you changed any initialization filters in the authorization token or refreshData if all you changed was a parameter or some metadata.
Cumulio.setAuthorization(
'<authorization key>',
'<authorization token>',
{
dashboardId: '<dashboard id>',
container: '<DOM selector of the dashboard container>'
}
);
reloadDashboard
The reloadDashboard function is used to reload an integrated dashboard without reloading the whole integrated frame. This is useful when the temporary authorization has changed and the dashboard needs to be reloaded with the new rights.
Cumulio.reloadDashboard();
refreshData
The refreshData function is used to refresh the data of a specific chart when the id of that chart is supplied. Without a chartId this refreshes the data in all charts.
Cumulio.refreshData(id);
getFilters
The getFilters function is used to get all visible dashboard with their active filters. It can be useful when using bi-direction communication with an integrated dashboard.
// Returns the active filters for all dashboards on the page
Cumulio.getFilters();
// Returns the active filters for the specified dashboard,
// and an empty array if the dashboard cannot be found.
Cumulio.getFilters('<dashboard id>');
getData
The getData function is used to get the data of a chart of a certain dashboard by providing the dashboardId or the container selector of the integrated frame. This function will return a Promise that resolves to the requested data.
Cumulio.getData(chartId, {
dashboardId: '< uuid of the dashboard >',
container: '< DOM selector of the container >'
}).then((data) => {
console.log('Data from chart: ', data);
});
exportDashboard
The exportDashboard function is used to download a snapshot of the dashboard in either PNG or PDF format.
Cumulio.exportDashboard(
{
container: ' < DOM selector of the container > '
},
'< format_of_export >'
);
Custom Events
Refer to the Developer Documentation or this Academy article for more information on why and how to set Custom Events in your dashboard.
When using cumulio.min.js, you can listen to Custom Events in the following way:
// If you give your function a name, you can remove the listener easily again later on.
Cumulio.onCustomEvent((e) => {
// Do something with the event here.
console.log(e);
// For example you can choose what action to perform
// depending on the custom event that is triggered:
switch(e.data.event) {
case '<myCustomEventName>':
// Do something
break;
case '<mySecondCustomEventName>':
// Do something else
break;
default:
// Always do this
}
});
You can remove the event listeners that you added via Cumulio.onCustomEvent by using the aptly named Cumulio.offCustomEvent function:
// When I create an event listener, I have to assign it a name first.
function myFunction(e) {
// Do something
}
// I can then add this function as an event listener.
Cumulio.onCustomEvent(myFunction);
// When I want to remove the event later on, I use the offCustomEvent function,
// passing it the same function we created earlier on.
Cumulio.offCustomEvent(myFunction);
// Alternatively if I don't supply any arguments to the function,
// all defined event listeners will be removed.
Cumulio.offCustomEvent();