Events & Interactions
Handle embed events
Run your own code when a viewer acts in the embed, when the embed loads, or when it shows an error.
The embed tells your page what happens in three ways:
| Way | Where | Use it for |
|---|---|---|
handleServerEvent | Function property on <dbn-dashboard> | Load state and viewer actions |
dbn-error event | On <dbn-dashboard> and <dbn-metric> | Errors the viewer sees |
dbn:embed-config event | On document | The data app config and sidebar state |
Listen for viewer actions
Set handleServerEvent as a JS property, not an attribute (webcomponents.ts:360). The embed calls it with an event code. Some codes also send a second value.
import '@databrainhq/plugin/web';
await customElements.whenDefined('dbn-dashboard');
const el = document.querySelector('dbn-dashboard');
el.handleServerEvent = (code, value) => {
if (code === 'DATA_LOADED') hideSpinner();
if (code === 'DOWNLOAD_METRIC') track('download', { metricId: value });
};<dbn-metric> has no handleServerEvent.
Event codes
Source: consts/api.ts:253-300, hooks/useEmbedLoadEvent.ts:22-25.
| Code | When | Second value |
|---|---|---|
IS_LOADING | The dashboard starts to load | |
DATA_LOADED | The dashboard has loaded | |
INVALID_TOKEN | The element has no token and proxy authentication is off | |
| (error text) | The dashboard failed to load. The code is the error message. | |
ENTER_FULL_SCREEN_MODE | A viewer opens a metric full screen | Metric id |
EXIT_FULL_SCREEN_MODE | A viewer closes full screen | |
METRIC_FILTER_APPLIED | A viewer applies a metric filter | Metric id |
DASHBOARD_FILTER_APPLIED | A viewer applies dashboard filters | |
DOWNLOAD_METRIC | A viewer downloads a metric’s data | Metric id |
DOWNLOAD_METRIC_WITHOUT_FILTERS | A viewer downloads a metric’s data with no filters | Metric id |
SAVE_METRIC_PNG | A viewer saves a chart as PNG | Metric id |
START_DOWNLOAD_ALL_METRICS | A download of all metrics starts | |
DOWNLOAD_ALL_METRICS | The ZIP of all metrics is ready | |
START_DASHBOARD_PDF | A PDF export starts | |
EXPORT_DASHBOARD_PDF | The PDF export is done | |
ENTER_SCHEDULED_REPORT_MODE | A viewer opens scheduled reports | |
SAVE_SCHEDULED_REPORT | A viewer saves a scheduled report | |
EXIT_SCHEDULED_REPORT_MODE | A viewer closes scheduled reports | |
ENTER_CUSTOMIZE_LAYOUT_MODE | A viewer starts to change the layout | |
SAVE_LAYOUT | A viewer saves the layout | |
EXIT_CUSTOMIZE_LAYOUT_MODE | A viewer cancels the layout change | |
ENTER_MANAGE_METRICS_MODE | A viewer opens Manage Metrics | |
SAVE_MANAGE_METRICS | A viewer publishes archived metrics | |
EXIT_MANAGE_METRICS_MODE | A viewer closes Manage Metrics | |
ENTER_METRICS_GALLERY_MODE | A viewer opens Gallery | |
SAVE_CLIENT_GALLERY_METRICS | A viewer adds metrics from the gallery | |
EXIT_METRICS_GALLERY_MODE | A viewer closes Gallery | |
ARCHIVE_METRIC | A viewer archives a metric | Metric id |
ENTER_CREATE_METRIC | A viewer starts to create a metric | |
ENTER_EDIT_METRIC | A viewer starts to edit a metric | |
CREATE_METRIC | A viewer saves a new metric | |
UPDATE_METRIC | A viewer saves a changed metric | |
DATASET_SEARCH_FOCUSED | A viewer selects the search box in the metric builder | |
DATASET_TABLE_SELECTED | A viewer selects a table in the metric builder | Table name |
COLUMN_DRAGGED_TO_DIMENSIONS | A viewer adds a column as a dimension | Column alias |
COLUMN_DRAGGED_TO_MEASURES | A viewer adds a column as a measure | Column alias |
COLUMN_AGGREGATE_CHANGED | A viewer changes a column’s aggregate | Column alias |
CHART_TYPE_CHANGED | A viewer changes the chart type | Chart type, for example BAR |
Listen for errors
Each time the embed shows an error, the element sends a dbn-error event. The event bubbles and crosses the shadow DOM. The embed also logs one console.warn with the same data (components/MetricList/errorShownEvent.ts:104-131).
document.querySelector('dbn-dashboard').addEventListener('dbn-error', (event) => {
const { code, message, hint, surface, metricId, dashboardId } = event.detail;
logToYourMonitoring({ code, message, hint, surface, metricId, dashboardId });
});event.detail has these fields (publicTypes.ts:1440-1455):
| Field | Type | Meaning |
|---|---|---|
code | string | The code the viewer sees, for example E1001 or AUTH_FAILED |
message | string | The cause, for your developers. It can name tables or variables. |
hint | string, optional | How to fix it, when known |
surface | card, builder or dashboard | Where the error showed |
metricId | string, optional | The metric that failed |
dashboardId | string, optional | The element’s dashboard-id |
The viewer sees short text and the code. message and hint are for you. Do not show them to the viewer. To look up a code, see Error codes.
Listen for the embed config
When the dashboard loads its data app config, it sends two events on document with the same data: dbn:embed-config and localStorageValueSet (utils/embedConfigEvent.ts:35-66). Use dbn:embed-config. localStorageValueSet is the old name and stays for existing pages.
document.addEventListener('dbn:embed-config', (event) => {
const { dashboardId, ishideSidebar } = event.detail;
if (dashboardId !== 'DASHBOARD_ID') return;
setSidebarVisible(!ishideSidebar);
});| Field | Type | Meaning |
|---|---|---|
ishideSidebar | boolean | true when the embed hides its sidebar |
config | object | The data app config from the server |
dashboardId | string or null | The element’s dashboard-id |
configId | string or null | The element’s config-id, when set |
externalDashboardId | string or null | Databrain’s internal id of the dashboard |
With two dashboards on one page, check dashboardId so each listener reacts to its own embed.
Next, set the other function props.