README
Web Component for Cumul.io Dashboards
A modern Web Component for Cumul.io dashboards in your web application.
Install
1. Install the component from npm
npm i @cumul.io/cumulio-dashboard
2. Import the component
In a JavaScript module:
import '@cumul.io/cumulio-dashboard';
OR In an HTML page:
<script type="module">
import './node_modules/@cumul.io/cumulio-dashboard/cumulio-dashboard.esm.js';
</script>
OR
<script
type="module"
src="./node_modules/@cumul.io/cumulio-dashboard/cumulio-dashboard.esm.js"
></script>
Usage
Use the dashboard components as if they were native HTML tags. Use the id of the dashboard you wish to embed. In your HTML template.
<cumulio-dashboard
dashboardId="55cfb99c-d602-492b-b192-6c15277fdb9a"
language="en"
>
</cumulio-dashboard>
OR
<!-- Embed a item by passing the item id as well -->
<cumulio-dashboard
dashboardId="55cfb99c-d602-492b-b192-6c15277fdb9a"
itemId="59fe5bd7-5070-42f5-98f4-da7f931e316c"
>
</cumulio-dashboard>
Properties:
Below a list of available properties on the dashboard web component
Property | Type | Description |
---|---|---|
dashboardId |
String | The id of the Cumul.io dashboard you wish to embed |
dashboardSlug |
String | The slug of the Cumul.io dashboard you wish to embed (if a dashboardId is supplied that one will be used) |
itemId |
String | The id of the Cumul.io item you wish to embed |
authKey |
String | Authorization key generated via Cumul.io API |
authToken |
String | Authorization token generated via Cumul.io API |
language |
String | The language of the dashboard: eg. 'en' (Default: 'auto') |
screenMode |
String | the screenmode of your dashboard: 'mobile', 'tablet', 'desktop', 'largeScreen', 'fixed' or 'auto' (Default: 'auto') |
switchScreenModeOnResize |
Boolean | true: the embedded dashboard can switch screenModes on resize of the container , false: Dashboard will keep the same screenMode (Default: true) |
loaderBackground |
String | Background color of the loader element (Default: '#f9f9f9') |
loaderFontColor |
String | Font color of the text of the loaders (Default: '#5a5a5a') |
loaderSpinnerColor |
String | Spinner color of the loader (Default: 'rgba(255, 165, 0, 0.7)') |
loaderSpinnerBackground |
String | Background color of the spinner (Default: 'rgba(169, 169, 169, 0.14)') |
appServer |
String | Tenancy of cumul.io to connect to (Default: 'https://app.cumul.io/') |
timezoneId |
String | 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. |
apiHost |
String | API server to connect to (Default: 'https://api.cumul.io/') |
editMode |
String | Specifies if the embedded dashboard should be editable or not. Accepted values: "view" , "editLimited" , "editFull" . Use "view" if you don't want the embedded dashboard to be editable. (Default: "view" ) |
mainColor |
String | Optional override of the main color used in the whitelabeling of the embedded dashboard editor. If not provided, the main color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values (i.e. "rgb(50,50,50)"). |
accentColor |
String | Optional override of the accent color used in the whitelabeling of the embedded dashboard editor. If not provided, the accent color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values (i.e. "rgb(50,50,50)"). |
Events:
load
: dispatched on load event of a dashboard.changedFilters
: dispatched when the filters of a dashboard are changedcustomEvent
: dispatched on custom event triggered from the dashboarditemsRendered
: dispatched when all items are rendered in a dashboardexported
: dispatched after export completes or fails.
Methods:
getData(itemId: string): Promise<object[]>
: Promise that returns an array with the data of a item.getFilters(): Promise<object[]>
: Promise that returns an array of filters.setAuthorization(authKey: string, authToken: string): Promise<void>
: Sets a new pair of authKey & authToken for the dashboardrefreshData(itemId?: string): Promise<void>
: Refreshes the data of a specific item/chart when the id of that item is supplied. Without a itemId this refreshes the data in all items.reloadDashboard(): Promise<void>
: Reloads the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded)exportDashboard(type?: 'png' | 'pdf'): Promise<void>
: Exports the current dashboard as either pdf or png.getAccessibleDashboards(): Promise<object[]>
: Retrieves a list of all dashboards an integration has access to. authKey and authToken needs to be set for this function to work.setEditMode(editMode: string): Promise<void>
: Sets the editMode of the current dashboard. Accepted parameters: view , editLimited , editFull .
Examples
A dashboard with a gray loader background
<cumulio-dashboard
dashboardId="035c0304-0bfe-4b7c-8c10-a4acb8eb9d76"
loaderBackground="rgb(238,243,246)"
>
</cumulio-dashboard>
A secured dashboard using an authorization key & token
<cumulio-dashboard
dashboardId="035c0304-0bfe-4b7c-8c10-a4acb8eb9d76"
authKey="<!-- your generated authKey-->"
authToken="<!-- your generated authToken -->"
>
</cumulio-dashboard>
A dashboard with a purple spinner color of the loader with screenmode mobile and switchScreenModeOnResize on false, so that the dashboard will stay in mobile mode
<cumulio-dashboard
id="dashboard"
dashboardId="55cfb99c-d602-492b-b192-6c15277fdb9a"
loaderSpinnerColor="purple"
screenMode="mobile"
switchScreenModeOnResize="false"
>
</cumulio-dashboard>
Add an event listener when all items are rendered
// get the component, here we query the component that has an id 'dashboard'
const dashboardComponent = document.getElementById('dashboard');
dashboardComponent.addEventListener('itemsRendered', (event) => {
// do something after all items are rendered
console.log(event);
});
Get data from an item
dashboardComponent
.getData('59fe5bd7-5070-42f5-98f4-da7f931e316c')
.then((data) => {
// do something with the item data
console.log('Item data', data);
});
Get filters used in the dashboard
dashboardComponent.getFilters().then((data) => {
// do something with the item data
console.log('Item data', data);
});
Export the dashboard
dashboardComponent.exportDashboard('png').then((data) => {
// do something with the item data
console.log('Item data', data);
});
Get accessible dashboards of an integration
dashboardComponent.getAccessibleDashboards().then((dashboards) => {
// do something with the dashboards
console.log('Accessible dashboards', dashboards);
});