Dashboard Component Detailed Description

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 or beta 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 (similarly to InsightView for visualizations)
• Provides mechanisms to allow you to integrate it with the rest of your application
• Allows you to customize the way the dashboard is rendered: you can alter the layout and change the way particular widgets are rendered

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

Customizations props

Eventing props

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 the 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 visualizations stored on the dashboard
    const visualizations = useDashboardSelector(selectInsights);

    return (
        <pre>{JSON.stringify(visualizations, 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 useDispatchDashboardCommand 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 { changeFiltersSelection, useDispatchDashboardCommand } from "@gooddata/sdk-ui-dashboard";

const CustomDashboardWidget = () => {
    const changeFiltersSelection = useDispatchDashboardCommand(changeFilterContextSelection);
    const correlationId = "triggeredByCustomDashboardWidget";

    return (
        <button
            onClick={() => changeFiltersSelection(updatedFilters, false, correlationId)}
        >
            Change filters
        </button>
    )
}

See the API reference for all the commands that are part of the public API.

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 the API reference for all the events that are part of the public API.

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.

See all configuration options here.

Access the state of the Dashboard component from outside the component

To access the state of the Dashboard component, use the SingleDashboardStoreAccessor class. This class provides the following functions that enable access to the Dashboard component state:

• getDashboardSelect() returns a dashboardSelect object for the current dashboard.
• getDashboardDispatch() returns a dashboardDispatch object for the current dashboard.
• getOnChangeHandler() returns a function that can be used as the onStateChange callback for the current dashboard.
• clearAccessor() removes the accessor from the store accessor object.
• isAccessorInitialized() returns true if the accessor is available for the current dashboard; otherwise, returns false.

To access more than one dashboard store object, use the DashboardStoreAccessorRepository class. This class uses a map where the value is DashboardStoreAccessor for a single dashboard and the key is the dashboard’s ObjRef.

• getAccessorsForDashboard(dashboard) returns an accessor object for a specific dashboard.
• getDashboardSelectForDashboard(dashboard) returns a dashboardSelect object for a specific dashboard.
• getDashboardDispatchForDashboard(dashboard) returns a dashboardDispatch object for a specific dashboard.
• getOnChangeHandlerForDashboard(dashboard) returns a function that can be used as the onStateChange callback.
• clearAccessorForDashboard(dashboard) removes accessors from a specific dashboard.
• clearAllAccessors() removes all accessors from the repository.
• isAccessorInitializedForDashboard(dashboard) returns true if the accessor is available for a specific dashboard; otherwise, returns false.

For more information, check the example.

If the default implementation of the DashboardStoreAccessorRepository class does not cover your specific scenario, you can use DashboardStoreAccessor to implement your own accessor repository.