JavaScript Events for Embedded Elements

This document describes how your application’s client can interact with its iframe through JavaScript actions and events. 

After you generate an embed URL, your application’s client can interact with its iframe through JavaScript actions and events. Events allow the client to listen for variable updates that it can then use to take actions, such as passing control values to different embeds or from one of your application’s widgets to an embed.

You can use the Embed Selection API to gain insights into the types of elements and corresponding values that your users click on. These insights can help organizations to understand which workbook elements users frequently engage with. 

Summary of Content

Requirements
Accessing Events
Workbook Events
     workbook:loaded
     workbook:variables:onchange
     workbook:table:oncellselect
     workbook:pivottable:oncellselect
     workbook:chart:onvalueselect
Update Controls in Sigma
     Actions
Related Resources

Requirements

Only organization Admins can generate application embed links; see Account types.

Value Types

All the data values returned by the API can be boolean for true/false, number for numeric, string for text, null for empty values, or Date for dates and timestamps.

Use the following type:

type Value = Date | boolean | number |string | null;

Accessing Events in JavaScript

Example of listening for Sigma JavaScript events:

window.addEventListener('message', function (event) {
  if (
    event.source === document.getElementById('sigma-iframe').contentWindow &&
    event.origin === "https://app.sigmacomputing.com"
  ) {
    console.log(event.data);
  }
});

Example 2 of Sigma listening events:

window.addEventListener('message',
(message) => message.data.source !== 'react-devtools-bridge' &&
console.log(message.data))

Workbook Events

All clicks on non-control elements such as dropdown selection, date pickers and page tabs contain the following properties:

• Type - The name of the event, all possible types listed below.
• NodeID - The ID of the element that's clicked.
• Title - The name of the element as displayed in Workbook.

workbook:loaded

This event is created when a workbook has finished loading the metadata but has not started evaluating the workbook elements.

{
  type: 'workbook:loaded',
  workbook: { variables: encodedVariables },
}

workbook:variables:onchange

This event is triggered whenever a control/variable has been updated within Sigma’s iframe through user interaction.

{
  type: 'workbook:variables:onchange',
  workbook: {
    variables: {'Variable1': 'value1', 'Variable 2': 'value2' }
  },
}

workbook:table:oncellselect

This event is created when a user clicks a cell or shift+clicks multiple cells in a table. In addition to the Type, NodeId, and Title, an Array of objects Cells is returned, each of which contain their own Objects with the following Key Value pairs:

• type: 'valueCell', 
• value: Value, The value present in the cell. 
• columnName: string, The name of the column this cell belongs to.
• underlyingData- Specific to groupings & aggregations in tables. This returns an array of rows that constitute the aggregate values and contains a maximum of 1000 rows (postMessage protocol limitation).

  You can't collapse the table to access underlyingData.

  underlyingData: {
            rows: Record<string, number | string>[],  An array of data objects, truncated up to 100 rows.
              isTruncated: boolean, Truncation flag set to true if the data associated with the selected cell is truncated.
             length: number, Total number of underlying rows that constitute the grouping.

Example

In the example below, a user selects the highlighted cell ("Sum Of Revenue" for Order #205).

When Sum Of Revenue for Order #205 is selected, it returns the example below. 

{
  "type": "workbook:table:oncellselect",
  "nodeId": "E7euUNfE_f",
  "title": "PLUGS_ELECTRONICS_HANDS_ON_LAB_DATA",
  "cells": [
    {
      "cellType": "valueCell",
      "columnName": "Sum of Revenue",
      "value": 1464.9658944658945,
      "underlyingData": {
        "rows": [
          {
            "Cust Key": 548,
            "CountDistinct of Order Number": 205,
            "Order Number": "SO43659",
            ...
          },
          ...
        ],
        "length": 6,
        "isTruncated": false
      }
    }
  ]
}

workbook:pivottable:oncellselect

Similar to the "Table - OnCellSelect", this event is triggered when a user clicks a cell in a Pivot Table. In addition to the Type, NodeId, and Title, an Array of objects Cells is returned, each of which contain their own Objects with the following Key Value pairs.  

• type: 'valueCell' | 'total' | 'columnHeader' | 'rowHeader'
• value: Value,
• columnName: string The column used in the "value" section of the pivot.
• rowPath: Array<Record<string, string>> | null, The rows this cell is grouped under.
• columnPath: Array<Record<string, string>> | null The columns this cell is grouped under.

Example

In the example below, the user clicks on the highlighted cell. 

When the highlighted cell is clicked, it returns the following.

{
"type": "workbook:pivottable:oncellselect",
"nodeId": "jgkdT5k0i6",
"title": "New Pivot Table",
"cells": [
 {
 "cellType": "total",
 "value": 449053,
 "columnPath": [
   {
   "value": "2020-01-01T00:00:00.000Z",
   "name": "Year of Date"
   }
  ],
  "columnName": "Number of items In Stock",
  "rowPath": [
   {
   "value": "Total",
   "name": "Product Type"
   }
  ]
 }
]
}

workbook:chart:onvalueselect

The chart OnValueSelect event is triggered when a user clicks a component of a chart such as a bar or slice of a pie. In addition to the Type, NodeId and Title, a “values” object is returned which contains Key Value Pair for the Axis and Value selected.

• type ColumnLabel = string;
• type ChartValue = Record<ColumnLabel, number | string | null>;

Unique to pivot table returns are the Column and Row path keys, which return objects containing an object with "name" and "value" keys.

Example

In the example below, a user clicks on the 2021-10 column. 

When the highlighted column is selected, it returns the following. 

{
  "type": "workbook:chart:onvalueselect",
  "nodeId": "GPGvodn8I6",
  "title": "Revenue by Quarter",
  "values": [
   {
    "Quarter of Date": "2021-10-01T00:00:00.000Z"
   }
     ]
}

Update Controls in Sigma

You can update controls within an iframe by posting a message to the iframe contentWindow.

const sigma_iframe = document.getElementById('sigma-iframe');
sigma_iframe.contentWindow.postMessage(
  {
     type: 'workbook:variables:update',
     variables: { 'Variable1': 'value1', 'Variable 2': 'value2' },
   },
   'https://app.sigmacomputing.com',
);

You can post the workbook:selectednodeid:onchange message to change which element or page is selected in the workbook.

const sigma_iframe = document.getElementById('sigma-iframe');
sigma_iframe.contentWindow.postMessage(
  {
    type: 'workbook:selectednodeid:onchange';
    selectedNodeId: string | null;
  },
  'https://app.sigmacomputing.com',
);
 

Actions

workbook:variables:update

This action updates the current control values within the iframe’s workbook. It is not available for hidden controls.

{
  type: 'workbook:variables:update',
  variables: { 'Variable1': 'value1', 'Variable 2': 'value2' },
}

Related Resources

Workbook Embedding: An Overview
Application Embedding
Public Embedding
Private Embedding
Workbook Controls in the URL
Hidden Controls in Workbooks