Skip to Content

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:

WayWhereUse it for
handleServerEventFunction property on <dbn-dashboard>Load state and viewer actions
dbn-error eventOn <dbn-dashboard> and <dbn-metric>Errors the viewer sees
dbn:embed-config eventOn documentThe 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.

CodeWhenSecond value
IS_LOADINGThe dashboard starts to load
DATA_LOADEDThe dashboard has loaded
INVALID_TOKENThe 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_MODEA viewer opens a metric full screenMetric id
EXIT_FULL_SCREEN_MODEA viewer closes full screen
METRIC_FILTER_APPLIEDA viewer applies a metric filterMetric id
DASHBOARD_FILTER_APPLIEDA viewer applies dashboard filters
DOWNLOAD_METRICA viewer downloads a metric’s dataMetric id
DOWNLOAD_METRIC_WITHOUT_FILTERSA viewer downloads a metric’s data with no filtersMetric id
SAVE_METRIC_PNGA viewer saves a chart as PNGMetric id
START_DOWNLOAD_ALL_METRICSA download of all metrics starts
DOWNLOAD_ALL_METRICSThe ZIP of all metrics is ready
START_DASHBOARD_PDFA PDF export starts
EXPORT_DASHBOARD_PDFThe PDF export is done
ENTER_SCHEDULED_REPORT_MODEA viewer opens scheduled reports
SAVE_SCHEDULED_REPORTA viewer saves a scheduled report
EXIT_SCHEDULED_REPORT_MODEA viewer closes scheduled reports
ENTER_CUSTOMIZE_LAYOUT_MODEA viewer starts to change the layout
SAVE_LAYOUTA viewer saves the layout
EXIT_CUSTOMIZE_LAYOUT_MODEA viewer cancels the layout change
ENTER_MANAGE_METRICS_MODEA viewer opens Manage Metrics
SAVE_MANAGE_METRICSA viewer publishes archived metrics
EXIT_MANAGE_METRICS_MODEA viewer closes Manage Metrics
ENTER_METRICS_GALLERY_MODEA viewer opens Gallery
SAVE_CLIENT_GALLERY_METRICSA viewer adds metrics from the gallery
EXIT_METRICS_GALLERY_MODEA viewer closes Gallery
ARCHIVE_METRICA viewer archives a metricMetric id
ENTER_CREATE_METRICA viewer starts to create a metric
ENTER_EDIT_METRICA viewer starts to edit a metric
CREATE_METRICA viewer saves a new metric
UPDATE_METRICA viewer saves a changed metric
DATASET_SEARCH_FOCUSEDA viewer selects the search box in the metric builder
DATASET_TABLE_SELECTEDA viewer selects a table in the metric builderTable name
COLUMN_DRAGGED_TO_DIMENSIONSA viewer adds a column as a dimensionColumn alias
COLUMN_DRAGGED_TO_MEASURESA viewer adds a column as a measureColumn alias
COLUMN_AGGREGATE_CHANGEDA viewer changes a column’s aggregateColumn alias
CHART_TYPE_CHANGEDA viewer changes the chart typeChart 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):

FieldTypeMeaning
codestringThe code the viewer sees, for example E1001 or AUTH_FAILED
messagestringThe cause, for your developers. It can name tables or variables.
hintstring, optionalHow to fix it, when known
surfacecard, builder or dashboardWhere the error showed
metricIdstring, optionalThe metric that failed
dashboardIdstring, optionalThe 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);
});
FieldTypeMeaning
ishideSidebarbooleantrue when the embed hides its sidebar
configobjectThe data app config from the server
dashboardIdstring or nullThe element’s dashboard-id
configIdstring or nullThe element’s config-id, when set
externalDashboardIdstring or nullDatabrain’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.