Embed Symphony Components Using JavaScript and Trusted Access

This applies to: Visual Data Discovery

You can embed a Symphony component using JavaScript.

The following components can be embedded:

• dashboards

• visual authoring experience

• source editor

When components are embedded, the way in which users can interact with them is determined by settings established by their Symphony user definition. See Embedded Symphony Component Controls.

Complete examples of JavaScript code that initializes and authorizes the Symphony EmbedManager class are provided in Embedded JavaScript Examples.

Follow these steps:

• Step 1. Verify the Prerequisites Have Been Met
• Step 2. Make the Embed Manager Available to Your Application
• Step 3. Initialize and Authorize the Embed Manager
• Step 4. Create and Render a Symphony Component in Your Application

Step 1. Verify the Prerequisites Have Been Met

Verify that the embedded dashboard prerequisites have been met. See Embedded Component Prerequisites.

Step 2. Make the Embed Manager Available to Your Application

To make the Symphony's embed manager available to your application, include this script in your HTML:

<script data-name="composer-embed-manager" src="https://<samplecomposerurl>/embed/embed.js"></script>

where <samplecomposerurl> is the URL of your Symphony instance.

After this script is run, the initComposerEmbedManager function is available globally in window.

Step 3. Initialize and Authorize the Embed Manager

Use the window.initComposerEmbedManager function to initialize and authorize the embed manager. This can be done using the following configuration properties. Note that the token you supply must be obtained beforehand using the Trusted Access API, usually in backend code that supports your HTML.

The getToken property is a method that returns a token from Trusted Access prior to token expiration. Here is an example:

const getEmbedManagerPromise = 
window.initComposerEmbedManager({
       getToken: function () {
           // transform for the embed syntax
           return getToken().then((result) => { // getToken function uses the Trusted Access API
               return {
                   access_token: result.token,
                   expires_in: result.expiresIn,
               };
            });
        },
});

After the initComposerEmbedManager function is called, it returns a promise that resolves an instance of the EmbedManager class. The objects, methods, properties, and embedded events provided with the Symphony EmbedManager class can be used in your HTML.

Step 4. Create and Render a Symphony Component in Your Application

After the Symphony EmbedManager class has been initialized and authorized, you can use its methods to embed a Symphony component in your application and set various properties for that component. In addition, you can use Symphony embedded events to control component behavior when specific events occur.

Other EmbedManager methods can be used to modify, refresh, and remove Symphony components in your application.

Complete descriptions of the supported EmbedManager methods and properties are provided in EmbedManager Methods, Embedded Dashboard Properties and Objects, and Embedded Visual Authoring Properties and Objects. Supported Composer embedded events are described in Embedded Events.

The following simple example creates and renders an embedded dashboard:

getEmbedManagerPromise.then((embedManager) => {
     embedManager.createComponent('dashboard',
          {
               dashboardId: <id>, // dashboard id
               <property>,... // set of properties
          }
     ).then(dashboard => dashboard.render(
          htmlElement, // htmlElement
          {width: '100%', height: '100%'}
     ))
});

// Example with async await
async function createComponent() {
     const embedManager = await getEmbedManagerPromise;
     const newDashboard = await embedManager.createComponent('dashboard',
          {
               dashboardId: <id>, // dashboard id
               <property>,... // set of properties
          });
     newDashboard.render(
          htmlElement, // htmlElement or selector
          {width: '100%', height: '100%'}
     ));
}