@hopara/iframe
v0.4.1
Published
This package provides an iframe to add [Hopara](https://hopara.io) visualizations to your project.
Downloads
1,972
Readme
Hopara Iframe Client
This package provides an iframe to add Hopara visualizations to your project.
Installing
You can install the iframe as a NPM module or using the Hopara CDN directly:
As a module:
$ npm install @hopara/iframeUsing Hopara CDN:
<script src="https://statics.hopara.app/embedded/latest/client.js"></script>Authentication
The iframe requires a valid accessToken. Use the Auth API to fetch it, as explained in our integration guide
Example
Node.JS
import React from 'react'
import Hopara from 'hopara'
class MyComponent extends React.Component {
componentDidMount(): void {
const hopara = Hopara.init({
visualizationId: 'my-hopara-viz',
accessToken: 'my-hopara-token',
targetElementId: 'my-target-element',
})
}
render() {
<div id="my-target-element" />
}
}HTML
<html>
<head>
...
<script src="https://statics.hopara.app/embedded/latest/client.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function(){
const hopara = Hopara.init({
visualizationId: 'my-hopara-viz',
accessToken: 'my-hopara-token',
targetElementId: 'my-target-element',
})
});
</script>
</head>
<body>
<div id="my-target-element"></div>
</body>
</html>API
Init
The init command starts the Hopara Visualization and returns a hopara instance that can be used to further interactions
const hopara = Hopara.init(config)Update
Use the update command to update any config passed previously in the init command.
...
const hopara = Hopara.init(config)
hopara.update({accessToken: 'newAccessToken'})
...Hopara Instance
{
// When triggered Hopara Visualization will reload every data source on the view
reload: () => void
}Hopara Config
{
// The vizualization
visualizationId: string
// The accessToken provided by auth API
accessToken: string
// Switch the theme mode to dark scheme (default: false)
darkMode: boolean | undefined
// Sets if the toolbar should be rendered (default: true)
toolbar: boolean | undefined
// Overwrites data at rendering time
dataLoaders: DataLoader[] | undefined
// The initial position to load the visualization
initialPosition: InitialPosition | undefined
// The initial row (e.g. asset) to load the visualization
initialRow: InitialRow | undefined
// Overrides the map style defined in the visualization studio. See the Map Style section for the available options
mapStyle: string | undefined
// Functions called when callback actions are triggered
callbacks: CallbackFunction[]
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
name: 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 customDataLoaders = [{
name: '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,
}
]
}
}]
Hopara.init({
visualizationId: 'my-hopara-viz',
accessToken: 'my-hopara-token',
targetElementId: 'my-target-element',
dataLoaders: customDataLoaders,
})Initial Position
The initial position prop overrides the initial position of the visualization.
type InitialPosition = {
latitude: number | undefined
longitude: number | undefined
x: number | undefined
y: number | undefined
z: number | undefined
zoom: number | undefined
bearing: number | undefined
}Initial Row
The initial row prop centers the visualization around a specific row (e.g. asset, facility).
type InitialRow = {
entityId: string
rowId: string
}Manual refresh
You can manually trigger a data refresh by calling the refresh method. This will result in all data loaders being called again.
const hopara = Hopara.init({
visualizationId: 'my-hopara-viz',
accessToken: 'my-hopara-token',
targetElementId: 'my-target-element',
})
// force data refresh every 3 seconds
setInterval(() => {
if (!hopara) return
hopara.refresh()
}, 3000)Map Style
In a geo visualization this config overrides the map style defined in the visualization studio.
The available options are 'none', 'building', 'dark', 'light', 'light-street', 'navigation', 'satellite'.
Hopara.init({
visualizationId: 'my-hopara-viz',
accessToken: 'my-hopara-token',
targetElementId: 'my-target-element',
mapStyle: 'building',
})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)
}
}
],
})