Edit visualizations on a dashboard

When you finish, users of your embedded dashboard open Analytical Designer on top of the dashboard. They can explore a visualization in view mode, edit it in edit mode, or create a new one, for example by dragging it into the layout. They stay in your application the whole time.

Turn on visualization editing

Set enableInsightEditing in the config of the Dashboard component:

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>");

export const EditableDashboard = () => (
    <Dashboard dashboard={dashboardRef} config={{ enableInsightEditing: true }} />
);

The option defaults to false. With it off, the dashboard behaves as before.

You don’t install or import anything else. @gooddata/sdk-ui-analytical-designer is a dependency of @gooddata/sdk-ui-dashboard. The dashboard loads Analytical Designer and its stylesheets in a separate chunk the first time a user opens it. It also passes Analytical Designer the data it has already loaded: backend, workspace, settings, permissions, user, color palette, theme, and the catalog tags of objectAvailability. Analytical Designer opens without loading them again.

Where users open Analytical Designer

Each entry point appears only for users with the matching permission:

Analytical Designer has no mobile layout, so these entry points don’t open it on a mobile screen.

Drag a new visualization into the layout

In edit mode, the creation panel has a Visualization item. When the user drags it into the layout, a placeholder takes the drop position and Analytical Designer opens with an empty editor. Saving puts the new visualization at the position of the placeholder. Cancelling removes the placeholder.

What saving does

When a visualization is saved but cannot be added to the dashboard, the dashboard shows a message and removes the placeholder. The visualization stays saved.

Escape closes the topmost layer first, for example an open dropdown. When Escape or a click outside reaches the editor itself, Analytical Designer closes. If the user has unsaved changes in an edited visualization or a metric, it asks for confirmation first.

Explore with the dashboard filters

Explore from here passes the dashboard filters and the timezone of the widget to Analytical Designer, so the copy shows the same data as the widget. Filters on attributes that cannot filter the visualization don’t pass.

When the filters cannot be kept, the dashboard shows a warning, and the copy opens without them:

• The date filter of the dashboard cannot be applied to the visualization.
• The filters have more than 20 items.
• Passing the filters takes longer than five seconds, or fails.

React to the editor events

The dashboard emits these events. Each has a type guard, for example isDashboardInsightEditorInsightSaved:

import {
    Dashboard,
    type IDashboardInsightEditorInsightSaved,
    isDashboardInsightEditorInsightSaved,
} from "@gooddata/sdk-ui-dashboard";

<Dashboard
    dashboard={dashboardRef}
    config={{ enableInsightEditing: true }}
    eventHandlers={[
        {
            eval: isDashboardInsightEditorInsightSaved,
            handler: (event: IDashboardInsightEditorInsightSaved) => {
                console.log("Visualization saved", event.payload.insight);
            },
        },
    ]}
/>;

To read whether the editor is open, and for which target, use selectInsightEditorTarget. See Handle dashboard events for more about event handlers.

Keep a caching backend fresh

If you give the dashboard a backend wrapped with withCaching, reset its caches when Analytical Designer asks. It asks after the user refreshes the catalog, edits a metric, or changes an attribute hierarchy. payload.scope is "catalogs" or "all":

import {
    Dashboard,
    type IDashboardInsightEditorCacheResetRequested,
    isDashboardInsightEditorCacheResetRequested,
} from "@gooddata/sdk-ui-dashboard";

import { cacheControl } from "./backend.js";

<Dashboard
    dashboard={dashboardRef}
    config={{ enableInsightEditing: true }}
    eventHandlers={[
        {
            eval: isDashboardInsightEditorCacheResetRequested,
            handler: (event: IDashboardInsightEditorCacheResetRequested) => {
                if (event.payload.scope === "all") {
                    cacheControl?.resetAll();
                } else {
                    cacheControl?.resetCatalogs();
                }
            },
        },
    ]}
/>;

Improve dashboard performance shows how to get cacheControl from withCaching.