v7.1

Integrate Dashboard Lite Viewer Component

This article describes the steps to embed a dashboard lite viewer component into your web application using div and the Dashboard Lite Viewer API.

Methods to Integrate Lite Viewer Component

There are three ways in which you can integrate the dashboard lite viewer component.

Method 1- Integrate the entire dashboard

ins.initialize({ container: viewerRoot, }).then((uiDashboard) => {
   const dashboardDom = document.querySelector('#dashboard-root');
   uiDashboard.connect(dashboardDom); // mount the dashboard onto this dom
   // listen to the event if you needed
   uiDashboard.on('render', () => {
       console.log('>>>', uiDashboard.name, 'uiDashboard render start');
   });
   uiDashboard.on('rendered', () => {
       console.log('>>>', uiDashboard.name, 'uiDashboard render end');
   });
   uiDashboard.on('mounted', () => {
       console.log('>>>', uiDashboard.name, 'uiDashboard mounted');
   });
   // trigger dashboard render
   uiDashboard.refresh();
});

Method 2- Integrate a single dashboard page

ins.initialize({ container: viewerRoot, }).then((uiDashboard) => {
   const firstPage = uiDashboard.pages[0]; // UIPage
   const pageDom = document.querySelector('#page-1');
   firstPage.connect(pageDom);
   firstPage.on('render', () => {
       console.log('>>>', firstPage.name, 'page render start')
   });
   firstPage.on('rendered', () => {
       console.log('>>>', firstPage.name, 'page render end')
   });
   firstPage.on('mounted', () => {
       console.log('>>>', firstPage.name, 'page mounted')
   });
   firstPage.refresh();
});

Method 3- Integrate a dashboard scenario

Here, you can customize the layout of the dashboard scenario such as add a slide animation after the scenario is mounted.

 ins.initialize({ container: viewerRoot, }).then((uiDashboard) => {
    const firstPage = uiDashboard.pages[0];
    const firstScenario = firstPage.widgets[0]; // UIScenario or UIContainer
    const scenarioDom = document.querySelector('#scenario-1');
    firstScenario.connect(scenarioDom);
    firstScenario.on('render', () => {
        console.log('>>>', firstScenario.name, ' scenario render start')
    });
    firstScenario.on('rendered', () => {
        console.log('>>>', firstScenario.name, ' scenario render end')
    });
    firstScenario.on('mounted', () => {
        console.log('>>>', firstScenario.name, ' scenario mounted')
    });
    firstScenario.on('update', () => {
        console.log('>>>', firstScenario.name, ' scenario update')
    });
    firstScenario.refresh();
});

Integrate Viewer using the Entire Dashboard Method

The following section describes the steps to integrate the dashboard lite viewer component in a web application using the entire dashboard method.

Add references to the dashboard lite viewer css and js files.

dashboard.viewerLite.css
dashboard.viewerLite.vendor.css
dashboard.viewerLite.js
dashboard.viewerLite.sheet.js
dashboard.viewerLite.chart.js
polyfills.js // this file is not part of viewer lite, It provides some polyfills on global.

References for lite viewer css files-

<link rel="stylesheet" href="/dist/dashboard.viewerLite.css" />
<link rel="stylesheet" href="/dist/dashboard.viewerLite.vendor.css" />

References for lite viewer js files-

<script src="/dist/polyfill.js"></script>
<script src="/dist/dashboard.viewerLite.js"></script>
<script src="/dist/dashboard.viewerLite.chart.js"></script>
<script src="/dist/dashboard.viewerLite.sheet.js"></script>

Add the following containers:

div#viewerlite-container: to create the instance for the dashboard lite viewer component
div#dashboard-container: to connect with the dashboard

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,maximum-scale=1.0,initial-scale=1.0,minimum-scale=1.0,user-scalable=no">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title>Viewer Lite Demo</title>

    <!-- viewerLite css file -->
    <link rel="stylesheet" href="/dist/dashboard.viewerLite.css" />
    <link rel="stylesheet" href="/dist/dashboard.viewerLite.vendor.css" />

    <!-- your code in app.css -->
    <link rel="stylesheet" href="/static/app.css" />
</head>

<body>
    <main id="viewerlite-container">
        <div id="dashboard-container">
        </div>
    </main>

    <script src="/dist/polyfill.js"></script>

    <!-- viewerLite js file -->
    <script src="/dist/dashboard.viewerLite.js"></script>
    <script src="/dist/dashboard.viewerLite.chart.js"></script>
    <script src="/dist/dashboard.viewerLite.sheet.js"></script>

    <!-- your code in app.js -->
    <script src="/static/app.js"></script>
</body>

</html>

You can also add custom animation to a dashboard (such as a transition effect) by modifying the referenced app.css file in the above code. For more information, refer to this article - Add Custom Animation to Dashboard.

Add the following code in app.js file to create an instance of the dashboard lite viewer component. The Token and baseUrl options in the code are used to integrate with other systems.

Initialize the lite viewer instance, it will return a promise. You will then get an instance of UIDashboard.
Connect the instance to the DOM element.
Refresh the instance and you will be able to see the document.
Destroy the instance.

const viewerLiteInstance = WynDashboards.createViewerLite({
  token: 'TOKEN_YOU_GOT_FROM_WYN_SERVER',
  baseUrl: 'WYN_SERVER_ADDRESS',
  dashboardId: 'xxxxxxxxxxxxxxx',
});

viewerLiteInstance.initialize({
  container: document.querySelector('#viewerlite-container'),
}).then((dash) => {
  document.title= dash.getName();
  const dashboardDom = document.querySelector('#dashboard-container');
  dash.connect(dashboardDom);
  dash.refresh();
});

window.addEventListener('beforeunload', (e) => {
  viewerLiteInstance.destroy();
});

Limitations

You cannot integrate and connect the same dashboard scenario twice. Let's suppose, scenario A is on the first page of the dashboard and you are already connected to the first page of the dashboard. In such a case, you can no longer connect to scenario A separately.

Similarly, containers, tabs, and groups can only be connected once. If the container is already connected to the DOM summary, you cannot connect to the scenario in the container separately.

// Note that the following two cases will not work correctly
// Case 1： The firstScenario will be connected twice. First, in the firstPage.connect, and second with dom2.
const firstPage = uiDashboard.pages[0];
const firstScenario = firstPage.scenarios[0];

firstPage.connect(dom1);
firstScenario.connect(dom2);

// case 2: The firstScenario will be connected twice. First, in the firstContainer.connect and second with dom2.
const firstPage = uiDashboard.pages[0];
const firstContainer = firstPage.containers[0];
const firstScenario =  firstContainer.scenarios[0];
firstContainer.connect(dom1);
firstScenario.connect(dom2);

The scope of cross filter, slicers between the dashboard scenarios is the same as that defined in the original dashboard. In simpler words, even if the scenarios in multiple dashboard pages are integrated into the same page, there will be no cross filtering effects between them, and the settings in the original dashboard will still be maintained. There is no filtering effect just because the UI is placed together.
```
const firstPage = uiDashboard.pages[0];
const secondPage = uiDashboard.pages[1];

const scenarioFromFirstPage = firstPage.scenarios[0];
const scenarioFromSecondPage =  secondPage.scenarios[0];

scenarioFromFirstPage.connect(dom1);
scenarioFromSecondPage.connect(dom2);

// Warning: In this case, the two scenarios cannot affect each other through cross filtering.
```