Actions & Events
Actions and Events are used to interact with an embedded Cluvio dashboard from the outer application via JavaScript. Your application can send actions to the embedded Cluvio application to forward user input received through your own UI or to react to events received from the embedded dashboard. Your application can in turn receive events to react to changes in the embedded Cluvio application.
Actions
All actions are sent via window.postMessage to the embedded Cluvio window. The JSON message format for all actions is
{
"action": "<name-of-action>",
"params": { <params-of-action> }
}
whereby <params-of-action>
is a JSON object with action-specific parameters.
Use https://dashboards.cluvio.com
as the targetOrigin
parameter to
postMessage
.
Change Parameters
To change dashboard filter parameters, use the action changeParameters
.
The parameters aggregation
and timerange
are used for the built-in aggregation
and built-in timerange filters.
For example:
{
"action": "changeParameters",
"params": {"aggregation": "week", "timerange": "1686838280~1686838380"}
}
Parameters for custom filters must be
grouped together in the filters
parameter. For example:
{
"action": "changeParameters",
"params": {"filters": {"my_filter_a": "some value", "my_filter_b": 42}}
}
Download Image
To trigger an image download on the embedded dashboard or a single report,
use the action downloadImage
. The only optional parameter is a reportId
,
which must be a JSON string with the targeted Cluvio report ID.
For example, to trigger a dashboard image download:
{
"action": "downloadImage"
}
To trigger a report image download:
{
"action": "downloadImage",
"reportId": "vqkp-z5wz-oy56"
}
Download PDF
To trigger a PDF download on the embedded dashboard or a single report,
use the action downloadPdf
. The only optional parameter is a reportId
,
which must be a JSON string with the targeted Cluvio report ID.
For example, to trigger a dashboard PDF download:
{
"action": "downloadPdf"
}
To trigger a report PDF download:
{
"action": "downloadPdf",
"params": {"reportId": "vqkp-z5wz-oy56"}
}
Download Excel Sheets
To trigger an Excel download on the embedded dashboard or a single report,
use the action downloadExcel
. The only optional parameter is a reportId
,
which must be a JSON string with the targeted Cluvio report ID.
For example, to trigger a dashboard Excel download:
{
"action": "downloadExcel"
}
To trigger a report PDF download:
{
"action": "downloadExcel",
"params": {"reportId": "vqkp-z5wz-oy56"}
}
Navigate
To navigate the embedded frame to another dashboard (i.e. another sharing link),
use the navigate
action with the dashboardId
and sharingToken
parameters.
For example:
{
"action": "navigate",
"params": {
"dashboardId": "1qk7-yrly-0vzd",
"sharingToken": "ebc1c3ed-340b-4053-98e0-38b0fc6fb5de"
}
}
If the target sharing link requires the use of a sharingSecret
, it must also
be provided as a parameter.
Refresh Dashboard
To explicitly refresh the data on a dashboard, use the refresh
action
without parameters. For example:
{
"action": "refresh"
}
Show Report
To show a single maximised report in the embedded dashboard,
use the action showReport
. The only required parameter is a reportId
,
which must be a JSON string with the targeted Cluvio report ID. For example:
{
"action": "showReport",
"params": {"reportId": "vqkp-z5wz-oy56"}
}
Show Dashboard
To revert back to showing the full dashboard, e.g. after using showReport
earlier, use the showDashboard
action without parameters. For example:
{
"action": "showDashboard"
}
Update Dashboard Settings
The updateSettings
action can be used to update some dashboard settings. At
the moment, the only available setting in this action is darkMode
, which can
be used to turn "dark mode" (i.e. night-time color scheme) on or off. For
example, to turn dark mode on:
{
"action": "updateSettings",
"params": {
"darkMode": true
}
}
To turn dark mode off:
{
"action": "updateSettings",
"params": {
"darkMode": false
}
}
Update Sharing Secret
To update the sharingSecret
parameter used by an embedded dashboard, e.g.
because it is about to expire or to update the fixed_parameters
, use the
updateSharingSecret
action:
{
"action": "updateSharingSecret",
"params": {
"sharingSecret": "<JWT>"
}
}
Events
The embedded Cluvio application emits events via postMessage
to the outer
window element - you can listen to these in your JavaScript code to respond to
changes, such as refreshing an expired sharing secret or updating the state of
your own filter controls to reflect the changes that happened on the embedded
dashboard. The message format for all events is
{
"event": "<name-of-event>",
"params": { <params-of-event> }
}
whereby <params-of-event>
is a JSON object with event-specific parameters.
Parameters Changed
The parametersChanged
event is emitted when the Cluvio filter bar is updated
with new values on an interactive sharing link. The new filter parameter values
are included in the parameters
field. For example:
{
"event": "parametersChanged",
"params": {
"parameters": {
"aggregation":"week",
"timerange":"1467331200~1483228799",
"filters": [
{ "filter_name": "my_country_filter", "selected_values": ["Germany"] }
]
}
}
}
Parameters Reverted
The parametersReverted
event is emitted when Revert to Defaults
is selected
in the Cluvio filter bar on an interactive sharing link. The event has no parameters.
For example:
{
"event": "parametersReverted"
}
Sharing Secret Expired
The secretExpired
event is emitted when the sharing link requires a sharing
secret and the current sharing secret used by the embedded Cluvio dashboard
expired and should be regenerated (see also
updateSharingSecret). The event has no parameters.
For example:
{
"event": "secretExpired"
}
Embed Size Changed
The embedSize
event is emitted when the embedded Cluvio dashboard is initially
rendered and subsequently whenever it is resized, usually by new reports
appearing or reports being removed. Your application can react by adjusting the
iframe DOM element size based on the actual dimensions the embedded dashboard
needs. The typical case is having a width of the iframe determined by the
available space and a dynamic height based on the needs of the dashboard grid.
The event has two parameters, width
and height
, for example:
{
"event": "embedSize",
"params": {
"width": 1200,
"height": 800
}
}
Drill-Down Selection
The drillSelect
event is emitted when the user clicks on a drill-down link in
a chart of an embedded non-interactive dashboard configured with the same
dashboard as the drill-down target. The filters
parameter contains a list of
the drill-down filters and their corresponding values. For example:
{
"event": "drillSelect",
"params": {
"filters": [
{"filterVariable": "my_filter", "value": 42}
]
}
}
This event is only emitted when the enableDrillEvents
URL parameter is
included on a non-interactive sharing link. It is never emitted for
interactive sharing links (Allow Parameters
enabled), where drill-down actions
targeting the same dashboard are performed automatically.
Drill-Down Navigation
The drillDown
event is emitted when the user clicks on a drill-down link
configured with a different dashboard as the drill-down target. The
dashboardId
parameter contains the target dashboard ID and the filters
parameter contains the list of drill-down filter values. For example:
{
"event": "drillSelect",
"params": {
"dashboardId": "1qk7-yrly-0vzd",
"filters": [
{"filterVariable": "my_filter", "value": 42}
]
}
}
Your application can react e.g. by sending the navigate action to the Cluvio embed.
This event is only emitted when the enableDrillEvents
URL parameter is
included on a sharing link.