Embed Logi Components Using Typescript

You can embed a Logi component using Typescript. The following components can be embedded:

• dashboards
• visual authoring experience
• source authoring
• list of inventory items
• lite dashboard

Changelog

| Version | Comments | |---------|---| | 23.2 | New Inventory type Source was added New visual events were added New dashboard and visual interactivity settings were added Added ability to hide restricted visuals on a dashboard| | 23.3 | New dashboard events were added New dashboard interactivity settings were added Custom Menu configuration was extended | | 23.4 | New visual interactivity settings were added Refresh data method was added to the dashboard component Bulk export was added to the Inventory component Allowed multiselect for type, data source, and tags in the inventory search bar | | 24.1 | New embed component called lite-dashboard was added New parameter called availableVisTypes was added, this can be used in case of lite-dashboard component to specify a limited set of visual types. | | 24.2 | Version change to follow composer release cycle | | 24.3.1 | Minor bug fixes | | 24.4.1 | instance param added to inventory click handler. Required for package-based usage. | | 25.3 | New Inventory type Report was added. Supported only for symphony. | | 25.4 | New embed component chat-bot introduced (experimental, works with Simba Intelligence) New param loadNewUI added to source-editor component. Set it to true to load new UI for Source Editor component.| | 26.1.1 | Bug fixes |

For more documentation can follow typedoc at https://<youcomposersurl.com>/composer/embed/docs/index.html

Install the Library

npm install logi-embed

Make the Embed Manager Available to Your Application

Since Composer uses Apache ECharts all JavaScript and HTML Source files used for embedding must be encoded in UTF-8 without BOM. Import init function from the module. Import required constants like ComponentTypes.

import { initEmbedManager, ComponentTypes } from 'logi-embed'

Initialize and Authorize the Embed Manager

Use the initEmbedManager function to initialize and authorize the embed manager. This can be done using either of 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 = initEmbedManager(
    {
        getToken: function () {
            // transform for the embed syntax.
            return getToken().then((result) => {
                // getToken function uses parent app backend. response structure is controlled by parent app.
                return {
                    access_token: result.token,
                    expires_in: result.expiresIn,
                };
            });
        },
    },
    url,
); // url pattern: https://<samplecomposerurl>/composer;

• The initialToken property is a way to pass just a token and handle expiration on your own. This option is not preferred and should be used for long living tokens only.

const getEmbedManagerPromise = initEmbedManager(
    {
        initialToken: 'tokenValue', // tokenValue is provided by the Trusted Access API
    },
    url,
); // url pattern: https://<samplecomposerurl>/composer;

After the initEmbedManager 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 Composer EmbedManager class can be used in your HTML.

Create and Render a Composer Component in Your Application

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

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

The following simple example creates and renders an embedded dashboard:

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


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

Dashboard

Dashboard Configuration

When creating dashboard component with no parameters, empty dashboard will be embedded. Use following dashboard properties for customization.

| Property | Description | | --------------------------- | ------------------------------------------------------------------------- | | dashboardId | id of the composer dashboard | | theme | Name of theme you want to apply to the dashboard | | header | Configuration of dashboard header | | editor | Configuration of enhanced visual editor | | interactivityProfileName | Name of interactivity profile. Use "readonly" for simple cases | | interactivityOverrides | Granular configuration of the dashboard parts and features | | menuEventsConfig | Configuration of the interaction with visuals | | editorUserSettings | Settings that controls editor capabilities of the dashboard | | suppressAutoLayoutWarning | Allows to hide visibility of old layout warning | | suppressResponsiveLayout | Allows to disable responsive behavior of layout on different screen sizes | | initialFilters | Ability to set default filters for a source | | notificationSettings | Controls places where alerts will be displayed | | hideRestrictedVisuals | Controls presence of restricted visuals in the dashboard | | visualLegendType | Allows to define visual legend type despite staticLegend toggle value | | availableVisTypes | Allows to define a limited set of visual types. For Dashboard component | | | it is undefined, for lite-dashboard availableVisTypes can be customized |

Example of embedding Dashboard

import { EditorPlacements, SettingTypes, DashboardSettingKeys, VisualSettingKeys, SeriesActionItems } from 'logi-embed';
const newDashboard = await embedManager.createComponent(ComponentTypes.DASHBOARD, {
    dashboardId: 'id', // dashboard id
    theme: 'dark', // set of properties
    header: {
        visible: true,
        showTitle: false,
        showActions: true,
    },
    editor: {
        placement: EditorPlacements.DOCK_RIGHT,
    },
    interactivityOverrides: {
        [SettingTypes.DASHBOARD]: {
            [DashboardSettingKeys.CHANGE_LAYOUT]: false,
        },
        [SettingTypes.VISUAL]: {
            [VisualSettingKeys.COPY]: false,
        },
    },
    menuEventsConfig: {
        click: SeriesActionItems.FILTER,
        contextMenu: 'openMenu',
    },
    suppressAutoLayoutWarning: true,
});

Dashboard Methods

Dashboard has next methods. These are available for any embedded components.

| Event | Description | | --------------------- | ---------------------------------------------------------------------- | | addEventListener | Adds event listeners. Allows to subscribe on custom component's events | | removeEventListener | Removes added event listener | | render | Use for adding component to DOM | | refreshData | Refreshed visual data on the dashboard |

Dashboard Events

Dashboard fires next events. Subscribe on these in order to customize your application.

import { DashboardEventNames } from 'logi-embed';
const newDashboard = await embedManager.createComponent(ComponentTypes.DASHBOARD, {
    dashboardId: 'id', // dashboard id
    ...properties, // set of properties
});
newDashboard.addEventListener(DashboardEventNames.READY, (e) => {
    console.log(e.detail);
});

| Event | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | READY | Triggered by the dashboard when all visuals on the dashboard have been rendered | | LOADED | Triggered when a dashboard resource is loaded | | SAVED | Triggered by the dashboard when a visual is added to the dashboard | | WIDGET_ADDED | Triggered by the dashboard when a visual is removed from the dashboard | | WIDGET_REMOVED | Triggered by the dashboard when a visual is removed from the dashboard | | CHANGED | Triggered by the dashboard when there is any change in the dashboard configuration | | DELETED | Triggered by the dashboard when the dashboard is deleted | | DIRTY | Triggered by the dashboard when the dashboard becomes unsaved | | PRISTINE | Triggered by the dashboard when the dashboard loaded for the first time or when its state was changed from unsaved |