react-cumulio-dashboard

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

Install

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

Usage

import { CumulioDashboardComponent } from '@cumul.io/react-cumulio-dashboard';
import { useRef } from 'react';
...
  function CumulioWrapper() {
    const ref = useRef(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

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 .
  

Migration

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;
  }
}]

Quick links

Cumul.io Codesandbox example