Embedding reports in dashboards

Ta treść nie jest jeszcze dostępna w Twoim języku.

This guide shows a report inside a dashboard you develop locally. The report components are described in Report components.

To show one saved report as a whole, you need no code: in Setup → Dashboards, select Create from report and pick the report.

Show a saved report

Start from the Empty dashboard template. Keep its index.tsx and manifest.ts: the entry re-exports dashboardConfigType and supportedLocales, which hmi build requires.

Declare the report in config.ts:

import Type from "typebox";

export const dashboardConfigType = Type.Object(
  {
    presetId: Type.String({ format: "uuid" }),
  },
  { additionalProperties: false },
);

Load the report with trpc.report.preset.get, and compose the report pieces in dashboard.tsx. Import them from @overvis/hmi-workspace-ui; do not bundle workspace-ui into the dashboard.

import {
  parseDashboardConfiguration,
  type DashboardRootProps,
} from "@overvis/hmi-shared/dashboard";
import {
  ReportDataProvider,
  ReportTimeNav,
  ReportWidget,
  trpc,
} from "@overvis/hmi-workspace-ui";

import { dashboardConfigType } from "./config.ts";

export default function Board(props: DashboardRootProps) {
  const { presetId } = parseDashboardConfiguration(dashboardConfigType, props.configuration);
  const presetQuery = trpc.report.preset.get.useQuery({ id: presetId });
  if (presetQuery.data == null) {
    return null;
  }
  return (
    <ReportDataProvider workspaceId={props.workspaceId} preset={presetQuery.data}>
      <div className="flex min-h-0 flex-col gap-3 p-4">
        <ReportTimeNav />
        <div className="h-64 min-h-0">
          <ReportWidget representationKey="mainChart" />
        </div>
      </div>
    </ReportDataProvider>
  );
}

Give each ReportWidget a parent with a definite height, such as h-64 or h-full.
Push the dashboard, and set configuration.presetId to the ID of a saved report in the dashboard’s settings.

Arrange the report pieces

Use ReportWidget rather than the view components; it picks the right one from the recipe.
Use one provider per report on a page.
Do not mount the same view key twice, such as in ReportView and in a separate ReportWidget.
To keep a dashboard tile from changing the window of the report page, set sessionScope on the provider.
To keep a tile from exporting or sharing, leave out ReportTimeNav.

Show a report generated in code

A dashboard can build a report in memory, such as a Sankey or time bars that follow its own configuration.

Freeze the parameter setups with useFrozenReportParameters(workspaceId, parameterIds). Show GeneratedReportPending until parameters is ready, with retry as its onRetry.
Build the report from the frozen parameters with a stable ID, such as derivedEntityId(entityId, role). Turn off comments, signing, snapshot sharing, and CSV.

Render it with GeneratedReport over the period the dashboard already shows, so the charts and its totals cover the same time, and put each view in a GeneratedReportSection:

const { parameters, isError, retry } = useFrozenReportParameters(workspaceId, parameterIds);
return parameters == null ? (
  <GeneratedReportPending isError={isError} onRetry={retry} />
) : (
  <GeneratedReport workspaceId={workspaceId} preset={buildPreset(parameters)} period={period}>
    <GeneratedReportSection title="Energy over time" representationKey="buckets" />
  </GeneratedReport>
);

Check the recipe with validateReportPresetRecipe from @overvis/hmi-shared/report in tests.

To use ReportDataProvider directly instead, pass the preset with saved={false} and the period window as timeRange, and give the provider a key that changes with the recipe, so a changed recipe starts a fresh session. Show a note instead of the provider until to passes from:

<ReportDataProvider
  key={recipeKey}
  workspaceId={workspaceId}
  preset={generatedPreset}
  timeRange={period.window}
  saved={false}
>
  <ReportWidget representationKey="flow" column="full" />
</ReportDataProvider>

Embedding reports in dashboards

Show a saved report

Arrange the report pieces

Show a report generated in code

Related