Agent-Ready Templates

This page provides practical templates for rapid dashboard development.

1. Reference Dashboard Metadata Template

{
  "dashboardSchemaVersion": 1,
  "name": "example-dashboard",
  "displayName": "Example Dashboard",
  "description": "Business overview dashboard.",
  "moduleUserKey": "<module-user-key>",
  "variables": [
    {
      "name": "date",
      "label": "Created At",
      "type": "date",
      "required": true
    },
    {
      "name": "status",
      "label": "Status",
      "type": "selectionStatic",
      "isMultiSelect": true,
      "selectionStaticValues": [
        "open:Open",
        "closed:Closed"
      ]
    },
    {
      "name": "owner",
      "label": "Owner",
      "type": "selectionDynamic",
      "selectionConfig": {
        "providerName": "ExampleOwnerVariableOptionsProvider"
      }
    }
  ],
  "widgets": [
    {
      "id": "kpi-total",
      "name": "Total",
      "type": "kpi",
      "dataProvider": "ExampleTotalKpiProvider"
    },
    {
      "id": "chart-status",
      "name": "Status Distribution",
      "type": "pieChart",
      "dataProvider": "ExampleStatusDistributionProvider"
    }
  ],
  "defaultLayout": {
    "engine": "gridstack",
    "columns": 12,
    "items": [
      { "widgetId": "kpi-total", "x": 0, "y": 0, "w": 3, "h": 2 },
      { "widgetId": "chart-status", "x": 3, "y": 0, "w": 6, "h": 4 }
    ]
  }
}

@DashboardWidgetDataProvider()
@Injectable()
export class ExampleTotalKpiProvider implements IDashboardWidgetDataProvider {
  name(): string {
    return "ExampleTotalKpiProvider";
  }

  help(): string {
    return "Returns total records for dashboard KPI.";
  }

  async getData(widgetDefinition: Record<string, any>, ctxt: IDashboardWidgetDataProviderContext) {
    const total = 0; // replace with repository query

    return {
      meta: {
        providerName: this.name(),
        widgetName: ctxt.widgetName,
        generatedAt: new Date().toISOString(),
        durationMs: 0,
      },
      data: {
        label: widgetDefinition?.name ?? "Total",
        value: total,
      },
    };
  }
}

import type { DashboardWidgetComponentProps } from "@solidxai/core-ui";

export function ExampleCustomWidget({ definition, runtime }: DashboardWidgetComponentProps) {
  const data = runtime?.data ?? {};

  return (
    <div>
      <h4>{definition?.displayName ?? definition?.name}</h4>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  );
}

Registration:

registerExtensionComponent(
  "ExampleCustomWidget",
  ExampleCustomWidget,
  ExtensionComponentTypes.dashboardWidget,
);

Metadata binding:

{
  "id": "widget-custom",
  "name": "Custom Widget",
  "type": "custom",
  "dataProvider": "ExampleCustomProvider",
  "componentName": "ExampleCustomWidget"
}

Add or update widget definition in dashboard metadata.
Create backend provider class implementing IDashboardWidgetDataProvider.
Decorate provider with @DashboardWidgetDataProvider().
Ensure provider is discoverable in module wiring/build.
Validate provider output envelope (meta, data).
If needed, create and register custom frontend widget (dashboardWidget).
Add/update default layout entry for the widget (widgetId, x/y/w/h).
Verify dashboard definition endpoint includes the widget.
Verify widget data endpoint returns expected payload.
Verify full dashboard page render.
Verify layout drag/resize + save + refresh roundtrip.

5. Operational Retest Snippets

# Definition
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/dashboard/<module>/<dashboard>/definition"

# Dashboard data batch
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE_URL/dashboard/<module>/<dashboard>/data" \
  -d '{"variables":{}}'

# Layout load
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/dashboard/<module>/<dashboard>/layout"

# Layout save
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE_URL/dashboard/<module>/<dashboard>/layout" \
  -d '{"layout":{"engine":"gridstack","columns":12,"items":[]}}'

Agent-Ready Templates

1. Reference Dashboard Metadata Template

2. Backend Widget Provider Template

3. Frontend Custom Widget Template (Optional)

4. End-to-End New Widget Checklist

5. Operational Retest Snippets

On this page