Deprecated

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

react-cumulio-dashboard

This is a React library for embedding Cumul.io dashboards in your React application.

Table of contents

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

Installation instructions

npm i @cumul.io/react-cumulio-dashboard

Usage

import { CumulioDashboardComponent, CumulioDashboard } from '@cumul.io/react-cumulio-dashboard';
import { useRef } from 'react';
...
  function CumulioWrapper() {
    const ref = useRef<CumulioDashboard>(null);
    return (
      <div className="App">
        <button
          onClick={async (e) => console.log(await ref.current.exportDashboard())}
        >
          Export Dashboard
        </button>
        <CumulioDashboardComponent
          ref={ref}
          authKey="<!-- your generated authKey -->"
          authToken="<!-- your generated authToken -->"
          dashboardSlug="test"
          switchScreenModeOnResize={false}
          loaderSpinnerColor="rgb(0, 81, 126)"
          loaderSpinnerBackground="rgb(236 248 255)"
          itemsRendered={(e) => console.log('itemsRendered', e)}>
        </CumulioDashboardComponent>
      </div>
    );
  }
...

Properties

Below a list of available properties on the dashboard react 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>
// Promise that returns an array with the data of a item.
  
getFilters(): Promise<FilterGroup[]>
// Promise that returns an array of filters.

setAuthorization(key: string, token: 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?: ExportType): Promise<ExportDashboard>
// Exports the current dashboard as either pdf or png.

getAccessibleDashboards(): Promise<AccessibleDashboard[]>
// 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<SetEditMode>
// Sets the editMode of the current dashboard. Accepted parameters: view , editLimited , editFull .

Changelog

• Changelog

Migration

Migration from 3.x.x to 4.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
}

Migration from 2.x.x to 3.x.x

• No Changes

Migrating from 1.x.x to 2.x.x

• All methods that were called on dispatched to store shall now be called on component ref (Which can be obtained using useRef to obtain a ref).
• chartId is now called itemId, charts-rendered is now called items-rendered
• All events are now of the format { data: { ...eventData } }, eventData is of the format

{
  dashboardId?: string;
  dashboardSlug?: string;
  itemId?: string;
  language: string;
  name: string;
  screenMode: string;
  type: string;
  dimensions?: object; // populated depending on the event
  changed?: [];  // populated depending on the event
  filters?: [];  // populated depending on the event
  item?: string;    // populated depending on the event
  origin?: string;  // populated depending on the event
  object?: string;  // populated depending on the event
  data?: object;       // populated depending on the event
}

• getFilters now returns an array of filters. [...objectOfFilters], objectOfFilters is of the format

[{
  expression: string;
  parameters: [];
  properties: {
    id: string;
    ignore?: string[];
    origin: string;
    type: string;
    viz: string;
  }
}]

For more migrations click here.

Quick links

Cumul.io | Codesandbox example | Migrations | Changelog