Basic concepts

General JavaScript environment (no-framework)

In a no-framework environment, you can create an instance by using the EmbedClient class from the embedding SDK. The following code is an example.

import { EmbedClient } from '@quickbi/bi-embed-client';

const embedClient = new EmbedClient({})

After creating an embedded client instance, the SDK does not render the embedded page immediately. You must call the render method to mount it to a DOM node on the host page.

embedClient.render(document.getElementById('container'));

Use the destroy method to destroy the embedded page.

embedClient.destroy();

import { EmbedClient, EmbedSrcUnion, compilePath } from '@quickbi/bi-embed-client';
const lastSrc:EmbedSrcUnion = {};
let embedClient = new EmbedClient({ src: lastSrc });
embedClient.render(containerDom)
const newSrc:EmbedSrcUnion = {};
if (compilePath(lastSrc) !== compilePath(newSrc)) { // Embedded source changes.
  embedClient.destroy(); // Destroy the embedded page.
  embedClient = new EmbedClient({ src: newSrc }); // Create a new instance.
  embedClient.render(containerDom) // Re-render.
}

React framework environment (recommended)

In the embedding SDK for React, the EmbedComponent component internally creates an embedded client instance and handles re-rendering automatically. You can obtain the embedded client instance using useRef.

import { EmbedClient, EmbedComponent } from '@quickbi/bi-embed-client-react';

const Demo: React.FC = () => {
  const embedClient = React.useRef<EmbedClient>();
  return (
    <EmbedComponent
      ref={embedClient}
      src={{
        // ...
      }}
    />
  )
}

Vue2 framework environment

In a Vue2 environment, you can directly import the EmbedComponent component. This component internally creates an embedded client instance and handles reactive rendering. You can obtain the embedded client instance by using this.$refs.

<template>
  <embed-component
    ref="child"
    :src="embedSrc"
  />
</template>
<script lang="ts">
import { EmbedComponent } from '@quickbi/bi-embed-client-vue2',
export default Vue.extend({
  name: 'SDK',
  components: {
    EmbedComponent
  },
  data() {
    return {
      embedSrc: {
       // ...
      },
    }
  }
  mounted(){
    /** Get the embedded client instance */
    const embedClient = this.$refs.child.embedClient;
    // Or by using the method exposed by the child component
    const embedClient = this.$refs.child.getEmbedClient();
  }
}),
</script>

Vue3 framework environment

Directly import the EmbedComponent component. It internally creates an embedded client instance and handles reactive rendering. You can obtain the instance by using ref and the getEmbedClient method exposed by the component.

<script setup lang="ts">
import {
  EmbedRouteKey,
  EmbedComponent,
} from "@quickbi/bi-embed-client-vue";
import type { EmbedSrcUnion } from "@quickbi/bi-embed-client-vue";
import { ref,onMounted } from "vue";

const embedSrc = ref<EmbedSrcUnion>({
  origin: 'xxx',  // Host for accessing Quick BI
  page: EmbedRouteKey.dashboardEdit,  // EmbedRouteKey for the dashboard edit page
  // Query parameters for accessing the Quick BI dashboard page
  search: {
    workspaceId: 'xxx',  // Workspace ID
    id: 'xxx',  // Work ID
  }
});
// Create a reference to EmbedComponent
const embedComponentRef = ref<InstanceType<typeof EmbedComponent> | null>(null);
// You can safely access the client instance after the component is mounted
onMounted(() => {
  const embedClient = embedComponentRef.value?.getEmbedClient();
  });

</script>

<template>
  <EmbedComponent
    :src="embedSrc"
    ref="embedComponentRef"
  />
</template>

Embedded source

The embedded source, or src, is an object that defines the page to embed. It specifies the target page and its parameters and is required when you create the client instance. It includes the following properties:

• origin: The source of the embedded content, for example, https://bi.aliyun.com.

• page: Each Quick BI work page and each tab on a list page is a route, such as a dashboard preview page, dashboard editing page, or workbench dashboard list page. Each route has a unique route key. For a list of route keys, see Route Key Reference.

  Note

  To ensure correct embedding, always use the EmbedRouteKey route enum instead of string literals.

• search: The URL parameters to pass to the embedded page.

  import { EmbedRouteKey } from '@quickbi/bi-embed-client';
  
  const embedClient = new EmbedClient({
    src: {
      origin: 'https://bi.aliyun.com',
      page: EmbedRouteKey.dashboardEdit,
      search: {},
    },
  });

  The embedding SDK provides utility functions to parse a URL into an embedded source or compile an embedded source into a URL.

  import { parsePath, compilePath, EmbedRouteKey } from '@quickbi/bi-embed-client';
  
  // url => src
  parsePath('https://bi.aliyun.com/workspace/dashboard?workspaceId=xxx'); // { page: 'dashboardList': {}, origin: 'https://bi.aliyun.com', search: { workspaceId: 'xx' } }
  
  // src => url
  compilePath({
    page: EmbedRouteKey.dashboardList,
    origin: 'https://bi.aliyun.com',
    search: { workspaceId: 'xx' },
  }); // https://bi.aliyun.com/workspace/dashboard?workspaceId=xxx

Embedded action

An embedded action, or action, is an object that defines an operation on the embedded page that the host can invoke. The host can trigger an embedded action by calling the dispatch(action) method of the embedded client instance. The action contains the following information:

• type: The key for the action type, such as navigating to a specific page. The type is EmbedActionType. For more information, see action.

  Note

  To ensure actions function correctly, always use the EmbedActionType enum instead of string literals.

• payload: The specific parameters for the embedded action. Different action types have different parameters. For more information, see action.

  /** Navigate to a specific page */
  embedClient.dispatch({
    type: EmbedActionType.embedNavigate,
    payload: {
      src: newSrc,
    }
  })

Embedded feature

An embedded feature, or feature, is a configuration for customizing the appearance of an embedded page, such as showing or hiding UI components or modifying display text. The configuration has a three-level structure: route key > functional module > feature configuration item. For detailed feature configurations, see feature.

feature: {
  [route key]: {
    [functional module]: {
      [feature configuration item key]: value
    }
  }
}

An embedded feature only takes effect within its configured route scope. The route key must match the page property of the embedded source. For example:

{
  src: {
    page: EmbedRouteKey.screenEdit,
  },
  feature: {
    [EmbedRouteKey.dashboardEdit]: { // Does not match the page property.
      goBack: { // Configuration is invalid because the page and route scope do not match.
        show: false,
      },
    },
  },
};

{
  src: {
    page: EmbedRouteKey.screenEdit,
  },
  feature: {
    [EmbedRouteKey.screenEdit]: {
      goBack: { // Configuration is valid.
        show: false,
      },
    },
  },
};

The host page can update embedded features by calling the setEmbedFeature action on the embedded client instance.

embedClient.dispatch({
  type: EmbedActionType.setEmbedFeature,
  payload: {
    [EmbedRouteKey.dashboardEdit]: {
      goBack: {
        show: goBack, // Hide the Back button on the dashboard editing page
      },
    },
  },
});

• React

  In the React framework SDK, a change to the props.feature of the EmbedComponent component automatically triggers a feature update.

  import { EmbedComponent } from '@quickbi/bi-embed-client-react';
  
  const Demo: React.FC = () => {
    return (
      <EmbedComponent
        feature={{
          // Features are automatically updated.
        }}
      />
    )
  }

• Vue2

  In the Vue2 embedding SDK, the EmbedComponent component reactively updates features when the bound feature prop changes.

  <template>
    <embed-component
      :feature="embedFeature"
    />
  </template>
  <script lang="ts">
  import { EmbedComponent } from '@quickbi/bi-embed-client-vue2',
  export default Vue.extend({
    name: 'SDK',
    components: {
      EmbedComponent
    },
    data() {
      return {
      embedFeature: {
         // Features are automatically updated.
        },
      }
    }
    
  }),
  </script>

• Vue3

  In the Vue3 framework SDK, the EmbedComponent component's props.feature automatically triggers feature updates through dynamic binding.

  <script setup lang="ts">
  import { EmbedComponent } from "@quickbi/bi-embed-client-vue";
  import { ref } from "vue";
  
  const embedFeature = ref({
    // Features are automatically updated.
  })
  </script>
  
  <template>
    <EmbedComponent
      :feature="embedFeature"
    />
  </template>

Embedded event

When an embedded page performs certain actions, it sends embedded events to the host page. The host page can register an event callback using the on(eventType, handler) method of the embedded client instance. When the page is no longer needed, you can unbind the event using the off(eventType, handler) method.

• eventType: The name of the event.

  Note

  To ensure events function correctly, always use the EmbedEventType enum instead of string literals.

• handler: The event callback function on the host page. The parameters passed to the callback vary depending on the event. For more information, see events.

  async handler function(payload) {}
  
  // Bind the event.
  embedClient.on(EmbedEventType['before-page-change-event'], handler); 
  
  // Unbind the event.
  embedClient.off(EmbedEventType['before-page-change-event'], handler);

In the React embedding SDK, changes to the events prop of the EmbedComponent component automatically rebind the event handlers. The SDK also unbinds all handlers when the component is unmounted.

import { EmbedComponent, EmbedEventType } from '@quickbi/bi-embed-client-react';

const Demo: React.FC = () => {
  const handler = useCallback(() => {}, []);
  return (
    <EmbedComponent
      events={{
        [EmbedEventType['before-page-change-event']]: handler // The handler is automatically updated.
      }}
    />
  )
}

In the Vue2 embedding SDK, changes to the events prop of the EmbedComponent component automatically rebind the event handlers. The SDK also unbinds all handlers when the component is destroyed.

<template>
  <embed-component
    :events="embedEvents"
  />
</template>
<script lang="ts">
import { EmbedComponent, EmbedEventType } from '@quickbi/bi-embed-client-vue2',
export default Vue.extend({
  name: 'SDK',
  components: {
    EmbedComponent
  },
  data() {
    return {
    embedEvents: {
      [EmbedEventType['before-page-change-event']]: handler // The handler is automatically updated.
      },
    }
  }
}),
</script>

In the Vue3 embedding SDK, changes to the events prop of the EmbedComponent component automatically rebind the event handlers. The SDK also unbinds all handlers when the component is unmounted.

<script setup lang="ts">
import { EmbedComponent,EmbedEventType } from "@quickbi/bi-embed-client-vue";
import { ref } from "vue";

const embedEvents = {
  [EmbedEventType["before-page-change-event"]]: handler
};
</script>

<template>
  <EmbedComponent
    :events="embedEvents"
  />
</template>