Angular component for Luzmo

This is an Angular library for embedding Luzmo dashboards in your Angular application.

Table of contents

1. Installation instructions
2. Luzmo Viz Item
3. Luzmo Dashboard
4. Luzmo IQ Components
5. Changelog
6. Migration
7. Compatibility
8. Quick links

Installation instructions

npm i @luzmo/ngx-embed --save

OR

ng add @luzmo/ngx-embed@latest #This also adds an entry in app.module.ts or app.component.ts if using standalone components.

Luzmo Viz Item

For a more comprehensive documentation visit Flex SDK Docs - Luzmo Developer Docs

In your app.module.ts import NgxLuzmoDashboardModule

import { NgxLuzmoDashboardModule, NgxLuzmoVizItemComponent } from '@luzmo/ngx-embed';

@NgModule({
    ...
  imports: [
    ...
    NgxLuzmoDashboardModule
  ],
})

OR import standalone component

@Component(
  imports: [ NgxLuzmoVizItemComponent ]
)

In your HTML template.

<!-- Embed a viz item by passing the options and slots -->
<luzmo-viz-item type="bar-chart" [options]="options" [slots]="slots" authKey="authKey" authToken="authToken"> </luzmo-viz-item>

OR

<!-- Embed a viz item by passing the item id and dashboard id -->
<luzmo-viz-item [dashboardId]="dashboardId" [itemId]="itemId" [options]="options" authKey="authKey" authToken="authToken"> </luzmo-viz-item>

Working with events

<!-- Listening for events, logEvent is a function with console log -->
<luzmo-viz-item type="bar-chart" (load)="logEvent($event)" (customEvent)="logEvent($event)" (changedFilters)="logEvent($event)"> </luzmo-viz-item>

Available Inputs

| Property | Type | Description | |----------------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | type | string | The type of viz item to embed. | | options | object | The options object to be passed on to viz item | | slots | array | The slots array to specify which columns to use to fetch data. depends on the type of chart. | | contextId | string | contextId is a unique id that can be assigned to viz item which will be used in filtering with canFilter. | | authKey | string | Authorization key generated via Luzmo API | | authToken | string | Authorization token generated via Luzmo API | | canFilter | string | array | canFilter can be either set to all or an array of contextId's. | | filters | object | filters object is used to set initial filters. | | appServer | string | Tenancy of luzmo.com to connect to (Default: 'https://app.luzmo.com/' for US set appServer to 'https://app.us.luzmo.com/') | | apiHost | string | API server to connect to (Default: 'https://api.luzmo.com/' , for US set apiHost to 'https://api.us.luzmo.com/') |

Public methods on NgxLuzmoVizItemComponent instance

getData(): any
// Return an array of the data of the viz item that's embedded.

getFilters(): FilterGroup[];
// Return an array of active filters on the viz item.

refreshData(): void
// Refresh the data of the viz item.

setAuthorization(key: string, token: string): void
// Changes the authorization of the viz item. To fetch data based on new authorization parameters, refreshData() needs to be called.

export(): void
// Export the viz item as png.

Examples

A Bar chart with display title hidden.

<luzmo-viz-item #vizItemInstance id="vizItem" type="bar-chart" options='{ "display": { "title": false } }'></luzmo-viz-item>

An event handler added to the luzmo-viz-item to listen for the load event.

<luzmo-viz-item #vizItemInstance id="vizItem" type="bar-chart" (load)="loadEvent($event)"></luzmo-viz-item>

import { NgxLuzmoVizItemComponent } from '@luzmo/ngx-embed';
...

@Component({
  ...
})

export class TestIntegrationComponent {
  @ViewChild('vizItemInstance') vizItemInstance: NgxLuzmoVizItemComponent;
  ...
  constructor() { }
  
  loadEvent(event: any) {
    console.log(event);
  }

  // To refresh data
  refresh() {
    this.vizItemInstance.refreshData(); // Unsubscribe in ngOnDestroy
  }
  allFunctions() {
    const filters = this.vizItemInstance.getFilters();
    const data = this.vizItemInstance.getData();
    this.vizItemInstance.refreshData();
    this.vizItemInstance.export();
  }
}

Events

| Name | Description | |----------------|----------------------------------------| | changedFilters | Emitted when filters are changed | | customEvent | Emitted when a custom event is fired | | exported | Emitted when export completes or fails | | rendered | Emitted when the item is rendered | | load | Emitted when viz item is loaded |

Luzmo Dashboard

Usage Luzmo Dashboard

In your app.module.ts import NgxLuzmoDashboardModule

import { NgxLuzmoDashboardModule } from '@luzmo/ngx-embed';

@NgModule({
    ...
  imports: [
    ...
    NgxLuzmoDashboardModule
  ],
})

In your HTML template.

<luzmo-dashboard [dashboardId]="dashboardId" [language]="'en'"> </luzmo-dashboard>

OR

<!-- Embed a chart/item by passing the item id as well -->
<luzmo-dashboard [dashboardId]="dashboardId" [itemId]="itemId" [language]="'en'"> </luzmo-dashboard>

Working with events

<!-- Listening for events, logEvent is a function with console log -->
<luzmo-dashboard [dashboardId]="dashboardId" [language]="'en'" (load)="logEvent($event)" (customEvent)="logEvent($event)" (changedFilters)="logEvent($event)"> </luzmo-dashboard>

Available inputs

Below a list of available input options you can add to your ngx-luzmo-dashboard

| Property | Type | Description | | -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dashboardId | string | The id of the Luzmo dashboard you wish to embed | | dashboardSlug | string | The slug of the Luzmo dashboard you wish to embed (if a dashboardId is supplied that one will be used) | | itemId | string | The id of the Luzmo item you wish to embed. The dashboardId should be provided as well if you what to embed just a Luzmo item. | | itemDimensions | { width: number/string; height: number/string; } | width and height of item only applies when itemId is provided. | | authKey | string | Authorization key generated via Luzmo API | | authToken | string | Authorization token generated via Luzmo API | | language | string | The language of the dashboard: eg. 'en' (Default: 'auto') | | screenMode | string | The screen mode of your dashboard: 'mobile', 'tablet', 'desktop', 'largeScreen', 'fixed' or 'auto' (Default: 'auto') | | switchScreenModeOnResize | boolean | true: the embedded dashboard can switch screenModes on resize of the container , false: Dashboard will keep the same screenMode (Default: true) | | loaderBackground | string | Background color of the loader element (Default: '#f9f9f9') | | loaderFontColor | string | Font color of the text of the loaders (Default: '#5a5a5a') | | loaderSpinnerColor | string | Spinner color of the loader (Default: 'rgba(255, 165, 0, 0.7)') | | loaderSpinnerBackground | string | Background color of the spinner (Default: 'rgba(169, 169, 169, 0.14)') | | appServer | string | Tenancy of luzmo.com to connect to (Default: 'https://app.luzmo.com/' for US set appServer to 'https://app.us.luzmo.com/') | | timezoneId | string | The timezone you you wish to use in your dashboard. This timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York. | | apiHost | string | API server to connect to (Default: 'https://api.luzmo.com/' for US set apiHost to 'https://api.us.luzmo.com/') | | editMode | string | Specifies if the embedded dashboard should be editable or not. Accepted values: "view" , "editLimited" , "editFull" . Use "view" if you don't want the embedded dashboard to be editable. (Default: "view" ) | | mainColor | string | Optional override of the main color used in the whitelabeling of the embedded dashboard editor. If not provided, the main color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values (i.e. "rgb(50,50,50)"). | | accentColor | string | Optional override of the accent color used in the whitelabeling of the embedded dashboard editor. If not provided, the accent color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values (i.e. "rgb(50,50,50)"). |

Examples

A dashboard with a gray loader background

<luzmo-dashboard #dashboardInstance [dashboardId]="'035c0304-0bfe-4b7c-8c10-a4acb8eb9d76'" [loaderBackground]="'rgb(238,243,246)'"> </luzmo-dashboard>

A dashboard with a purple spinner color of the loader with screenMode="mobile" and switchScreenModeOnResize=false, so that the dashboard will stay in mobile mode

<luzmo-dashboard #dashboardInstance [dashboardId]="'55cfb99c-d602-492b-b192-6c15277fdb9a'" [loaderSpinnerColor]="'purple'" [screenMode]="'mobile'" [switchScreenModeOnResize]="false"> </luzmo-dashboard>

In Component, service can also be used to facilitate different functionality (Only refresh data is implemented here, other methods can also be implemented in similar fashion)

import { NgxLuzmoDashboardService, NgxLuzmoDashboardComponent } from '@luzmo/ngx-embed';
...

@Component({
  ...
})

export class TestIntegrationComponent {
  @ViewChild('dashboardInstance') dashboardInstance: NgxLuzmoDashboardComponent;
  ...
  constructor() { }

  // To refresh data
  refresh() {
    this.dashboardInstance.refreshData().subscribe(); // Unsubscribe in ngOnDestroy
  }
  allFunctions() {
    this.dashboardInstance.getFilters().subscribe(console.log);
    this.dashboardInstance.getData('item-id').subscribe(console.log);
    this.dashboardInstance.reloadDashboard().subscribe(console.log);
    this.dashboardInstance.exportDashboard('png').subscribe(console.log);
    this.dashboardInstance.getAccessibleDashboards().subscribe(console.log);
  }
}

Public methods available on dashboardComponent instance

getDashboards(): Observable<NgxLuzmoDashboard[]>
// Returns an instantly resolved promise with an array of all the visible dashboards on a page with their information.

getData(itemId: string): Observable<ItemData>
// Returns an array the data of a chart of a certain dashboard by adding the dashboardId or the container of the iframe.

getFilters(): Observable<FilterGroup[]>
// Returns an array of active filters.

setAuthorization(key: string, token: string): Observable<void>
// Changes the authorization of all or one dashboard. To fetch data based on new authorization parameters, reloadDashboard() or refreshData() needs to be called.

refreshData(itemId?: string): Observable<void>
// Refreshes the data of a specific chart when the id of that item is supplied. Without a itemId this refreshes the data in all items.

reloadDashboard(): Observable<void>
// Reload the dashboard. (useful when the authorization is changed, and dashboard needs to be reloaded without reloading the iFrame)

exportDashboard(type?: ExportType): Observable<ExportDashboard>
// Exports the current dashboard as either pdf or png. a container class needs to be passed as an argument and an optional type parameter.

getAccessibleDashboards(): Observable<AccessibleDashboards>
// Get accessible dashboards in a integration, make sure apiHost, authKey, authToken are set correctly on the instance.

setEditMode(editMode: DashboardEditMode): Observable<SetEditMode>
// Sets the editMode of the current dashboard. Accepted parameters: view , editLimited , editFull .

Events

| Name | Description | Event Arguments | | -------------- | -------------------------------------- | --------------------- | | changedFilters | Emitted when filters are changed | ChangedFiltersEvent | | customEvent | Emitted when a custom event is fired | CustomEvent | | exported | Emitted when export completes or fails | ExportedEvent | | itemsRendered | Emitted when all items are rendered | ItemsRenderedEvent | | load | Emitted when dashboard is loaded | LoadEvent |

Luzmo IQ components

How to use the IQ components

In your app.module.ts import NgxLuzmoIQChatComponent and NgxLuzmoIQAnswerComponent

import { NgxLuzmoIQChatComponent } from '@luzmo/ngx-embed';

// OR

import { NgxLuzmoIQAnswerComponent } from '@luzmo/ngx-embed';

@NgModule({
    ...
  imports: [
    ...
    NgxLuzmoIQChatComponent,
    NgxLuzmoIQAnswerComponent
  ],
})

In your HTML template.

<luzmo-iq-chat authKey="Your auth key" authToken="Your auth token" options="options"> </luzmo-iq-chat>

OR

<luzmo-iq-answer authKey="Your auth key" authToken="Your auth token" options="options" messages="messages"> </luzmo-iq-answer>

Inputs

IQ chat component

All available inputs for the IQ chat component can be seen in the table below.

| Property | Type | Description | |-------------------------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| | authKey | string | Authorization key generated via Luzmo API | | authToken | string | Authorization token generated via Luzmo API | | appServer | string | Tenancy of Luzmo app to connect to (Default: 'https://app.luzmo.com/' for US set appServer to 'https://app.us.luzmo.com/') | | apiHost | string | Tenancy of Luzmo API to connect to (Default: 'https://api.luzmo.com/' , for US set apiHost to 'https://api.us.luzmo.com/') | | options | string | Specifies the customization options of the IQ chat component that affect its appearance and functionality. | | initialSuggestionsDatasetId | string | ID of a dataset that assists the AI service in generating automated, initial prompts based on the provided data. |

IQ answer component

All available inputs for the IQ answer component can be seen in the table below.

| Property | Type | Description | |-------------|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| | authKey | string | Authorization key generated via Luzmo API | | authToken | string | Authorization token generated via Luzmo API | | appServer | string | Tenancy of Luzmo app to connect to (Default: 'https://app.luzmo.com/' for US set appServer to 'https://app.us.luzmo.com/') | | apiHost | string | Tenancy of Luzmo API to connect to (Default: 'https://api.luzmo.com/' , for US set apiHost to 'https://api.us.luzmo.com/') | | options | string | Specifies the customization options of the IQ answer component that affect its appearance and functionality. | | messages | string | Specifies an array of messages to be displayed in the IQ answer component. |

Customization options

IQ chat component

The IQChatOptions interface provides a range of configuration options that allow you to customize the appearance and functionalitie of the IQ chat component. These options help tailor the chat experience to fit specific use cases by controlling elements such as welcome messages, translations, interaction options, and whether to display charts or text summaries. The table below provides a detailed overview of each configurable parameter and its purpose.

| Property | Type | Description | |-------------------------------|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | areChartActionsEnabled | boolean | Determines whether users should be allowed to trigger chart actions that enable them to explore further insights based on the given chart type. | | areWelcomeMessagesVisible | boolean | Specifies whether to display the welcome messages at the chat start. | | chartTheme | ItemThemeConfig | Defines theme settings for the charts displayed in the component. | | chatWidgetHorizontalOffset | number | Specifies the horizontal offset for the chat widget overlay position in relation to the chat button. | | chatWidgetOverlayPosition | string | Defines the position of the chat widget overlay in relation to the chat button. | | chatWidgetPosition | ConnectedPosition[] | Defines the customized configuration of the chat widget overlay position. | | chatWidgetTitle | string | The chat title to be displayed at the top of the chat container. | | chatWidgetVerticalOffset | number | Specifies the vertical offset for the chat widget overlay position in relation to the chat button. | | disclaimerText | string | Defines the disclaimer text to be displayed if enabled. Uses a default message if not specified. | | displayMode | string | Configures the appearance of the chat component as either 'chatWidget' or 'fullChat'. | | initialSuggestions | IQSuggestion[] | Predefined questions displayed at chat start, sent to the AI service upon click. | | isChartConfigurationEnabled | boolean | Specifies whether users can configure charts via the chart configuration panel. | | isChartExportEnabled | boolean | Specifies whether users can export charts as PNGs. | | isChartFeedbackEnabled | boolean | Enables feedback, allowing users to rate responses and suggest corrections. | | isConversationIdVisible | boolean | Displays the conversation ID for reporting or feedback purposes. | | isDisclaimerVisible | boolean | Determines if the disclaimer text is shown in the chat. | | locale | string | Specifies the locale for localizing text elements and chart configurations.Accepts values: "de", "en", "es", "fr", "it", "ja", "nl", "no", "pt", "ru", "sv", "tr". | | messages | IQMessage[] | An array of processed messages to display, following the IQMessages interface. | | responseMode | string | Specifies the response format as 'chart', 'text', or 'mixed'. | | timezone | string | Specifies the timezone for displaying timestamps in charts. | | welcomeMessages | IQMessage[] | Array of welcome messages displayed at chat start. |

IQ answer component

The IQAnswerOptions interface allows to customize the appearance and functionality of the IQ answer component. These options help define whether certain elements, such as charts, text summaries, or feedback panel, are displayed to users. The table below provides a detailed overview of each configurable parameter and its purpose:

| Property | Type | Description | |-------------------------------| ------------------------------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | areChartActionsEnabled | boolean | Determines whether users should be allowed to trigger chart actions that enable them to explore further insights based on the given chart type. | | isChartConfigurationEnabled | boolean | Specifies whether users should be able to configure charts with the chart configuration panel. | | isChartExportEnabled | boolean | Specifies whether users can export charts as PNGs. | | isChartFeedbackEnabled | boolean | Specifies whether the feedback mechanism should be displayed, allowing users to rate AI responses and suggest chart corrections. | | locale | string | Specifies the locale used for component interactions, including localization of text elements like welcome messages, responses, and chart configurations. | | responseMode | string | Defines the response mode for the answer component: 'chart', 'text', or 'mixed' (default). 'chart' shows AI responses as charts only, 'text' shows only text summaries, and 'mixed' displays both. | | chartTheme | ItemThemeConfig | Specifies the theme settings for customizing the appearance of charts displayed in the component. |

CSS Variables

The following CSS variables can be used to customize various aspects of the IQ components. They are grouped based on their functionality, such as general styling, chat appearance, bubble styles, messages, and feedback.

General Styling

These variables control the overall appearance of elements like borders, background colors, font sizes, and spacing.

--luzmo-iq-border-color: rgba(0,0,0,.1);          /* Border color */
--luzmo-iq-border-radius: .5rem;                  /* Standard border radius */
--luzmo-iq-border-radius-lg: .75rem;              /* Large border radius */
--luzmo-iq-border-radius-xl: 1rem;                /* Extra-large border radius */
--luzmo-iq-border-radius-full: 999rem;            /* Full (circle) border radius */
--luzmo-iq-border-width: 1px;                     /* Standard border width */
--luzmo-iq-background-color: #ffffff;             /* Default background color */
--luzmo-iq-background-hover-color: #f8fafc;       /* Background color on hover */
--luzmo-iq-background-active-color: #f1f5f9;      /* Background color when active */
--luzmo-iq-font-size: .875rem;                    /* Default font size */
--luzmo-iq-font-weight: 400;                      /* Standard font weight */
--luzmo-iq-font-color: #333;                      /* Default font color */
--luzmo-iq-spacing-1: .125rem;                    /* Small spacing */
--luzmo-iq-spacing-5: 1rem;                       /* Large spacing */

Messages Styling

These variables define the appearance of both human and system messages in the chat.

--luzmo-iq-human-message-background: blue;        /* Default background color for human messages */
--luzmo-iq-human-message-color: white;            /* Default text color for human messages */
--luzmo-iq-system-message-background: rgb(226, 232, 240); /* Default background for system messages */
--luzmo-iq-system-message-color: #333;            /* Default text color for system messages */

State Loader and Spinner Styling

These variables are used for customizing the appearance of state loaders and spinners within the chat component.

--luzmo-iq-spinner-color: magenta;                /* Default spinner color */
--luzmo-iq-spinner-border-width: .125rem;         /* Default spinner border width */
--luzmo-iq-spinner-opacity: .5;                   /* Default spinner opacity */
--luzmo-iq-state-loader-background: #778393;      /* Default background color of the loader */
--luzmo-iq-state-loader-color: #333;              /* Default text color for the loader */

Feedback and Ratings

These variables control the appearance of feedback icons and rating elements.

--luzmo-iq-positive-feedback-icon-hover-color: rgb(20, 120, 63); /* Default hover color for positive feedback */
--luzmo-iq-negative-feedback-icon-hover-color: rgb(216, 64, 64); /* Default hover color for negative feedback */
--luzmo-iq-rating-icon-size: 1rem;                /* Default size of the rating icons */
--luzmo-iq-info-icon-size: 1rem;                  /* Default size of the info icons */

Tooltips

These variables are used to adjust the appearance of tooltips.

--luzmo-iq-tooltip-background-color: #000;     /* Tooltip background color, defaults to #000 (black) */
--luzmo-iq-tooltip-color: #fff;                /* Tooltip text color, defaults to #fff (white) */
--luzmo-iq-tooltip-font-size: 0.8125rem;       /* Tooltip font size, defaults to 0.8125rem */

Changelog

• Changelog

Migration

Migrating from cumul.io to luzmo.

• Change import '@cumul.io/ngx-cumulio-dashboard to import @luzmo/ngx-embed.
• Change NgxCumulioDashboardModule to NgxLuzmoDashboardModule.
• Replace all references of Cumulio with Luzmo.
• Replace all references of cumulio-dashboard to luzmo-dashboard

Compatibility

Angular version compatibility, please select the compatible version of the library from the table below.

| @luzmo/ngx-embed | Angular | |------------------|---------| | ➤6.X.X | 16.X.X | | ➤6.0.4 | 17.X.X | | ➤6.2.0 | 18.X.X |

This library requires Angular version 16 and above.

| Angular | |-------------------------------------| | 16.0.0 |

For Angular version < 16.0.0 please use our old library

Quick links

Luzmo | Sample Integration | Migration | Changelog