Implement actions and events in embeds

Actions and events enable seamless interactions in embedded solutions by facilitating communications between the embedded content and the host application. For example, when a user clicks an object in the host application, a JavaScript action can enable the embedded Sigma content to display different information.

This document introduces actions and events and provides examples demonstrating how to use them in Sigma embeds.

📘

Because you can use a variety of methods to implement actions and events, and you may have unique integration requirements, this document doesn't provide step-by-step guidance on implementing actions and events in embeds. Instead, it highlights examples that can provide helpful context that you can leverage as you develop your own approach.

Embed actions

Embed actions are mechanisms through which the host application communicates with the Sigma embed. Essentially, they are variables or commands that Sigma processes and responds to by dynamically modifying control values.

Sigma supports two methods of communicating actions:

• JavaScript: Typically utilized to send data from the host application to the embedded content without refreshing the embed. This method enables a more interactive and responsive user experience.
• URL: Primarily utilized at runtime to append variable values directly to the embed URL. This method is ideal for initializing the embed with specific parameters.

Both methods offer flexibility in the transmission of actions, allowing your embedded solution to accommodate different scenarios and requirements.

Example embed action: Update controls in Sigma

The following example script demonstrates a method of communicating information from the host application to the iframe of the embedded Sigma content. It utilizes the postMessage method to enable communication and allows the host application to send messages directly to the iframe's contentWindow to specify action type and variables to update.

The target origin https://app.sigmacomputing.com enhances security by ensuring the message reaches by the intended recipient.

// Get the Sigma iframe element from the document
const sigma_iframe = document.getElementById('sigma-iframe');  

// Post a message to the Sigma iframe's content window
sigma_iframe.contentWindow.postMessage(  
  {  
    // Specify the type of action to perform
    type: 'workbook:variables:update',  

    // Define the variables to update in Sigma, with their new values
    variables: { 'Variable1': 'value1', 'Variable 2': 'value2' },  
  },  

  // Provide the target origin for where the message should be accepted
  'https://app.sigmacomputing.com',  
);

🚧

This example action updates control values currently displayed in the embedded content. It does not apply to hidden controls.

Example embed action: Change the selected element or page

The following example snippet demonstrates how to programmatically change the selected element or page within an embed. It utilizes the postMessage method to enable communication and allows the host application to send messages that specify the workbook:selectednodeid:onchange action type and ID of the node to select (the string placeholder value would be replaced with null or an actual node ID).

The target origin is provided to ensure the message is sent to the correct domain.

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

Embed events and listeners

What are embed events and listeners?

Embed events are messages the embedded Sigma content communicates to the host application to provide updates about interactions or changes applied to the content within Sigma. JavaScript event listeners must be implemented for the host application to detect and respond to embed events. This facilitates the interactivity between the host application and Sigma embed.

Example embed event: Basic event listener

This first example demonstrates how an event listener can be added to the window object. The listener checks for event messages sent by the Sigma embed and logs the event data.

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

Example embed event: Filter specific event messages

This second example demonstrates how to filter out unrelated event messages (for example, from React DevTools).

window.addEventListener('message', (message) => {
  // Filter out messages not related to Sigma
  if (message.data.source !== 'react-devtools-bridge') {
    console.log(message.data);
  }
});

Workbook events

Workbook events are communications about user interactions with embedded Sigma content. They include specific properties about the interaction that allow the host application to process and respond accordingly. It's important to understand these properties to effectively manage interactions and ensure a dynamic, interactive user experience.

Workbook event properties:

Available workbook event types

workbook:loaded

The workbook:loaded event occurs when a workbook's metadata has loaded, but the elements haven't been evaluated.

This event is crucial for scenarios in which an initial setup or a pre-processing step is required before the workbook becomes interactive. It provides an opportunity to implement any preparatory actions in the host application based on the workbook's metadata.

Event structure:

{
  type: 'workbook:loaded',
  workbook: {
    variables: encodedVariables // Contains workbook metadata
  },
}

workbook:variables:onchange

The workbook:variables:onchange event occurs when a user- or system-initiated update is applied to a control or variable within the embedded Sigma content.

This event is essential for situations where the host application needs to respond to changes within the embedded Sigma content.

Event structure:

{
  type: 'workbook:variables:onchange',
  workbook: {
    variables: { 'Variable1': 'value1', 'Variable 2': 'value2' } // Updated variable values
  },
}

Event attributes:

workbook.variables: Contains the variables updated within the workbook. The format follows the structure { 'Variable Name': 'value' }, with URL-encoded values.

This event provides critical information about user interactions with the embedded content, allowing for a dynamic and responsive integration within the host application. For detailed examples on how values are encoded for URLs, refer to Apply control values with URL parameters > Directly generate a URL.

workbook:table:oncellselect

The workbook:table:oncellselect event occurs when a user selects a cell or multiple cells in an embedded table. This event provides an array of selected cells and their properties.

Additional information included in the event:

Example scenario:

When a user selects a specific cell (for example, in the Sum of Revenue column) for a particular order, the event returns detailed information about the cell, including its value, column name, and any underlying data (if it's an aggregate value).

This event is crucial for applications that require responsive interaction with table data within Sigma, allowing the host application to tailor its response based on user selection in the embedded workbook.

workbook:chart:onvalueselect

The workbook\:chart\:onvalueselect event is specifically designed for user interactions with embedded visualization elements, like clicking data points in a bar chart. This event extends beyond the basic interaction details and includes a values object that provides insight about the specific chart component selected.

Additional information included in the event:

This event is crucial for applications that must respond to precise user interactions within embedded visualization elements. It offers a nuanced understanding of the chart component a user focuses on and analyzes.

Example scenario:

A user clicks on a specific bar in a bar chart. The event returns detailed information about that bar, including its category label and value. This enables the host application to provide context-specific responses or further data insights related to that precise interaction.