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
| Property | Element | Called with | When |
|---|---|---|---|
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 intent | A viewer clicks a chart that is set to send its value to your app |
filterStateFunction | <dbn-dashboard> | EmbedFilterStateSnapshot | The applied filters change. See Set and carry dashboard filters. |
onSupportClick | both | nothing | A viewer selects the support button on the embed’s error screen |
manageMetricsBtnContent | <dbn-dashboard> | nothing; return the button content | The embed draws the Manage Metrics and Gallery menu items |
onMinimize | <dbn-metric> | nothing | A 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):
| Field | Meaning |
|---|---|
kind | Always 'dashboard' |
dashboardId, embedDashboardId | The id to put in the new element’s dashboard-id |
globalFilterOptions | Pass to the new element as is. The clicked value is an arrivalValue for each filter. |
filters | [{ column, value }] applied on arrival |
openInNewTab | The metric author’s choice |
path | A 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):
| Function | Opens | Present when |
|---|---|---|
onClickCreateMetric | The metric builder | The viewer can create metrics and the data app uses drag and drop creation |
onClickManageMetrics | Manage Metrics | The viewer can manage metrics and the dashboard has metrics |
onClickScheduleReports | Scheduled reports | Reports are on for the data app and options.disableScheduleEmailReports is not set |
onClickCustomizeLayout | Layout editing | The 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.