How to block widget queries until a required dashboard filter is selected [Linux]
Summary: In the article by Thalita Santos titled 'How to block widget queries until a required dashboard filter is selected,' a method is presented to enhance dashboard widgets' functionality. The solution uses the 'widgetbeforequery' event to prevent widgets from executing their data queries unless a required filter is selected, thereby avoiding incomplete or misleading results. Detailed steps are provided for implementing the script, tailored for Sisense L2026.1.1. The approach ensures users receive data only when a specific filter is applied, improving the contextual accuracy of the displayed information. The guide includes customizations and debugging tips, with a focus on ensuring the script's adaptability to different filter structures.
Introduction
This article explains how to prevent specific widgets from executing their data queries until the user has selected a value in a required dashboard filter. Without this control, widgets may load with incomplete or misleading results when a filter is left at "All" or has no selection.
The solution uses the dashboard.on('widgetbeforequery') event to intercept each widget's query before it runs. If the required filter has no specific value selected, the query is emptied and the widget title is updated to prompt the user to make a selection.
This is particularly useful for dashboards where certain widgets are only meaningful in the context of a specific filter value, for example, a report that should only display data for a selected brand, region, or department.
The solution is tested on Sisense L2026.1.1 and works for both cloud and on-premises deployments.
Step-by-Step Guide
1. Open the dashboard script editor
From your dashboard, click the Edit button → open the Script tab (dashboard-level script, not widget-level).
2. Identify the widgets to protect
Each Sisense widget has a unique ID (OID). To find a widget's OID:
Open the dashboard in edit mode.
Click on the widget → open its script editor or inspect the URL/network request.
Copy the OID — it is a 24-character hexadecimal string (e.g. 69cd7ac30a2c1ca15a29c174).
You can also get this value from the URL when inside the widget editing.
Add all target widget OIDs to the targetWidgetIds array in the script.
3. Identify the required filter name
The script matches the filter by its jaql.title value — the internal field name Sisense uses, which may differ from the display label shown on the dashboard. To find the exact value:
Temporarily leave the console.log line active in the script (it is included by default):
Open your browser's developer console, reload the dashboard, and inspect the logged output.
Find the filter you want to require and note the value of its jaql.title property.
Use that exact string as the value of requiredFilterName.
4. Paste the full script
dashboard.on('widgetbeforequery', (d, args) => {
// Specify the title of the filter you want to require
const requiredFilterName = "Brand";
const targetWidgetIds = ["69cd7ac30a2c1ca15a29c174", "69cd7a670a2c1ca15a29c16e"];
if (!targetWidgetIds.includes(args.widget.oid)) {
return;
}
// Find the filter in the dashboard's filter collection
// Uncomment the lines below to identify the exact filter title value and structure, to adapt the code accordingly:
console.log('filters', d.filters.$$items)
let targetFilter = d.filters.$$items.find(
(filter) => filter?.jaql?.title == requiredFilterName
);
// If the filter is not set or "All" is selected, stop the query
if (targetFilter.jaql.filter?.members?.length == 0 || targetFilter.jaql.filter?.all) {
args.query.metadata = []; // Empty the query
// Optional: update the widget title to prompt the user
args.widget.title = "Please select a filter value for " + requiredFilterName + " to view data";
}
});5. Configure the script constants
At the top of the script, update the two configuration values to match your dashboard:
6. How the script works
The script hooks into the widgetbeforequery event, which fires for every widget on the dashboard just before its data query is sent. For each firing:
It checks whether the widget is in the targetWidgetIds list — if not, it exits immediately and the widget loads normally.
It searches the dashboard's filter collection (d.filters.$$items) for a filter whose jaql.title matches requiredFilterName.
It checks whether that filter has any specific members selected (members.length == 0) or whether "All" is selected (filter.all).
If no specific value is selected, it empties the widget's query metadata — preventing any data from loading — and optionally updates the widget title to guide the user.
7. Adapting the script to your filter structure
The console.log lines included in the script are intentional debugging helpers. Before going live, use them to inspect your filter's structure in the browser console and confirm:
That jaql.title matches your requiredFilterName exactly.
That the filter state is accessible via jaql.filter.members and jaql.filter.all (it can have a different structure depending on filter type).
If your filter uses a different structure (e.g. a hierarchical/cascading filter with a levels array), the lookup logic will need to be adapted accordingly. The logged output will make this visible.
8. Save and test
Once configured, comment out or remove the console.log lines, save the dashboard script, and reload the dashboard. The target widgets should display no data and show the prompt message when the required filter is set to "All" or has no selection. Once a specific filter value is chosen, the widgets will load their data normally.
Important notes
Important notes
Dashboard-level script only: This script must be placed in the dashboard script editor, not in an individual widget's script. The dashboard.on('widgetbeforequery') event is only available at dashboard level.
Flat filters only: This script is designed for standard, single-level filters where the field title is accessible via filter.jaql.title. If your filter is hierarchical (cascading), the filter structure will differ — use the console.log output to inspect it and adapt the lookup logic accordingly.
Finding the filter title: The requiredFilterName must match the internal jaql.title value exactly, including capitalisation and spacing. The console.log helpers are the most reliable way to verify this.
Widget OIDs: Each widget OID must be a 24-character hexadecimal string. Double-check these values — an incorrect OID means the widget will not be protected by the script.
Widget title change is optional: The line that updates args.widget.title is a helpful UX touch but is not required for the blocking logic to work. You can remove or customize the message to suit your dashboard's language and audience.
Multiple widgets: You can protect as many widgets as needed by adding their OIDs to the targetWidgetIds array. Widgets not in the list are completely unaffected.
Remove console logs before publishing: The console.log lines are useful during setup but should be commented out or removed before the dashboard goes live to avoid unnecessary browser console output.
Conclusion
By intercepting the widgetbeforequery event at dashboard level and checking the state of a required filter before each query runs, you can enforce a "filter-first" experience for any widget on your dashboard, ensuring users always see meaningful, contextually correct data rather than unfiltered results. The built-in console.log helpers make it straightforward to inspect your filter structure and adapt the script to your specific setup.
References / Related content
Disclaimer: This post outlines a potential custom workaround for a specific use case or provides instructions regarding a specific task. The solution may not work in all scenarios or Sisense versions, so we strongly recommend testing it in your environment before deployment. If you need further assistance with this, please let us know.
