Skip to Content

Events & Interactions

Set function props

Pass your own JavaScript functions to the embed for chart clicks, filter changes, support and custom buttons.

Set a function prop as a JS property, for example el.chartClickFunction = fn. Do not use an HTML attribute: an attribute holds text, not a function.

Function props

PropertyElementCalled withWhen
handleServerEvent<dbn-dashboard>(code, value?)The dashboard loads or a viewer acts. See Handle embed events.
chartClickFunction<dbn-dashboard>A value, a row, or a navigation intentA viewer clicks a chart that is set to send its value to your app
filterStateFunction<dbn-dashboard>EmbedFilterStateSnapshotThe applied filters change. See Set and carry dashboard filters.
onSupportClickbothnothingA viewer selects the support button on the embed’s error screen
manageMetricsBtnContent<dbn-dashboard>nothing; return the button contentThe embed draws the Manage Metrics and Gallery menu items
onMinimize<dbn-metric>nothingA viewer closes full screen

Source: webcomponents.ts:338, 360, 363, 371, 380, 424, 443.

Set them in plain JS

import '@databrainhq/plugin/web';

await customElements.whenDefined('dbn-dashboard');
const el = document.querySelector('dbn-dashboard');

el.chartClickFunction = (payload) => console.log('chart click', payload);
el.onSupportClick = () => openYourHelpWidget();
el.manageMetricsBtnContent = () => 'Edit charts';

Set the props after customElements.whenDefined resolves. You can set them before or after the element is on the page.

Set them in React

Create the element in an effect and set the functions on it. This also works when you change dashboards, because each change makes a new element.

import { useEffect, useRef } from 'react';

type Props = {
  token: string;
  dashboardId: string;
  onNavigate: (intent: any) => void;
};

export function Dashboard({ token, dashboardId, onNavigate }: Props) {
  const host = useRef<HTMLDivElement>(null);

  useEffect(() => {
    let cancelled = false;
    (async () => {
      await import('@databrainhq/plugin/web');
      await customElements.whenDefined('dbn-dashboard');
      if (cancelled || !host.current) return;

      const el = document.createElement('dbn-dashboard') as any;
      el.setAttribute('token', token);
      el.setAttribute('dashboard-id', dashboardId);
      el.setAttribute('enable-chart-dashboard-navigation', 'true');
      el.chartClickFunction = (payload: any) => {
        if (payload?.kind === 'dashboard') onNavigate(payload);
      };
      el.onSupportClick = () => window.open('/help');
      host.current.replaceChildren(el);
    })();
    return () => {
      cancelled = true;
      host.current?.replaceChildren();
    };
  }, [token, dashboardId, onNavigate]);

  return <div ref={host} style={{ height: '100vh' }} />;
}

Wrap onNavigate in useCallback. A new function on each render makes a new element.

Handle chart clicks

chartClickFunction gets one of two payloads.

A value from the chart

In the metric’s chart click actions, set Re-direct Type to Re-direct value to user function. The embed then calls chartClickFunction with the clicked value, for example "APAC". Choose the column in Value Column (core/metric-builder/clickActions.ts:118-170).

With Pass Complete Data to Function on, the embed sends the whole clicked row as an object, for example { "region": "APAC", "revenue": 1200 }.

A dashboard to open

Add enable-chart-dashboard-navigation="true". When a metric’s chart click opens another dashboard, the embed does not move your page. It calls chartClickFunction with an intent (v2/runtime/ChartNavigationProvider.tsx:498-545, core/src/metric-builder/dashboardNavigation.ts:212-219):

FieldMeaning
kindAlways 'dashboard'
dashboardId, embedDashboardIdThe id to put in the new element’s dashboard-id
globalFilterOptionsPass to the new element as is. The clicked value is an arrivalValue for each filter.
filters[{ column, value }] applied on arrival
openInNewTabThe metric author’s choice
pathA ready-made query string. It is not a route in your app.

The same callback gets plain values from other charts. Check payload?.kind === 'dashboard' first.

el.chartClickFunction = (payload) => {
  if (payload?.kind !== 'dashboard') return;
  showDashboard(payload.embedDashboardId, payload.globalFilterOptions);
};

The server checks that the current guest token may open the destination before the embed offers the click. The clicked value narrows the token’s own filter values and never widens them (v2/runtime/ChartNavigationProvider.tsx:38-53). In showDashboard, create a new <dbn-dashboard> with a guest token that covers that dashboard.

Add a support button

onSupportClick adds a second button on the embed’s error screen, next to Try Again. support-label sets its text. The default is Get help. Without onSupportClick, the screen shows only Try Again (components/ErrorFallback/index.tsx:20-90).

Change the Manage Metrics label

manageMetricsBtnContent returns the content of the Manage Metrics and Gallery menu items. The embed calls it each time it draws them (containers/Dashboard/EmbededDashboard.tsx:3251-3288).

Open built-in panels from your own buttons

The dashboard puts four functions on its .dbn-dashboard container in the shadow root (containers/Dashboard/EmbededDashboard.tsx:2048-2081):

FunctionOpensPresent when
onClickCreateMetricThe metric builderThe viewer can create metrics and the data app uses drag and drop creation
onClickManageMetricsManage MetricsThe viewer can manage metrics and the dashboard has metrics
onClickScheduleReportsScheduled reportsReports are on for the data app and options.disableScheduleEmailReports is not set
onClickCustomizeLayoutLayout editingThe viewer can change the layout
const panel = el.shadowRoot?.querySelector('.dbn-dashboard');
if (typeof panel?.onClickScheduleReports === 'function') {
  panel.onClickScheduleReports();
}

Look up the container each time. It changes when the element is created again.