React native component for Luzmo.

This is a React native library for embedding Luzmo dashboards in your React native application.

Table of contents

1. Installation instructions
2. Luzmo viz item
3. Luzmo Dashboard
4. Changelog
5. Migration
6. Quick links

Installation instructions

npm i @luzmo/react-native-embed

Luzmo viz item

For a more comprehensive documentation visit Flex SDK Docs - Luzmo Developer Docs

Usage

import { LuzmoVizItemComponent } from '@luzmo/react-embed';
import { useRef } from 'react';
...
  function LuzmoWrapper() {
    const ref = useRef<any>(null);
    return (
      <div className="App">
        <button
          onClick={(e) => console.log(ref.current.export())}
        >
          Export Dashboard
        </button>
        <LuzmoVizItemComponent
          ref={ref}
          authKey="<!-- your generated authKey -->"
          authToken="<!-- your generated authToken -->"
          type="bar-chart"
          load={(e) => console.log('load', e)}
        </LuzmoVizItemComponent>
      </div>
    );
  }
...

Properties: LuzmoVizItemComponent

Below a list of available properties on the viz item web component

| Property | Type | Description | |----------------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | type | string | The type of viz item to embed. | | options | object | The options object to be passed on to viz item | | slots | array | The slots array to specify which columns to use to fetch data. depends on the type of chart. | | contextId | string | contextId is a unique id that can be assigned to viz item which will be used in filtering with canFilter. | | authKey | string | Authorization key generated via Luzmo API | | authToken | string | Authorization token generated via Luzmo API | | canFilter | string | array | canFilter can be either set to all or an array of contextId's. | | filters | object | filters object is used to set initial filters. | | appServer | string | Tenancy of luzmo.com to connect to (Default: 'https://app.luzmo.com/' for US set appServer to 'https://app.us.luzmo.com/') | | apiHost | string | API server to connect to (Default: 'https://api.luzmo.com/' , for US set apiHost to 'https://api.us.luzmo.com/') |

Events LuzmoVizItemComponent

| Name | Description | |----------------|----------------------------------------| | changedFilters | Emitted when filters are changed | | customEvent | Emitted when a custom event is fired | | exported | Emitted when export completes or fails | | rendered | Emitted when the item is rendered | | load | Emitted when viz item is loaded |

Public methods LuzmoVizItemComponent

getData(): Promise<any>
// Return a Promise of an array of the data of the viz item that's embedded.

getFilters(): Promise<FilterGroup[]>;
// Return a Promise of an array of active filters on the viz item.

refreshData(): Promise<void>
// Refresh the data of the viz item.

setAuthorization(key: string, token: string): Promise<void>
// Changes the authorization of the viz item. To fetch data based on new authorization parameters, refreshData() needs to be called.

export(): Promise<void>
// Export the viz item as png.

Luzmo Dashboard

Usage

import { LuzmoDashboardComponent, LuzmoDashboard } from '@luzmo/react-native-embed';
import { useRef } from 'react';
import { Button } from 'react-native';
...
  function LuzmoWrapper() {
    const ref = useRef<LuzmoDashboard>(null);
    return (
      <div className="App">
        <Button
          title='Get Filters'
          onPress={async (e) => console.log(await ref.current.getFilters())}
        >
          Get Filters
        </Button>
        <LuzmoDashboardComponent
          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)}>
        </LuzmoDashboardComponent>
      </div>
    );
  }
...

Properties

Below a list of available properties on the dashboard react native component

| Property | Type | Description | | -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dashboardId | string | The id of the Luzmo dashboard you wish to embed | | dashboardSlug | string | The slug of the Luzmo dashboard you wish to embed (if a dashboardId is supplied that one will be used) | | itemId | string | The id of the Luzmo item you wish to embed. The dashboardId should be provided as well if you what to embed just a Luzmo item. | | itemDimensions | { width: number/string; height: number/string; } | width and height of item only applies when itemId is provided. | | authKey | string | Authorization key generated via Luzmo API | | authToken | string | Authorization token generated via Luzmo API | | language | string | The language of the dashboard: eg. 'en' (Default: 'auto') | | screenMode | string | The screen mode 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 Luzmo to connect to (Default: 'https://app.luzmo.com/' for US set appServer to 'https://app.us.luzmo.com/') | | 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.luzmo.com/' for US set apiHost to 'https://api.us.luzmo.com/') | | 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

| Name | Description | Event Arguments | | -------------- | ------------------------------------ | --------------------- | | changedFilters | Emitted when filters are changed | ChangedFiltersEvent | | customEvent | Emitted when a custom event is fired | CustomEvent | | itemsRendered | Emitted when all items are rendered | ItemsRenderedEvent | | load | Emitted when dashboard is loaded | LoadEvent |

Public methods

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>
// Changes the authorization of all or one dashboard. To fetch data based on new authorization parameters, reloadDashboard() or refreshData() needs to be called.

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)

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.

Changelog

• Changelog

Migration

Migrating from cumul.io to luzmo.

• Change import '@cumul.io/react-native-cumulio-dashboard to import @luzmo/react-native-embed.
• Replace all references of cumulio-dashboard to luzmo-dashboard
• Replace CumulioDashboardComponent to LuzmoDashboardComponent.
• Replace CumulioDashboard to LuzmoDashboard.

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
}

Migrating 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 a promise that resolves to 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

Luzmo | Changelog | Migration