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' }
},
}
Attribute |
Format |
Description |
---|---|---|
workbook.variables | Object |
The variables applied to the workbook with the format { ‘Variable Name’: ‘value1’, ‘Variable Name2’: ‘value2’ } Note that the values are URL encoded. Please see Workbook Controls in the URL for examples on how the values are encoded for the URL. |
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:
Data types: Date | boolean | number | string | null
-
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.
Data types: Date | boolean | number | string | null
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.
Unique to pivot table returns is the Column and Row path keys, which return objects containing an object with "name" and "value" keys.
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