@hopara/iframe 0.2.2 → 0.2.4

package/README.md

@@ -1,15 +1,12 @@
 # Hopara Iframe Client
-The Hopara Iframe Client enables you to embed an Hopara App on your web site.
+This package provides an iframe to add [Hopara](https://hopara.io) visualizations to your project.
 
 # Installing
-Using npm:
-```shell
-$ npm install @hopara/iframe
-```
+You can install it as a NPM module or using Hopara CDN directly:
 
-Using yarn:
+As a module:
 ```shell
-$ yarn add @hopara/iframe
+$ npm install @hopara/iframe
 ```
 
 Using Hopara CDN:
@@ -17,8 +14,11 @@ Using 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](https://docs.hopara.app/docs/integration-guide/authentication-integration.html)
+
 # Example
-### React
+### Node.JS
 ```js
 import React from 'react'
 import Hopara from 'hopara'
@@ -73,10 +73,10 @@ Hopara.init(config)
   // The app id
   app: string
 
-  // The accessToken fetched from the auth API
+  // The accessToken provided by auth API
   accessToken: string
 
-  // Overwrites the data at render time
+  // Overwrites data at rendering time
   dataLoaders: DataLoader[] | undefined
 
   // Provides a custom ways to update data
@@ -89,4 +89,123 @@ Hopara.init(config)
   initialRow: InitialRow | undefined
 }
 ```
-for more information about the initialization props go to our [@hopara/react](https://www.npmjs.com/package/@hopara/react) module
+
+### 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.
+
+```typescript
+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
+
+```javascript
+const customDataLoaders = [{
+  name: 'queryName',
+  source: 'dataSourceName',
+  loader: () => {
+    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({
+  app: 'my-hopara-app',
+  accessToken: 'my-hopara-token',
+  targetElementId: 'my-target-element',
+  dataLoaders: customDataLoaders,
+})
+```
+
+### Data Updater
+By default Hopara will update the visualization in the same database configured in hopara.app. You can use the data updater prop to provide a custom way to update the data.
+
+The data updater is called when placing objetcs in a visualization and when resizing images.
+
+```typescript
+type DataUpdater = {
+  // query name
+  name: string
+
+  // data source name
+  source: string
+
+  // callback to be used on data update
+  updater: (updatedRow: Record<string, any>, originalRow: Record<string, any>, diff: Partial<Record<string, any>>) => Promise<void>
+}
+```
+
+```jsx
+const customDataUpdaters = [{
+  name: 'queryName',
+  source: 'dataSourceName',
+  updater: (newRow) => {
+    const rowIndex = dataInMemory.findIndex((row) => row.id === newRow.id)
+    dataInMemory[rowIndex] = newRow
+  }
+}]
+
+
+Hopara.init({
+  app: 'my-hopara-app',
+  accessToken: 'my-hopara-token',
+  targetElementId: 'my-target-element',
+  dataUpdaters: customDataUpdaters,
+})
+```
+
+### Initial Position
+The initial position prop overrides the initial position of the visualization.
+
+```typescript
+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).
+
+```typescript
+type InitialRow = {
+  entityId: string
+  rowId: string
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopara/iframe",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "main": "build/client.js",
   "scripts": {
     "start": "ESLINT_NO_DEV_ERRORS=true react-app-rewired start",
@@ -27,8 +27,8 @@
   ],
   "devDependencies": {
     "@babel/register": "^7.15.3",
-    "@hopara/react": "^0.2.2",
-    "@hopara/system-test": "^0.2.2",
+    "@hopara/react": "^0.2.4",
+    "@hopara/system-test": "^0.2.4",
     "babel-loader": "8.1.0",
     "customize-cra": "^1.0.0",
     "react": "^18.2.0",

package/tests/spec/view.system.test.js

@@ -19,16 +19,35 @@ module.exports = {
     browser.setWindowSize(1280, 800)
       .url('http://localhost:3456/')
       .execute(() => {
-      window.postMessage({
-        app: 'circle',
-        tenant: 'hopara.io',
-        accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJ0ZW5hbnRzIjpbImhvcGFyYS5pbyJdLCJzY29wZSI6InJvdzp3cml0ZSJ9.qJwSd1EUmiVX5NrgelVQdn9MDbdVNq4GGjzHPQlDQ1A',
-        targetElementId: 'embedded-target-element',
-        __hopara__eventType__: 'init'
-      }, '*')
+        window.postMessage({
+          app: 'circle',
+          tenant: 'hopara.io',
+          accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJ0ZW5hbnRzIjpbImhvcGFyYS5pbyJdLCJzY29wZSI6InJvdzp3cml0ZSJ9.qJwSd1EUmiVX5NrgelVQdn9MDbdVNq4GGjzHPQlDQ1A',
+          targetElementId: 'embedded-target-element',
+          __hopara__eventType__: 'init'
+        }, '*')
       })
       .pause(waitTime())
       .waitForElementVisible('#deckgl-overlay')
       .assert.compareScreenshot('circle-layer.png', mismatchPercentage)
   },
+  'Circle Layer With Entites': (browser) => {
+    mockServer.get('/app/circle').thenReply(200, JSON.stringify(responses.app.circleWithEntities))
+    mockServer.get('/view/queryName/row').thenReply(200, JSON.stringify(responses.geo.circle))
+
+    browser.setWindowSize(1280, 800)
+      .url('http://localhost:3456/')
+      .execute(() => {
+        window.postMessage({
+          app: 'circle',
+          tenant: 'hopara.io',
+          accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJ0ZW5hbnRzIjpbImhvcGFyYS5pbyJdLCJzY29wZSI6InJvdzp3cml0ZSJ9.qJwSd1EUmiVX5NrgelVQdn9MDbdVNq4GGjzHPQlDQ1A',
+          targetElementId: 'embedded-target-element',
+          __hopara__eventType__: 'init'
+        }, '*')
+      })
+      .pause(waitTime())
+      .waitForElementVisible('#deckgl-overlay')
+      .assert.compareScreenshot('circle-layer-with-entities.png', mismatchPercentage)
+  },
 }