Viz Item Component Reference

This component can be used to create data visualizations in code using Luzmo's Flex SDK. By referencing your dataset and column identifiers and specifying which chart should show with with options, you can quickly create powerful data visualizations directly in your codebase. Below you can find all properties, events, and methods that are exposed by this frontend component.

⚠️

Note that the Flex SDK is not included by default in your Luzmo license. Please reach out to your contact person at Luzmo or support@luzmo.com to further discuss this if necessary!

ℹ️

If you're looking for an introduction to Luzmo's Flex SDK, take a look here .

Properties

All available properties can be seen in the code snippet below

index.html

Web component

Angular

React

React Native

Vue

<luzmo-embed-viz-item
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< Embed authorization key >"
  authToken="< Embed authorization token >"
  type="< type of chart >"
  options=" < options object >"
  slots="< slots array >"
  contextId="< string >"
  canFilter="all or an array of contextIds"
  dashboardId="< dashboardId >"
  itemId="< itemId >"
  filters="< filters object >"
  selectedData="< selectedData object>"></luzmo-embed-viz-item>

Below you can find a list of all available properties that you can (optionally) specify in the frontend component, together with their explanation and possible values:

Parameter	Description
appServer string	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost string	Tenancy of Luzmo API to connect to. Defaults to 'https://api.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://api.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey uuid	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken string	The authorization token from the response of the authorization request in your backend.
type string	The chart type to embed.
slots object	Slots property can be used to define which columns need to be queried for which slots of a widget. As the slots differ for different charts, you can find the available slots and their information on the respective chart documentation here.
options object	The Options object can be passed onto chart to modify how it looks and other optional settings.
contextId string	(Optional & Unique) contextId is used to filter items and is unique for each item.
canFilter string \| array	(Optional) String `all` or an array of contextIds `['context1', 'context2']`.
dashboardId string	(Optional) dashboardId of which the item belongs to, if this property is specified, it is necessary to specify itemId.
itemId string	(Optional) itemId of the item, if this property is specified, it is necessary to specify dashboardId.
filters object	(Optional) filters to be set on viz item can be passed as an object. (Accepted structure is either FilterGroup[] or the one returned by getFilters())
selectedData object	(Optional) selectedData usage can be used to set initialization filter on viz items.

Chart type

type property is a string with following values allowed.

area-chart , bar-chart , bubble-chart , box-plot , bullet-chart , choropleth-map , circular-gauge , circle-pack-chart , column-chart , combination-chart , conditional-number , date-filter , donut-chart , dropdown-filter , evolution-number , funnel-chart , heat-map , heat-table , hexbin-map , image , line-chart , marker-map , ohlc-chart , parallel-coordinates-plot , pivot-table , pyramid-chart , radar-chart , regular-table , route-map , sankey-diagram , scatter-plot , slicer-filter , slider-filter , speedometer-chart , spike-map , strip-plot , sunburst-chart , symbol-map , text , treemap-chart , video , wordcloud-chart

Slots and options

ℹ️

For a full reference of allowed slots and options per chart type, please refer to the specific chart docs .

Each chart has different allowed slots:

Chart type	Slots allowed
Area chart	x-axis, measure, legend
Bar chart	y-axis, measure, legend
Box plot	category, measure
Bubble chart	category, measure, color
Bullet chart	category, measure, target
Choropleth map	geo, measure, category
Circle pack chart	levels, measure
Circular gauge	measure, target
Column chart	x-axis, measure, legend
Combination chart	x-axis, measure
Date filter	time
Donut chart	category, measure
Dropdown filter	dimension
Evolution number	evolution, measure
Funnel chart	category, measure
Heat map	geo, measure
Heat table	x-axis, y-axis, measure
Hexbin map	geo, measure
Image	No slots supported
Line chart	x-axis, measure, legend
Marker map	geo, measure
OHLC chart	x-axis, open, high, low, close
Parallel coordinates plot	coordinates, color
Image	No slots supported
Pivot table	row, column, measure
Pyramid chart	y-axis, measure, legend
Radar chart	category, measure, legend
Regular table	columns
Route map	geo, order, legend, measure
Sankey diagram	source, destination, category, measure
Scatter plot	x-axis, y-axis, size, name, color
Slicer filter	dimension
Slider filter	slidermetric
Speedometer	target, measure
Spike map	geo, measure, color
Strip plot	y-axis, measure
Sunburst chart	levels, measure
Symbol map	geo, measure, category
Text	No slots supported
Treemap chart	category, measure, color
Video	No slots supported
Worldcloud chart	category, measure, color

selectedData usage

selectedData is used to set initial filters on chart (Sort of like user interacting with the chart and setting some filter.)

dashboard.html

Web component

Angular

React

React Native

Vue

  import { selectedDataUtils } from '@luzmo/embed';

  <!-- If the y-axis data is a hierarchy of countries, following command can be used to set Belgium and France as selected option in bar chart -->

  <luzmo-embed-viz-item
    type="bar-chart"
    selectedData=`'${selectedDataUtils.isIn('y-axis', ['Belgium', 'France'])}'`
  >
  </luzmo-embed-viz-item>

  <!-- If the y-axis data is of type datetime, following command can be used to set selected data to be between 2010-01-01 and 2010-01-02 in bar chart -->

  <luzmo-embed-viz-item
    type="bar-chart"
    selectedData=`'${selectedDataUtils.between('y-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])}'`
  >
  </luzmo-embed-viz-item>

  <!-- If the y-axis data is of type numeric, following command can be used to set selected data to be between 1 and 10 in bar chart -->

  <luzmo-embed-viz-item
    type="bar-chart"
    selectedData=`'${selectedDataUtils.between('y-axis', [1, 10])}'`
  >
  </luzmo-embed-viz-item>

selectData supported charts and operation supported

selectedDataUtils is exported from the library of your choice.

selectedDataUtils has 3 utility functions to help create data acceptable by selectedData.

typescript

const selectedDataUtils = {
  isIn(slotName: SlotName, value: string[] | number[], otherOptions?: any),
  between(slotName: SlotName, value: [string | number, string | number], otherOptions?: any),
  range(slotName: SlotName, value: [string | number, string | number], otherOptions?: any),
}

Chart type	Slot	Slot data type	Supported operation
area-chart	x-axis	hierarchy	`selectedDataUtils.isIn('x-axis', ['Belgium', 'France'])`
area-chart	x-axis	datetime	`selectedDataUtils.range('x-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
area-chart	x-axis	numeric	`selectedDataUtils.range('x-axis', [1, 10])`
bar-chart	y-axis	hierarchy	`selectedDataUtils.isIn('y-axis', ['Belgium', 'France'])`
bar-chart	y-axis	datetime	`selectedDataUtils.between('y-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
bar-chart	y-axis	numeric	`selectedDataUtils.between('y-axis', [1, 10])`
choropleth-map	geo	geo	`selectedDataUtils.isIn('geo', ['1778d050ca5ce22ea4a724546b3851fd' '1b574f7cefe80d526c7ef944a164dd16'])`
column-chart	x-axis	hierarchy	`selectedDataUtils.isIn('x-axis', ['Belgium', 'France'])`
column-chart	x-axis	datetime	`selectedDataUtils.between('x-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
column-chart	x-axis	numeric	`selectedDataUtils.between('x-axis', [1, 10])`
date-filter	time	datetime	`selectedDataUtils.range('time', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
dropdown-filter	dimension	hierarchy	`selectedDataUtils.isIn('dimension', ['Belgium', 'France'])`
dropdown-filter	dimension	datetime	`selectedDataUtils.between('dimension', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
donut-chart	category	hierarchy	`selectedDataUtils.isIn('category', ['Belgium', 'France'])`
donut-chart	category	datetime	`selectedDataUtils.between('category', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
donut-chart	category	numeric	`selectedDataUtils.between('category', [1, 10])`
dropdown-filter	dimension	numeric	`selectedDataUtils.isIn('dimension', [1, 10])`
line-chart	x-axis	hierarchy	`selectedDataUtils.isIn('x-axis', ['Belgium', 'France'])`
line-chart	x-axis	datetime	`selectedDataUtils.range('x-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z'])`
line-chart	x-axis	numeric	`selectedDataUtils.range('x-axis', [1, 10])`
slicer-filter	dimension	hierarchy / numeric	`selectedDataUtils.isIn('dimension', ['Belgium', 'France'])`
scatter-plot	x-axis, y-axis	hierarchy x numeric	`selectedDataUtils.merge( selectedDataUtils.isIn('x-axis', ['Belgium', 'France']), selectedDataUtils.range('y-axis', [10 , 70]) )`
scatter-plot	x-axis, y-axis	numeric x datetime	`selectedDataUtils.merge( selectedDataUtils.range('x-axis', [10, 70]), selectedDataUtils.range('y-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z']) )`
scatter-plot	x-axis, y-axis	datetime x hierarchy	`selectedDataUtils.merge( selectedDataUtils.range('x-axis', ['2010-01-01T00:00:00.000Z', '2010-01-02T00:00:00.000Z']), selectedDataUtils.isIn('y-axis', ['Belgium']) )`
slicer-filter	dimension	datetime	`selectedDataUtils.between('dimension', ['2010-01-01T00:00:00.000Z', '2010-01-01T00:00:00.000Z'])`
slider-filter	slidermetric	datetime / numeric	`selectedDataUtils.range('slidermetric', [1, 10])`

Example

Everything combined together will look something like this.

dashboard.html

Web component

Angular

React

React Native

Vue

<luzmo-embed-viz-item
  class="bar-chart"
  type="bar-chart"
  contextId="bar-chart-01"
  canFilter='["abcdef"]'
  authKey="<your_auth_key>"
  authToken="<your_auth_token>"
  selectedData="selectedDataUtils.isIn('y-axis', ['Asia'])"
  options='{
     "theme": "royale",
     "bars": {
       "roundedCorners": 7
     },
     "title": {
       "en": "Filtered by selectbox, area-chart and slicer"
     }
   }'
  filters='[
     {
       "condition": "or",
       "filters": [
         {
           "expression": "? in ?",
           "parameters": [
             {
               "columnId": "4c1eee0b-3a5f-41e1-820f-d09440784c67",
               "datasetId": "f6b55beb-8a92-4976-81fa-1aecc7b27e49",
               "level": 1
             },
             ["Europe", "Asia", "Africa"]
           ]
         }
       ]
     }
   ]'
  slots='[
     {
       "name": "y-axis",
       "content": [
         {
           "type": "hierarchy",
           "label": "Region",
           "columnId": "4c1eee0b-3a5f-41e1-820f-d09440784c67",
           "datasetId": "f6b55beb-8a92-4976-81fa-1aecc7b27e49"
         }
       ]
     },
     {
       "name": "measure",
       "content": [
         {
           "type": "numeric",
           "format": "$,.2s",
           "label": "Total cost",
           "aggregationFunc": "sum",
           "columnId": "88916a0d-b238-4d2a-af84-63f6121088e1",
           "datasetId": "f6b55beb-8a92-4976-81fa-1aecc7b27e49"
         }
       ]
     }
   ]'>
</luzmo-embed-viz-item>

Explanation of inputs for the above example

type="bar-chart" -> Type of viz item is bar-chart
contextId="bar-chart-01" -> contextId is a unique id assigned to viz item so it can be filtered upon.
canFilter='["abcdef"]' -> This viz item can filter viz items with contextId "abcdef"
options -> bars will have rounded corners and theme set to royale for the whole viz item.
filters -> Following filters will be passed to the viz item and will be sent along with the query
slots -> slots are passed onto viz items which specifies from which column and set to load data from.
selectedData -> Initial values to be selected after viz item is rendered.

Methods

The embed libraries offer some methods you can use to trigger actions on the viz item, or receive information/data from the viz item.

We currently provide the following methods:

setAuthorization

The setAuthorization method allows you to replace the Embed authorization token that is currently used to embed a viz item. This can be useful if the new Embed authorization token has different properties that should be taken into account in the viz item (e.g. different (initialization) filter values, different theme, etc.).

Replaces the authorization key & token of an embedded viz item when the button is clicked.

index.html

Web component

Angular

React

React Native

Vue

<body>
  <!-- -->
  <button id="set-authorization-button">Set authorization</button>
  <luzmo-embed-viz-item
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< Initial Embed Authorization key >"
    authToken="< Initial Embed Authorization token >"
    type="bar-chart"></luzmo-embed-viz-item>
  <!-- -->
  <script>
    // Get the button reference
    const setAuthorizationButton = document.getElementById('set-authorization-button');

    // Get the component reference
    // Note: only returns the first occurrence of a Luzmo component within the document.
    const vizItemComponent = document.querySelector('luzmo-embed-viz-item');

    // Add an event listener to the click event on the button
    setAuthorizationButton.onclick = () => {
      // Set the new Embed Authorization token via the setAuthorization method
      vizItemComponent.setAuthorization('< New Embed Authorization key >', '< New Embed Authorization token >');
      vizItemComponent.refreshData();
    };
  </script>
</body>

You pass along a new Embed Authorization key and token pair as arguments to the setAuthorization method. After calling the function you will always want to call :

the refreshData method, if the queries of the viz item(s) should take the properties of the new Embed authorization token into account. This will trigger one viz item queries to be fired again.

⚠️

The setAuthorization method should not be used to set the initial authorization key-token pair when embedding a viz item, but only to replace the initially specified key-token pair (as set on the authKey and authKey properties of the Luzmo frontend component).

Parameter	Description
authKey string	The new Embed Authorization key (the `'id'` property in the response of the Embed Authorization request).
authToken string	The new Embed authorization token.

refreshData

The refreshData method is used to retrigger all queries of viz item without reloading the viz item itself . This is useful when e.g. the authorization has changed (by using setAuthorization ) the widget should use the new authorization token to query different data (e.g. filtered by a component from your application).

Refreshes the data when the button is clicked

The refreshData method returns no value .

index.html

Web component

Angular

React

React Native

Vue

<body>
  <!-- ... -->
  <button id="refresh-data-button">Refresh data</button>
  <luzmo-embed-viz-item
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< Embed Authorization key >"
    authToken="< Embed Authorization token >"
    type="bar-chart"></luzmo-embed-viz-item>
  <!-- ... -->
  <script>
    // Get the button reference
    const refreshDataButton = document.getElementById('refresh-data-button');

    // Get the component reference
    // Note: only returns the first occurrence of a Luzmo component within the document.
    const vizItemComponent = document.querySelector('luzmo-embed-viz-item');

    // Add an event listener to the click event on the button
    refreshDataButton.onclick = () => {
      // Refresh the data of all items using the refreshData method
      vizItemComponent.refreshData();
    };
  </script>
</body>

The refreshData method is used to refresh the data of of the current viz item.

getFilters

The getFilters method is used to get all active filters on the viz item . It can be useful when using bi-directional communication with an embedded viz item, e.g. if you'd like to enable your users to save the currently applied filters of an embedded viz item.

ℹ️

If your application should be aware of each filter change within an embedded viz item (e.g. a user selects "value 1" and "value 2" in a viz item): it might be interesting to set up an event listener to the changedFilters event instead of using the getFilters method.

Usage

Get all active filters when the button is clicked

index.html

Web component

Angular

React

React Native

Vue

<body>
  <!-- ... -->
  <button id="get-filters-button">Get active filters</button>
  <luzmo-embed-viz-item
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< Embed Authorization key >"
    authToken="< Embed Authorization token >"
    type="bar-chart"></luzmo-embed-viz-item>
  <!-- ... -->
  <script>
    // Get the button reference
    const getFiltersButton = document.getElementById('get-filters-button');

    // Get the component reference
    // Note: only returns the first occurrence of a Luzmo component within the document.
    const vizItem = document.querySelector('luzmo-embed-viz-item');

    // Add an event listener to the click event on the button
    getFiltersButton.onclick = () => {
      // Get all active filters using the getFilters method
      const filters = vizItem.getFilters();
    };
  </script>
</body>

The getFilters method does not have any arguments to specify.

Response

json

[
  {
    "id": "<auto_generated_filter_group_id>",
    "origin": "< 'filterFromVizItem', 'filterFromFilterItem', 'itemFilter', or 'global' >",
    "condition": "< 'and', or 'or' >",
    "filters": [
      {
        "expression": "< filter expression >",
        "parameters": [
          {
            "datasetId": "< dataset id >",
            "columnId": "< dataset column id >"
          },
          < filter value(s) >
        ],
        "properties": {
          "id": "<auto_generated_filter_id>",
          "origin": "< 'filterFromVizItem', 'filterFromFilterItem', 'itemFilter', or 'global' >",
          "type": "< 'having', or 'where' >",
          "itemId": "< dashboard item id (not available for filters with origin 'global')>"
        }
      }
    ],
    "subGroups": [
      // Filter groups within filter group
    ],
    "itemId": "< dashboard item id (not available for filter groups with origin 'global') >",
    "datasetId": "< dataset id (only available for filter groups with origin 'global') >"
  },
  ... // Other filter groups
]

The getFilters return an array value containing the active filters as objects .

Property	Description
id uuid	(Auto-generated) The UUID of the filter group.
origin string	The resource type from where the filter group originates from, either: "itemFilter": A static filter that has been set up on a viz item when designing the dashboard. Also called a chart filter. "global": A static filter that has been set up on a dataset when designing the dashboard. Also called a global filter (in side bar of the dashboard editor -> filters -> dashboard filters)..
condition string	The filter condition between the different filters in this group, either `and` or `or`.
filters array[object]	A list of the different filters in the filter group.
expression string	The filter expression of the filter that is applied. See this Academy article for a list of supported filter expressions per column type).
parameters array	The parameters of the filter. The first element in this array is an object containing the `datasetId`, `columnId`, and `level` (only for datetime and hierarchy columns) of the filter. The second element is the filter value itself. See this Academy article for the different values to expect for different filter expressions.
properties object	The properties related to the filter.
id uuid	(Auto-generated) The UUID of the filter.
origin string	The resource type from where the filter itself originates from, either: "filterFromVizItem": A runtime filter from a non-filter viz item (i.e. filter from an interactive chart widget). "filterFromFilterItem": A runtime filter from a filter viz item (i.e. from a 'Date filter', 'Slider filter', or '(Rank) Slicer filter' widget). "itemFilter": A static filter that has been set up on a viz item when designing the dashboard. Also called a chart filter. "global": A static filter that has been set up on a dataset when designing the dashboard. Also called a global filter (can be found in side bar of the dashboard editor -> filters -> dashboard filters).
type string	The filter type of the filter. Depending on the filter origin and expression, this would be either `having` or `where`.
itemId uuid	The id of the viz item where this filter originates from. Note: this is not available for filters with origin `global`. These filters do not originate from a specific viz item, and are instead applied on a dataset level (i.e. all viz items querying that dataset will be filtered by this filter).
subGroups array[object]	A list of the filter subgroups within this filter group. Each of these objects is a filter group itself.
itemId uuid	The id of the dashboard item where this filter group has been set up. Note: this is not available for filter groups with origin `global` (instead of an `itemId`, filter groups with origin `global` would contain a `datasetId` see property below). Such filter groups were not set up on a specific dashboard item, but on a dataset level in the dashboard editor (i.e. all dashboard items querying that dataset will be filtered by this filter group).
datasetId uuid	The id of the dataset where this filter group has been set up. Note: this is only available for filter groups with origin `global`.

getData

The getData method is used to get the data of the specific viz item as it is visualized in an embedded viz item (i.e. taking into account all active filters applied on this viz item).

Usage

Gets the data of a specific viz item when the button is clicked.

index.html

Web component

Angular

React

React Native

Vue

<body>
  <!-- ... -->
  <button id="get-data-button">Get viz item data</button>
  <luzmo-embed-viz-item
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< Embed Authorization key >"
    authToken="< Embed Authorization token >"
    type="bar-chart"></luzmo-embed-viz-item>
  <!-- ... -->
  <script>
    // Get the button reference
    const getDataButton = document.getElementById("get-data-button");

    // Get the component reference
    // Note: only returns the first occurrence of a Luzmo component within the document.
    const vizItemComponent = document.querySelector("luzmo-embed-viz-item");

    // Add an event listener to the click event on the button
    getDataButton.onclick = () => {
      // Get the data of a specific viz item
      const data = vizItemComponent.getData();
  </script>
</body>

Response

getData returns an array of the data points.

Below you can see an example of the response of getData on a line chart that visualizes the total clicks per year (for 2022 and 2023) per transaction type (Online and Offline).

Response

json

[
  [
    "2022-01-01T00:00:00.000Z",
    {
      "id": "Online",
      "name": {
        "nl": "Online",
        "fr": "En ligne",
        "en": "Online"
      },
      "color": "rgb(0,255,0)"
    },
    2010843
  ],
  [
    "2022-01-01T00:00:00.000Z",
    {
      "id": "Offline",
      "name": {
        "nl": "Offline",
        "fr": "Hors ligne",
        "en": "Offline"
      },
      "color": "rgb(255,0,0)"
    },
    1912666
  ],
  [
    "2023-01-01T00:00:00.000Z",
    {
      "id": "Online",
      "name": {
        "nl": "Online",
        "fr": "En ligne",
        "en": "Online"
      },
      "color": "rgb(0,255,0)"
    },
    5323286
  ],
  [
    "2023-01-01T00:00:00.000Z",
    {
      "id": "Offline",
      "name": {
        "nl": "Offline",
        "fr": "Hors ligne",
        "en": "Offline"
      },
      "color": "rgb(255,0,0)"
    },
    5093799
  ]
]

The getData method returns an array of arrays value , where each inner array contains the values of a specific data point in the viz item.

The actual data returned will depend on the specific viz item and slot configuration.

export

The export method is used to download a snapshot of the viz item in PNG format or export the data of the viz item in XLSX or CSV file.

Usage

Creates a PNG export of an embedded viz item when the button is clicked.

index.html

Web component

Angular

React

React Native

Vue

<body>
  <!-- ... -->
  <button id="export-button">Export</button>
  <luzmo-embed-viz-item
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< Embed Authorization key >"
    authToken="< Embed Authorization token >"
    type="bar-chart"></luzmo-embed-viz-item>
  <!-- ... -->
  <script>
    // Get the button reference
    const exportButton = document.getElementById('export-button');

    // Get the component reference
    // Note: only returns the first occurrence of a Luzmo component within the document.
    const vizItemComponent = document.querySelector('luzmo-embed-viz-item');

    // Add an event listener to the click event on the button
    exportButton.onclick = () => {
      // Call the export method
      vizItemComponent.export('png');
    };
  </script>
</body>

Response

The export will begin downloading when the export function is called.

The export method returns nothing. The downloaded file will be named export.png .

Events

The embed libraries emit events when certain actions in an embedded viz item take place. Below you can find more information about how to set up an event listener to these events, as well as details on each of the available events you can optionally listen to!

We currently expose the following events:

Listening to events

In the code example you can see how you can set up an event listener to listen to one or more of the desired events!

Setting up event listeners to all available viz item events.

index.html

Web component

Angular

React

React Native

Vue

<body>
  <!-- -->
  <button id="set-authorization-button">Set authorization</button>
  <luzmo-embed-viz-item
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< Initial Embed Authorization key >"
    authToken="< Initial Embed Authorization token >"
    type="bar-chart"></luzmo-embed-viz-item>
  <!-- -->
  <script>
    // Get the component reference
    // Note: only returns the first occurrence of a Luzmo component within the document.
    const vizItemComponent = document.querySelector('luzmo-embed-viz-item');

    // Add an event listener to the load event
    vizItemComponent.addEventListener('load', (event) => {
      // Do something after the viz item has loaded
    });

    // Add an event listener to the changedFilters event
    vizItemComponent.addEventListener('changedFilters', (event) => {
      // Do something if an interactivity filter in the viz item has changed
    });

    // Add an event listener to the itemsRendered event
    vizItemComponent.addEventListener('rendered', (event) => {
      // Do something after viz item is rendered
    });

    // Add an event listener to the exported event
    vizItemComponent.addEventListener('exported', (event) => {
      // Do something after a viz-item has been exported
    });

    // Add an event listener to the customEvent event
    vizItemComponent.addEventListener('customEvent', (event) => {
      // Do something if a custom event is thrown from a viz item
    });
  </script>
</body>

Event: load

The following payload will be included every time the 'load' event is emitted

Response

json

{
  "contextId": "< context id>",
  "locale": "language",
  "options": "{ options object }",
  "type": "load",
  "dashboardId": "< dashboard ID >",
  "itemId": "< item id >"
}

This event is emitted when a viz item has loaded (i.e. the viz item's resources have been retrieved, but the viz item still need to query data).

The emitted load event contains the following meaningful payload in the data property:

Property	Description
locale string	The locale in which the viz item has loaded. This Academy article goes into more detail about multi-lingual dashboards. ISO locale code Check the `ISO 639-1` column for allowed values.
type string	The type of the event, in this case `load`.
dashboardId UUID	The ID of the dashboard of which the viz item was loaded from.
itemId UUID	The ID of the viz item that has loaded.
contextId string	The `contextId` that was passed as input.
options object	The `options` object after being processed and upgraded.

Event: changedFilters

The following payload will be included every time the 'changedFilters' event is emitted, including the changed filter groups and all active filter groups in the viz item.

Response

json

{
  "origin": "< origin of filter change >",
  "changed": [{...}, ...],
  "filters": [{...}, ...],
  "type": "changedFilters",
  "item": "itemId"
}

This event is emitted each time an interactivity filter in a viz item has changed (e.g. a user selects "value 1" and "value 2" in a viz item). If the filter state of an embedded viz item should be known by your application, you should set up an event listener to the changedFilters event.

You can also programmatically retrieve the filter state of an embedded viz item using the getFilters() method.

The emitted changedFilters event contains the following meaningful payload:

Property	Description
origin string	The resource type from where the filter change originates from, either: "filterFromVizItem": A runtime filter from a non-filter viz item (i.e. filter from an interactive chart widget). "filterFromFilterItem": A runtime filter from a filter viz item (i.e. from a 'Date filter', 'Slider filter', or '(Rank) Slicer filter' widget).
changed array[object]	The list of filter groups that changed and caused this event to be emitted. More information about the different properties of the filter groups can be found in the response of the getFilters() method.
filters array[object]	The list of all active filter groups that are applied in this viz item. More information about the different properties of the filter groups can be found in the response of the getFilters() method.
item uuid	The ID of the viz item that caused this event to be emitted.
type string	The type of the event, in this case `changedFilters`

Event: rendered

The following payload will be included every time the 'rendered' event is emitted.

Response

json

{
  "type": "rendered",
}

This event is emitted when viz item has rendered (i.e. the data has been queried and visualized). It could be used to e.g. show a custom loader until the event is triggered, gather statistics on load times, etc.

The emitted rendered event contains the following meaningful payload in the data property:

Property	Description
type string	The type of the event, in this case `rendered`.

Event: exported

The following payload will be included every time the 'exported' event is emitted

Response

json

{
  "type": "exported",
  "itemId": "< viz item ID >",
  "exportType": "< viz item export type >"
}

This event is emitted when a viz item has been exported via:

The export button of a viz item.

The emitted exported event contains the following meaningful payload:

Property	Description
type string	The type of the event, in this case `exported`.
itemId UUID	The ID of the viz item that has been exported.
exportType string	The export type in which the viz item is exported: either `pdf`, `png`, `csv`, `csv-raw`, `xlsx`, or `xlsx-raw`.

Event: customEvent

Custom Events allow you to perform actions in your platform based on what a user has clicked in a viz item . This means you can re-use the item's selected data point in your platform , or even include additional data that is not shown in the viz item itself. You could for instance open a new viz item with extra information, filtered to the data point a user has clicked.

In the example shown above, the first custom event is used to open a modal in the parent application. Depending on the specific bar a user has clicked on, a the model will show more in-depth insights in another viz item filtered to the Category value of the bar ( this Academy article explains step-by-step how to set up your own drillthrough interactivity between dashboards) . Another custom event is used to redirect the user to another part of the parent application, where they can alter the campaign where the custom event originated from!

To set this up, you'll want to:

Create one or more custom events in your dashboard item(s) (see below).
Set up an event listener to listen to events of type customEvent .
Implement your desired interactivity and actionability , based on the emitted event payload of the embedded Luzmo dashboard!

ℹ️

The data emitted with a specific custom event takes into account any filters active on the given dashboavizrd item , which means these filters will directly affect what is emitted by the Custom Event.

ℹ️

Custom events are (currently) not supported in the following viz items:

Filter items (e.g. Date filter, Slicer filter, etc.)
Hexbin map
Heat map
Route map
Parallel coordinates
Strip plot
Radar chart

If you have any use-cases in mind where custom events on one of the viz item above would be useful, Don't hesitate to pass describe your use-case using the "Submit an idea" button on (our public Roadmap page)[ https://www.luzmo.com/roadmap ]!

Payload

Response

json

{
  "type": "customEvent",
  "data": {
    "event": "name_of_custom_event",
    "language": "en",
    "measure": {
      "value": 8305.960329,
      "formattedValue": "8.31k",
      "label": "Population density (per km²)"
    },
    "category": {
      "id": "Singapore",
      "value": "Singapore",
      "label": "Country"
    },
    "extraData": {
      "continent": {
        "value": {
          "id": "Asia"
        },
        "datasetId": "< dataset ID >",
        "columnId": "< continent column ID >",
        "aggregation": {
          "type": "min"
        }
      },
      "region": {
        "value": {
          "id": "East Asia & Pacific"
        },
        "datasetId": "< dataset ID>",
        "columnId": "< region column ID >",
        "aggregation": {
          "type": "min"
        }
      },
      "subregion": {
        "value": {
          "id": "South-Eastern Asia"
        },
        "datasetId": "< dataset ID>",
        "columnId": "< subregion column ID >",
        "aggregation": {
          "type": "min"
        }
      },
      "number_of_customers": {
        "value": 12054,
        "datasetId": "< dataset ID>",
        "columnId": "< name column ID >",
        "aggregation": {
          "type": "count"
        }
      }
    }
  },
  "itemId": "< viz item ID >"
}

A generic structure of a custom event message's data property, including some extra data properties. Note that the exact property names will depend on the specific viz item and custom events setup.

Response

json

{
  "type": "customEvent",
  "data": {
    "language": "< current viz item language, e.g. 'en' >",
    "<item-specific slot name>": {
      "value": < numeric value >,
      // The "formattedValue" for e.g. SI units would be "8.31k"
      "formattedValue": "< formatted value >",
      "label": "< slot column label >"
    },
    "<another item-specific slot name>": {
      // The "id" would be identical to the data value in your data source
      "id": "< data text value >",
      // If the data value is adapted via our hierarchy editor,
      // the adapted value would be exposed as "value".
      "value": "< hierarchy data text value >",
      "label": "< slot column label >"
    },
    // Other item-specific slots used in your viz item item
    // ...
    // Extra data as added in the Custom events configuration modal of the widget
    "extraData": {
      "<extra data property name>": {
        "value": {
          // The "id" would be identical to the data value in your data source
          "id": "< data text value >"
        },
        "datasetId": "< dataset ID >",
        "columnId": "< hierarchy-column ID >",
        "aggregation": {
          "type": "< 'min' or 'max' >"
        }
      },
      "<another extra data property name>": {
        "value": <numeric value>,
        "datasetId": "< dataset ID >",
        "columnId": "< column ID >",
        "aggregation": {
          "type": "count"
        }
      },
      "<another extra data property name>": {
        "value": <numeric value>,
        "datasetId": "< dataset ID >",
        "columnId": "< numeric-column ID >",
        "aggregation": {
          "type": "< 'rate' / 'weightedaverage' >",
          "columnId": "< denominator/weight column ID >",
          "datasetId": "< denominator/weight dataset ID >"
        }
      },
      // Any other extra data properties set up for this item's custom events.
      // ...
    },
    // The "event" name is defined in the dashboard editor,
    // and specific to dropdown element (i.e. custom event) the user clicked on.
    "event": "< custom event name >"
  },
  "itemId": "< dashboard item ID >"
}

The emitted event contains information about the viz item , the specific data point that was clicked on, as well as all extra data properties you set up in the custom events modal of that item.

The emitted customEvent event contains the following meaningful payload in the data property:

Property	Description
language string	The language in which the viz item has loaded. This Academy article goes into more detail about multi-lingual dashboards.
type string	The type of the event, in this case `customEvent`.
data object	The actual data that is emitted from the viz item. The event name, as specified in the 'Custom events' modal, will be included in its `name` property. The properties inside this data object are highly dependent on the specific viz item type, item slot(s) usage, and item slot(s) configuration; typically, you could expect properties that are named similar as the viz item's slot names (e.g. 'measure', 'category', 'x-axis', etc.). Next to that, it will include an `extraData` property that will contain all the extra data properties that were set up in the "Custom events" modal (see this Academy article). It's recommended to test your specific setup with an event listener on the `customEvent` event, and investigate its specific payload when emitted!
itemId uuid	The ID of the viz item that caused this event to be emitted.

Filters

Filters object that can be sent as an input has the follwing properties.

Property	Description
id string	Unique identifier for the filter group.
condition FilterOperators required	Logical condition used to combine filters within the group (e.g., 'and' or 'or'). Check out all allowed `FilterOperators`
filters array[object] required	Array of filters included in the group. Check out `Filter[]` structure.
subGroups array[object]	Array of nested filter groups within this group. subGroups are of type `FilterGroup[]`
origin Enum	The origin or context from which this filter group was created. Check out `FilterOrigin`
datasetId String	ID of the dataset associated with the filter group.
itemId String	ID of the item associated with the filter group.

Example

json

// FilterGroup[]
[
  {
    "condition": "or",
    "filters": [
      {
        "expression": "? = ?",
        "parameters": [
          {
            "columnId": "4c1eee0b-3a5f-41e1-820f-d09440784c67",
            "datasetId": "f6b55beb-8a92-4976-81fa-1aecc7b27e49",
            "level": 1
          },
          "Asia"
        ]
      }
    ]
  }
]

Filter

Property	Description
fromAuthorization Boolean	Indicates if the filter comes from an authorization context.
expression Enum required	The expression used for filtering. Check out allowed `FilterExpression`
parameters Array[Object] required	Parameters used for the filter expression. May include column IDs, dataset IDs, levels, and other values. `Parameters` is an `Array` of two values, first value is an `Object` which contains information about which dataset and column to apply the filter on, the second value is the actual filter value. Second value is the actual value to filter on, can be an array of values, a single value, depends on the expresion. Check out allowed `FilterParameters`
properties Object	Additional properties related to the filter, such as ID, ignored values, item ID, origin, and type. Filter properties has the following structure. `{ id?: string; ignore?: string[]; itemId?: string; viz?: string; origin?: FilterOrigin; type?: 'where' \| 'having'; }`

Example

json

// Filter
{
  "expression": "? = ?",
  "parameters": [
    {
      "columnId": "4c1eee0b-3a5f-41e1-820f-d09440784c67",
      "datasetId": "f6b55beb-8a92-4976-81fa-1aecc7b27e49",
      "level": 1
    },
    "Asia"
  ]
}

FilterParameters

Property	Description
columnId String required	Represents the ID of the column.
datasetId String required	Represents the ID of the dataset.
column_id String	Optional. Deprecated. Will be removed in the next major release. Use `columnId` instead.
dataset_id String	Optional. Deprecated. Will be removed in the next major release. Use `datasetId` instead.
level Number	Optional. Represents currently used level of a column (hierarchy or datetime) in a slot or filter. level for a datetime field can have the value ranging from 1 to 9. Which corresponds to `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second`, `millisecond` respectively. Different values of level will render to different date format on the chart. For example sepcifying 1 will render only the year part of the date column and so on. level for hierarchy columns depend on the branches of hierarchy.
lowestlevel Number	Optional. Lowest supported level of the column (for e.g. 9 in case of datetime). Value of 1 is symbolizes year and a Value of 9 symbolizes millisecond level.

FilterOperators

Property	Description
Value Enum	Represents logical operators used to combine filters. Allowed values are `'and'` \| `'or'`

FilterExpression

Property Description

Property	Description
Expression Enum	Represents different types of filter expressions that can be used in queries or data filtering. More info can be found in our Academy article. Allowed values are: `'?' = '?'` \| `'?' != '?'` \| `'?' in '?'` \| `'?' not in '?'` \| `'?' like '?'` \| `'?' not like '?'` \| `'?' starts with '?'` \| `'?' not starts with '?'` \| `'?' ends with '?'` \| `'?' not ends with '?'` \| `'?' < '?'` \| `'?' <= '?'` \| `'?' > '?'` \| `'?' >= '?'` \| `'?' between '?'` \| `'last_now'` \| `'to_date'` \| `'last_available'` \| `'last_completed'` \| `'next_now'` \| `'next_full'` \| `'WTD'` \| `'MTD'` \| `'QTD'` \| `'YTD'` \| `'?' is null'` \| `'?' is not null'`

FilterOrigin

Property	Description
Origin Enum	Represents the source or context from which the filter originated. Flex allows setting filters with origin `itemFilter` only. `itemFilter` are filters applied to a specific viz item. Allowed values are: `'filterFromVizItem'` \| `'filterFromFilterItem'` \| `'itemFilter'` \| `'global'`

Types

Following types are exported from the libraries.

index.ts

Web component

Angular

React

React Native

Vue

import {
  // region Filters
  Filter,
  FilterExpression,
  FilterOrigin,
  SelectedDataInput,
  FilterGroup,
  // endregion

  // region Common
  ExportType, // @deprecated, use DashboardExportType instead
  DashboardExportType,
  ItemData,
  // endregion

  // region VizItem
  VizItemOptions,
  VizItemSlots,
  VizItemType,
  // endregion

  //region VizItemPostMessage
  VizItemPostMessageLoadEvent,
  VizItemPostMessageRenderedEvent,
  VizItemPostMessageExportedEvent,
  VizItemPostMessageChangedFiltersEvent,
  VizItemPostMessageCustomEventEvent
  //endregion
} from '@luzmo/embed';

Did this page help you?

Yes