Page and Card Embedding Solution - Web SDK

Overview

Guandata supports quickly embedding completed Dashboard pages and Card detail pages into customer systems. At the technical level, this mainly uses iframe embedding and provides two implementation methods:

• Embed pages directly and pass the user token and specific filter parameters through the URL.
• Use the Guandata Web SDK to quickly embed pages and Cards, with support for complex filter parameters.

Direct Page Embedding

For the specific approach, see this guide. This solution is suitable when only a small number of parameters need to be passed.

Embed Pages and Cards Through Web SDK

The SDK provides the following capabilities:

• Quick embedding through Card ID and Page ID
• Communication between the host window and the embedded page to pass filter parameters

SDK download: https://www.npmjs.com/package/gd-sdk

Code Examples

Embed a Card

import React, { useEffect, useImperativeHandle, useState, forwardRef, useRef } from 'react'
import { Card } from 'gd-sdk'

function BICard(props, ref) {
  const { cdId } = props
  const [card, setCard] = useState(null)
  const iframeRef = useRef()
  const [configInfo, setConfigInfo] = useState(null)
  useImperativeHandle(ref, () => ({
    // Pass filter information to the Card
    updateFilter: (filter) => {
      card && card.updateFilter(filter)
    },
    // Refresh method, supports refreshing with filters, for example after drill actions
    refresh: (filter) => {
      const newCard = new Card(configInfo.base, configInfo.params)
      setCard(newCard)
      filter && newCard.updateFilter(filter)
    },
  }))
  useEffect(() => {
    // fetchData should return the following structure:
    // {
    //   address: 'https://demo.guandata.com',
    //   domainId: 'demo',
    //   ssoToken: 'xxxxxx',
    // }
    fetchData().then((data) => {
      const conf = {
        base: {
          host: data.address,
          domain: data.domainId,
          ssoToken: data.ssoToken,
        },
        params: {
          ps: 'embed',
          container: iframeRef.current,
          cdId,
        },
      }
      setConfigInfo(conf)
      setCard(new Card(conf.base, conf.params))
    })
  }, [cdId])
  return
}
export default forwardRef(BICardIframe)

Linked Card

import React, { useRef, useEffect } from 'react'

// Example filter array
// [{
//   fdId: 'xxxx',
//   name: 'field name',
//   filterValue: ['20'],
//   filterType: FilterTypes.IN,
// }, {
//   ...
// }]
const filter = [{
  fdId: 'eefc3d11461514365b065b41',
  name: 'province',
  filterValue: ['Zhejiang'],
  filterType: 'IN',
}]

export default TableView() {
  const BICard = useRef()
  useEffect(() => {
    BICard.updateFilter(filter)
  }, [])
  const onRefresh = () => {
    BICard.refresh(filter)
  }
  return (
  )
}

Embed a Page and Trigger Linkage

import { Page } from 'gd-sdk'

const instanse = new Page(
  {
    host: 'xxx',
    domain: 'domainId',
    ssoToken: 'ssoToken',
  },
  {
    ps: 'iframe2',
    container: dom,
    pgId: 'xxxx',
    query: { name: 'value' },
  }
)

instanse.updateFilter([
  {
    fdId: 'fieldId',
    cdId: 'filterCardId',
    name: 'filterName',
    filterValue: ['filterValue'],
    filterType: 'IN',
  },
])

Before use, create an instance named instanse. When triggering linkage, call instanse.updateFilter. The method accepts an array as the linkage parameter. If the target is a Page, multiple filters can be triggered at the same time. If the target is a Card, multiple filter conditions can be applied at the same time.

Notes on Passing Linkage Parameters

Match Filters

For embedded Pages, externally triggered linkage is first matched against filters on the current page before the filter linkage is triggered. A match is considered successful if any one of fdId, cdId, or name in the page filter matches the external linkage parameter. Here, fdId is the ID of the Dataset field referenced by the filter, cdId is the ID of the filter Card, and name is the name of the filter Card.

Match Filter Conditions

For embedded Cards, externally triggered linkage is applied directly to the Card. It also supports omitting fdId and using name to match the alias or name of any field in the Dataset used by the current Card. A successful name match becomes a valid filter condition.

Filter Types and Filter Values

filterType indicates the filter type. The following values are supported. filterValue indicates the filter value and must be a string array. Its meaning varies depending on filterType.

• IN: selection filter. filterValue can contain multiple values.
• EQ: equals. filterValue can contain only one value.
• NE: not equals. filterValue can contain only one value.
• CONTAINS: contains. filterValue can contain only one value.
• NOT_CONTAINS: does not contain. filterValue can contain only one value.
• STARTSWITH: starts with. filterValue can contain only one value.
• ENDSWITH: ends with. filterValue can contain only one value.
• NOT_STARTSWITH: does not start with. filterValue can contain only one value.
• NOT_ENDSWITH: does not end with. filterValue can contain only one value.
• BT: between. filterValue must contain two values.
• GT: greater than. filterValue can contain only one value.
• GE: greater than or equal to. filterValue can contain only one value.
• LT: less than. filterValue can contain only one value.
• LE: less than or equal to. filterValue can contain only one value.
• IS_NULL: null. filterValue contains no value.
• NOT_NULL: not null. filterValue contains no value.

Notes

When embedding a Page, the filterType and filterValue in the incoming filter parameters must match the internal filter being targeted. For example, if the internal filter is a selection filter, the incoming filterType must be IN.

For security reasons, the SSO token should be generated on the backend. For the specific implementation method, see Guandata BI SSO Integration.