react-cumulio
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    React Component Library

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

    Install

    npm i react-cumulio

    OR

    yarn add react-cumulio

    Usage

    Add higher order context provider

    This library makes use of the React state and context functionality.

    More info about React context can be found here

    Therefore all components that want to access the cumulio data and use the external actions, need to be wrapped in this context. All children in the App component will now have access to Cumulio data.

    import React, { useReducer } from "react";
    import {
        CumulioContext,
        initialState,
        reducer
    } from "react-cumulio";
    
    const [state, dispatch] = useReducer(reducer, initialState);
    
    <CumulioContext.Provider value={{ state, dispatch }}>
        <App />
    </CumulioContext.Provider>

    Use component

    Render dashboard

    The component can now be used and the state can be accessed. Include the component by:

    <CumulioComponent
        dashboardId="dashboardId"
        language="en"
    />

    OR render a single chart

    <CumulioComponent
        dashboardId="dashboardId"
        chartId="chartId"
        language="en"
    />

    Available Inputs
    Below a list of available input options you can pass to the component. If you like, you can always take a look at the typescript definitions in the cumulio-model.ts file

    dashboardId: string;                // The id of the Cumul.io dashboard you wish to embed.
    chartId: string;                    // The id of the Cumul.io chart you wish to embed (Default: null)
    authKey: string;                    // Authorization key generated via Cumul.io API (Default: null)
    authToken: string;                  // Authorization token generated via Cumul.io API (Default: null)
    language: string;                   // Sets the language of errors and loader, eg. 'en' (Default: 'auto')
    screenmode: string;                 // Sets the screenmode of your dashboard: 'mobile', 'tablet', 'desktop', 'largeScreen', 'fixed' (Default: 'auto'). There is a ScreenMode enum available that can be used to simplify your code.
    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)')
    loaderLogoColor: string;            // Background color of the spinner (Default: 'orange')
    chartDimensions: Object;            // (optional) The desired dimensions of the single chart you want to embed; can be set when 'chartId' is set, chartDimensions : { width: 100, height: 200 }. (Default: { width: 'auto', height: 'auto' }) 

    Examples

    A dashboard with a gray loader background

    <CumulioComponent
        dashboardId="035c0304-0bfe-4b7c-8c10-a4acb8eb9d76"
        loaderBackground="rgb(238,243,246)"
    />

    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

    import {
        ScreenMode,
    } from "react-cumulio";
    
    <CumulioComponent
        dashboardId="55cfb99c-d602-492b-b192-6c15277fdb9a"
        loaderSpinnerColor="purple"
        screenMode={ScreenMode.MOBILE}
        switchScreenmodeOnResize={false}
    />

    Public methods that can be dispatched

    There are a few methods that can be dispatched using the React state. This actions will execute a specific method on cumul.io. You can use the useCumulio() hook provided by the package. This hook will give you access to:

    const { state, dispatch } = useCumulio();

    The dispatch method allows a action to be passed.

    const { state, dispatch } = useCumulio();
    
    dispatch(getDataAction(
        {
            chartId: "eb626f65-7c67-4cde-b365-d73c00bee0b7",
            dashboard: {
                dashboardId: "763177aa-9b93-4ae7-903e-3cb07dc593d8"
            }
        }
    ));

    Dispatch the action and the data will be available inside the state variable.

    The following state variables can be accessed.

    dashboards: CumulioDashboard[];   // Returns an array of all the visible dashboards on a page with their information
    filters: IDashboardFilters[];     // Returns an array of all visible dashboards with their active filters
    data: object[];                   // Array with processed chart data
    customEvent: any;                 // Returns the custom event information containing dashboard id, chart id and the event name & data

    Possible actions and their parameters:

    1. getDataAction

    Returns an array the data of a chart of a certain dashboard by adding the dashboardId or the container of the iframe.

    Properties that can be passed to the action.

    interface IGetDataPayload {
        chartId: string;
        dashboard?: {
            dashboardId?: string;
            container?: string;
        };
    }

    2. refreshDataAction

    Refreshes the data of a specific chart when the id of that chart is supplied. Without a chartId this refreshes the data in all charts.

    Properties that can be passed to the action.

    interface IRefreshDataPayload {
        id?: string;
    }

    3. setAuthorizationAction

    Changes the authorization of all or one dashboard and refreshes the data of those dashboards

    Properties that can be passed to the action.

    interface ISetAuthorizationPayload {
        authKey: string;
        authToken: string;
        dashboard?: {
            dashboardId?: string;
            container?: string;
        };
    }

    4. exportDashboardAction

    Exports the current dashboard as either pdf or png. A container class name needs to be passed as an argument and an optional format parameter.

    Properties that can be passed to the action.

    interface IExportDashboardPayload {
      container: string;
      format?: string;
    }

    5. reloadDashboardAction

    Reloads the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded without reloading the iFrame).

    5. getAccessibleDashboards

    dispatch(await getAccessibleDashboards({ dashboardId?: string, dashboardSlug?: string, apiHost?: string, authKey?: string, authToken?: string, container?: string }));
    // Get accessible dashboards in a integration, provide either dashboardId, dashboardSlug, container if a dashboard is already loaded.
    // Or provide authKey, apiHost and authToken
    
    // You will find integration inside state.integration

    Quick links

    Cumul.io | Stackblitz Example

    Install

    npm i react-cumulio

    DownloadsWeekly Downloads

    618

    Version

    1.0.5

    License

    none

    Unpacked Size

    1.05 MB

    Total Files

    43

    Last publish

    Collaborators

    • cumul.io_team