@cumul.io/cumulio-dashboard

A modern Web Component for Cumul.io dashboards in your web application.

Usage no npm install needed!

<script type="module">
  import cumulIoCumulioDashboard from 'https://cdn.skypack.dev/@cumul.io/cumulio-dashboard';
</script>

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 changed
  • customEvent: dispatched on custom event triggered from the dashboard
  • itemsRendered: dispatched when all items are rendered in a dashboard
  • exported: 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 dashboard
  • refreshData(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);
});

Quick links

Cumul.io | Demo - Sample Integration | Codesandbox example