# Beginner's Guide to Sisense BloX with Actions

> Sisense BloX enables you to build custom, interactive widgets. This article explains a simple BloX widget line-by-line, and introduces how to add interactive actions like buttons and popups.

*Source: https://docs.sisense.com/main/SisenseLinux/blox-intro.htm*

---

Last updated: June 10, 2026

|  |  |  |
| --- | --- | --- |
| [Tier](https://www.sisense.com/pricing/#pricing) | [Deployment](https://docs.sisense.com/main/SisenseLinux/introduction-to-sisense-cloud-managed-services.md#ComparisonofManagedCloudandSelfHosted) | [Availability](https://docs.sisense.com/main/SisenseLinux/l2026-2-release-notes.md#ClassicMode) |
| Enterprise | Cloud     On-Prem | Classic Mode Only |

Sisense supports building custom interactive widgets for your dashboard using Sisense BloX. This section describes the components of a BloX widget, illustrating how to add interactive elements such as popups and dropdowns.

## Prerequisites

Before proceeding, a working knowledge of the following is recommended:

- JavaScript: for implementing custom actions and controlling widget logic
- CSS: for defining styles and modifying widget appearance
- HTML: for understanding the DOM structure and working with widget templates

## Creating a BloX Template

1. From the dashboard, click ![+widget blue](https://docs.sisense.com/main/Resources/Images/+widget-blue_85x31.png) > **Advanced Configuration**. The widget editor opens.

   ![Blox advanced config](https://docs.sisense.com/main/Resources/Images/blox-advanced-config.png)
2. Change the widget type to **BloX** (top left-hand corner). The template editor opens and displays the JSON structure.

   ![Blox template editor](https://docs.sisense.com/main/Resources/Images/blox-template-editor_942x393.png)

The Sisense BloX Template Editor contains the following key elements:

- **Editor:** Used to write and modify the JSON structure that defines the layout and behavior of the widget.

  - Creating widget layout `(components)`
  - Adding styles
  - Referring to `actions`
  - Using data via `{{value}}` syntax
- **Configuration:** Create custom, reusable input fields (like drop-downs, text boxes) to customize a BloX widget without editing code. This includes:

  - Making BloX reusable with custom settings
  - Enabling users to change text, color, or fields without modifying the code
  - Dynamic customization
- **Snippets:** A collection of pre-built mini templates or code blocks (e.g. JSON) that can be inserted into the Editor. They allow UI components to be built quickly while reducing syntax errors.
- **Actions:** Define custom action handlers (JavaScript functions that can be called from the widget). They are used to create buttons and logic, call APIs, and apply filters. These include:

  - Alert popups
  - HTTP requests
  - Dynamic interaction logic
  - Accessing `$context` for filters and metadata

## BloX Widget Components

|  |  |
| --- | --- |
| `"style"` (Optional) | The “style” parameter defines the widget's overall CSS style. It can be used to change the look and feel of the widget including the background, border, and padding. |
| `"title" and "titleStyle"` (Optional) | The “title” and “titleStyle” parameters define the widget’s title and the title’s appearance. |
| `"script"`  (for Custom Actions) | The “script” parameter defines JavaScript functions for buttons that use a custom "action" name. It can be used to trigger a popup or execute a procedure based on user interaction such as clicking. |
| `"actions"` | In BloX widgets that consist of multiple built-in procedures, the “actions” parameter is used to configure built-in Sisense actions (such as filtering and navigation). |
| `"data"`  (Optional) | The “data” parameter passes dynamic text from Sisense to BloX, including user name and KPIs.  **Note:**  The data must be offset with double curly braces: {{value}}. |
| `"components"`  (REQUIRED) | The “components” parameter defines what elements are visible in the widget (e.g. text, buttons, images). |

Note:

BloX does not support comments in the main or configuration sections (JSON). Comments can be added within custom actions (JavaScript) using standard commenting syntax.

## Debugging the Full BloX Editor Session

The BloX editor can be used to debug BloX code when configuring custom actions, data input mappings, or dynamic template conditions.

To debug BloX code:

1. Enable Chrome DevTools:

   1. Open the BloX widget in the BloX editor.
   2. Press F12 or right-click and select **Inspect** to launch Chrome DevTools.
   3. Open the **Console** tab.
2. Insert debugging statements:

   To inspect values or pause execution, add `console.log()` or `debugger;` statements in the following areas:

   - **My Actions:** to track custom JavaScript behavior.
   - **Data Input Mappings:** to verify incoming values and context.
   - **Dynamic Template Conditions:** to log or break on logic that controls visibility or styling.
3. Preview and interact:

   - Use the Live Preview in the BloX editor (or test via a dashboard).
   - Interact with the widget to trigger your custom logic.
   - Monitor the Console tab for real-time logs or execution pauses if `debugger;` is used.

### Additional Resources

For deeper insights and examples, refer to the [Mastering Custom Actions in Sisense](https://community.sisense.com/kb/troubleshooting/mastering-custom-actions-in-sisense-debugging-and-understanding-payload-properti/25815).

## BloX Code Examples

### Alert Button: Display Popup Message

To create a button that triggers a popup alert:

1. In the Editor section of BloX, enter the following code.

[Copy](javascript:void(0);)

```
{  
   "title": "Button Test",  
   "body": [  
       {  
           "type": "TextBlock",  
           "text": "❤️ Welcome to Blox ❤️",  
           "style": {  
               "text-align": "center",  
               "font-size": "22px",  
               "margin": "30px"  
           }  
       }  
   ],  
   "actions": [  
       {  
           "type": "showMessage",  
           "title": "Click me!",  
           "opts": {  
               "message": "❤️ I think you are ❤️"  
           }  
       }  
   ]  
}
```

![Blox editor section](https://docs.sisense.com/main/Resources/Images/blox-editor-section.png)

1. From the **Actions** tab, click ![More options (three dots) icon](https://docs.sisense.com/main/Resources/Images/3_dots.png) > **Edit Action**.

   ![Blox edit actions](https://docs.sisense.com/main/Resources/Images/blox-edit-actions.png)
2. Update the action snippet as follows:

   [Copy](javascript:void(0);)

   ```
   const { message } = payload.opts;  
   alert(message)
   ```
3. Click **Next**.

   ![Blox next](https://docs.sisense.com/main/Resources/Images/blox-next.png)
4. Click **Create**.

   ![Blox create button](https://docs.sisense.com/main/Resources/Images/blox-create-button.png)
5. In the BloX widget, click **Apply**.

   ![Blox apply button](https://docs.sisense.com/main/Resources/Images/blox-apply-button.png)
6. Click **Are you having fun?** to test your widget.

   ![Blox fun button](https://docs.sisense.com/main/Resources/Images/blox-fun-button.png)

   The following message appears:

   ![Blox popup message](https://docs.sisense.com/main/Resources/Images/blox-popup-message.png)

### Dynamic Drop-down Filter

Use the Dynamic Drop-down Filter to filter results using a drop-down menu.

The filter creates a drop-down list using values from a specified field, allowing users to refine the dashboard data. It can be used to filter by categories such as brand or region.

Add the following code to the Editor section of BloX:

[Copy](javascript:void(0);)

```
{  
  "showCarousel": true,  
  "carouselAnimation": {  
    "delay": 0,  
    "showButtons": false  
  },  
  "body": [  
    {  
      "type": "Container",  
      "style": {  
        "justify-items": "center",  
        "align-items": "center"  
      },  
      "items": [  
        {  
          "type": "TextBlock",  
          "spacing": "medium",  
          "size": "large",  
          "text": "Select a Specialty",  
          "style": {  
            "text-align": "center",  
            "font-weight": "600"  
          }  
        },  
        {  
          "type": "Container",  
          "spacing": "small",  
          "items": [  
            {  
              "type": "Input.ChoiceSet",  
              "id": "data.filters[0].filterJaql.members[0]",  
              "displayType": "compact",  
              "style": {  
                "align-self": "center"  
              },  
              "choices": "{choices:Specialty}"  
            }  
          ]  
        }  
      ]  
    }  
  ],  
  "actions": [  
    {  
    "type": "Filters",  
      "title": "Apply",  
      "data": {  
        "filters": [  
          {  
            "panelName": "Specialty",  
            "filterJaql": {  
              "explicit": true,  
              "members": [""]  
            }  
          }  
        ]  
      }  
    },  
    {  
      "type": "Filters",  
      "title": "Clear",  
      "data": {  
        "filters": [  
          {  
            "panelName": "Specialty",  
            "filterJaql": {  
              "explicit": true,  
              "all": true  
            }  
          }  
        ]  
      }  
    }  
  ]  
}
```

To select the dataset to be used for the dropdown menu:

In the lefthand panel, click the plus icon and add the field or fields to be used to populate the dropdown menu.

![Blox dropdown with code](https://docs.sisense.com/main/Resources/Images/blox-dropdown-with-code.png)

At the top of the editor, click Apply. The new widget appears on the dashboard.

![Blox dropdown](https://docs.sisense.com/main/Resources/Images/blox-dropdown4.png)

**Note:**

The dashboard filters do not affect the widget.