@cumul.io/cumulio-dashboard v4.0.1

Deprecated

This package has been deprecated in favor of @luzmo/embed

Web Component for Cumul.io Dashboards

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

Table of contents

1. Installation instructions
2. Usage
3. Events
4. Public Methods
5. Examples
6. Changelog
7. Migration
8. Quick links

Installation instructions

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/index.js';
</script>

OR

<script
  type="module"
  src="./node_modules/@cumul.io/cumulio-dashboard/index.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

Events

Public methods

getDashboards(): Promise<CumulioDashboard[]>
// Returns an instantly resolved promise with an array of all the visible dashboards on a page with their information.

getData(itemId: string): Promise<ItemData>
// Returns an array the data of a chart of a certain dashboard by adding the dashboardId or the container of the iframe.

getFilters(): Promise<FilterGroup[]>
// Returns an array of active filters.

setAuthorization(key: string, token: string): Promise<void>
// Changes the authorization of all or one dashboard and refreshes the data of those dashboards.

refreshData(itemId?: string): Promise<void>
// Refreshes the data of a specific chart when the id of that item is supplied. Without a itemId this refreshes the data in all items.

reloadDashboard(): Promise<void>
// Reload the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded without reloading the iFrame)

exportDashboard(type?: ExportType): Promise<ExportDashboard>
// Exports the current dashboard as either pdf or png. A container class needs to be passed as an argument and an optional type parameter.

getAccessibleDashboards(): Promise<AccessibleDashboard[]>
// Get accessible dashboards in a integration, make sure 'apiHost', 'authKey', 'authToken' are set correctly on the instance.  

setEditMode(editMode: DashboardEditMode): Promise<SetEditMode>
// 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=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);
});

Changelog

• Changelog

Migration

From 3.x.x to 4.x.x

• cumulio-dashboard.umd.js is removed from the package.
• ESM file is renamed to index.js (older: cumulio-dashboard.esm.js) and CommonJS file is now called index.cjs

From 2.x.x to 3.x.x

• Filters are represented as a FilterGroup array instead of a Filter array. FilterGroup is an object containing the list of filters and AND/OR condition describing their relation. FilterGroup also can have child groups to support complex filtering logic

// FilterGroup 
{
  id: string;
  condition: 'and' | 'or';
  filters: Filter[]; 
  subGroups: FilterGroup[];
  origin: string;
  datasetId?: string; // dataset id in case of dahsboard level filters
  itemId?: string; // chart id in case of chart level filters
}

// Filter
{
  expression: string;
  parameters: [];
  properties: {
    id: string;
    origin: string;
    type: string;
    itemId: string;
    ignore?: string[];
  }
}

• getFilters() method response and changedFilters event data now contain filters as an array of FilterGroup objects instead of Filter objects

getFilters(): Promise<FilterGroup[]>

// changedFilters event data
{
  changed: FilterGroup[]; // changed filters
  filters: FilterGroup[]; // all filters
  // ... other event properties
}

From 1.x.x to 2.x.x

• No Changes.

For more migrations click here.

Quick links

Cumul.io | Demo - Sample Integration | Codesandbox example | Changelog | Migrations