Dashboard Component
Some parts of the Dashboard component are still in the beta stage.
The Dashboard component has a rich set of APIs, but not all of them are stable yet. Carefully read the API maturity annotations, and keep in mind that in the future releases we may make breaking changes to the APIs that are on the
alpha
orbeta
level.
The Dashboard component is a highly customizable component that renders dashboards created and saved by KPI Dashboards.
The Dashboard component:
- Allows you to embed a dashboard natively in React in view mode (similarly to InsightView for visualizations)
- Provides mechanisms to allow you to integrate it with the rest of your application (see Commands and Events)
- Allows you to customize the way the dashboard is rendered: you can alter the layout and change the way particular widgets are rendered (see Props and Selectors)
The Dashboard component is built using an architecture resembling the Model-View-Controller pattern:
The Model part is implemented with Redux and Redux-Saga. The Model part exposes rich APIs: selectors to get data from the component's state, events to describe changes, interactions with the dashboard, and commands to trigger changes.
The View and Controller parts are implemented using React components and hooks. The top-level Dashboard component also has rich APIs: props to specify a dashboard to render, configuration for rendering, customization of almost all view components used on a dashboard, and integration with the eventing.
Basic usage
import "@gooddata/sdk-ui-dashboard/styles/css/main.css";
import { Dashboard } from "@gooddata/sdk-ui-dashboard";
import { idRef } from "@gooddata/sdk-model";
const dashboardRef = idRef("<dashboard-identifier>");
const EmbeddedReactDashboard = () => {
return (
<Dashboard dashboard={dashboardRef} />
);
};
Props
Similar to any other React component, you can configure the Dashboard component by setting up its props.
The API reference describes all the props in detail. Here are the most important props:
Base props
Name | Required? | Type | Description |
---|---|---|---|
dashboard | true | ObjRef or IDashboard | The reference to the dashboard to render, or the loaded dashboard |
filterContextRef | false | ObjRef | The reference to the filter context that should be used instead of the default, built-in filter context. NOTE: This property is valid only when you specify the dashboard prop by reference. If you specify dashboard by value, the component assumes that the value also contains the desired filter context and will use it as is. |
config | false | DashboardConfig | Configuration that can be used to modify dashboard features, capabilities, and behavior. If not specified, the dashboard will retrieve and use the essential configuration from the backend. |
Customizations props
Name | Required? | Type | Description |
---|---|---|---|
customizationFns | false | DashboardModelCustomizationFns | The customization functions. The dashboard component will call out to these functions at different points during its lifetime. To learn more, see documentation for a particular function. |
InsightComponentProvider | false | OptionalInsightComponentProvider | The function to obtain a custom component to use for rendering an insight |
KpiComponentProvider | false | OptionalKpiComponentProvider | The function to obtain a custom component to use for rendering a KPI |
WidgetComponentProvider | false | OptionalWidgetComponentProvider | The function to obtain a custom component to use for rendering either a built-in widget or a custom widget |
Eventing props
Name | Required? | Type | Description |
---|---|---|---|
eventHandlers | false | DashboardEventHandler[] | The event handlers to register at the dashboard creation time |
onEventingInitialized | false | Function | The callback that will be called when the dashboard eventing subsystem initializes and a new event can be registered and existing event handlers can be un-registered |
onStateChange | false | Function | The callback that will be called each time the state changes |
Check the full list of the Dashboard component props here.
Selectors
To obtain the values of the current state of the Dashboard component, use the useDashboardSelector
hook with a relevant selector passed to
it (all dashboard selectors start with the select
prefix). The selectors have cache, so the reference equality of
a returned value should remain the same (unless the value itself changed), which is useful to avoid unnecessary React re-renders.
import { useDashboardSelector, selectInsights } from "@gooddata/sdk-ui-dashboard";
const CustomDashboardWidget = () => {
// Example how to obtain all insights stored on the dashboard
const insights = useDashboardSelector(selectInsights);
return (
<pre>{JSON.stringify(insights, null, 2)}</pre>
);
}
See all available selectors here.
Commands
Commands are Redux actions that you can dispatch to the Dashboard component to initiate a change of the rendered
dashboard. To dispatch a command, use the useDashboardDispatch
hook. As the Dashboard component handles
a command, it emits one or more events describing what has happened. Typically, at least one event describing
the accomplished result will be emitted.
The events emitted during command handling will be sent to all handlers added for the respective event type. To allow for request-response semantics, each command can specify a custom correlation ID that will be included in all events emitted during the command processing.
IMPORTANT! The commands are the only valid and supported way to modify a rendered dashboard. You must not alter the state of the Dashboard component by directly mutating it because it may lead to undesired behavior and issues.
import { useDashboardSelector } from "@gooddata/sdk-ui-dashboard";
const CustomDashboardWidget = () => {
const dispatch = useDashboardDispatch();
const correlationId = "triggeredByCustomDashboardWidget";
return (
<button
onClick={() => dispatch(changeFilterContextSelection(updatedFilters), false, correlationId)}
>
Change filters
</button>
)
}
See all available commands here.
Events
Events inform you about what happened in the Dashboard component (for example, the filters changed).
The following code sample represents an example of listening to all dashboard events:
import "@gooddata/sdk-ui-dashboard/styles/css/main.css";
import { Dashboard, anyEventHandler } from "@gooddata/sdk-ui-dashboard";
import { idRef } from "@gooddata/sdk-model";
const dashboardRef = idRef("<dashboard-identifier>");
const EmbeddedReactDashboard = () => {
return (
<Dashboard
dashboard={dashboardRef}
eventHandlers={[
anyEventHandler((e) => {
console.log("Dashboard event fired:", e);
}),
]}
/>
);
};
See all available events here.
Configuration
Configuration of a dashboard can influence the available features, look-and-feel, and behavior of the dashboard. To
specify the configuration, use the config
prop.
All configuration properties are optional. For most of them, the Dashboard component can reliably retrieve values from the Analytical Backend.
Name | Required? | Type | Description |
---|---|---|---|
locale | false | ILocale | The localization of the visualization. Defaults to the locale set for the current user. For other languages, see the full list of available localizations. |
separators | false | ISeparators | The number format |
mapboxToken | false | string | The map access token to be used by geo pushpin charts |
isReadOnly | false | boolean | If set to true , the dashboard will be embedded in read-only mode disabling any user interaction that would alter any backend state (disabling creating/changing alerts, creating scheduled emails, and so on) |
See all configuration options here.