@hopara/react

This package provides a react component to add Hopara visualizations to your project.

Requirements

The Hopara component is built on top of React and React-Redux. It requires the following dependencies:

• react >= 18.2
• react-redux >= 8.0
• redux >= 4.2

Installing

Package manager

Using npm:

$ npm install --save @hopara/react

Using yarn:

$ yarn add @hopara/react

Once installed, you can import the library using import or require:

import {Hopara} from '@hopara/react';

Authentication

The component requires a valid accessToken. Use the Auth API to fetch it, as explained in our [integration guide]integration guide

Examples

Basic usage

<div className="HoparaEmbedded">
  <Hopara
    visualizationId="your-visualization-id"
    accessToken="your-access-token"
  />
</div>

Module API

You can further customize the integration by using the component props:

type HoparaProps = {
  // The visualization id
  visualizationId: string

  // Short-lived token provided by Auth API used for authentication in API calls
  accessToken: string

  // Long-lived token used to obtain a new accessToken when the current one expires.
  refreshToken: string | undefined

  // Switch the theme mode to dark scheme (default: false)
  darkMode: boolean | undefined

  // Overwrites data at rendering time
  dataLoaders: DataLoader[] | undefined

  // The initial row (e.g. asset) to load the visualization
  initialRow: InitialRow | undefined

  // The custom controller to be used on Hopara Visualization
  controller: HoparaController | undefined

  // The filters to be added on data fetches
  filters: Filter[] | undefined

  // Functions called when callback actions are triggered
  callbacks: CallbackFunction[]
}

Controller

You can provide a Hopara Controller to manually trigger a data refresh (i.e. fetch all data again).

Example

import {Hopara, HoparaController} from '@hopara/react'
const customController = new HoparaController()

<div className="HoparaEmbedded">
  <Hopara
    visualizationId="your-visualization-id"
    accessToken="your-access-token"
    controller={customController}
  />
</div>

Data Loader

By default Hopara will load the same visualization and data as seen as in hopara.app. You can use the data loader prop to provide a custom way to load the data.

type DataLoader = {
  // query name
  query: string

  // data source name
  source: string

  // callback to be used on data load
  loader: (filterSet: {limit: number, offset:number, filters: any[]}) => Promise<Record<string, any>[]>
}

Example

const dataLoaders = [{
  query: 'queryName',
  source: 'dataSourceName',
  loader: async () => {
    return [
      {
        id: 1,
        name: 'Eiffel Tower',
        country: 'France',
        longitude: 48.85845461500544,
        latitude: 2.294467845588995
      },
      {
        id: 2,
        name: 'Liberty Statue',
        country: 'USA',
        longitude: 40.68815550804761,
        latitude: -74.02620077137483
      },
      {
        id: 3,
        name: 'Great Wall of China',
        country: 'China',
        longitude: 40.43211592595951,
        latitude: 116.57040708445938,
      }
    ]
  }
}]
...
<div className="HoparaEmbedded">
  <Hopara
    visualizationId="your-visualization-id"
    accessToken="your-access-token"
    dataLoaders={dataLoaders}
  />

Initial Row

The initial row prop centers the visualization around a specific row (e.g. asset, facility).

type InitialRow = {
  layerId: string
  rowId: string
}

Filter

When adding a filter, the field name is handled as a dimension in Hopara.

Hopara.init({
  visualizationId: 'my-hopara-viz',
  accessToken: 'my-hopara-token',
  targetElementId: 'my-target-element',
  filters: [
    {
      field: 'type',
      values: ['REFRIGERATOR', 'FREEZER'],
    }
  ],
})

Callback Function

You can implement custom interactions by adding callback actions to a layer. When the user selects an object in the visualization and click on the action the registered javascript function will be called with the associated row data.

type CallbackFunction = {
  name: string
  callback: (row) => void
}

Hopara.init({
  visualizationId: 'my-hopara-viz',
  accessToken: 'my-hopara-token',
  targetElementId: 'my-target-element',
  callbacks: [
    {
      name: 'my-callback-action',
      callback: (row) => {
        console.log('Callback triggered', row)
      }
    }
  ],
})