This article walks through authoring a custom dashboard block — from declaring metadata to writing the template, connecting a data source, and placing it on a dashboard.
Step-by-Step
- Open Architect Panel → Dashboards → Custom Blocks and click New Block.
- Metadata:
- Name (e.g. “SLA Traffic Light”).
- Key (e.g.
sla_light) — used in code/API. - Category (KPI, Chart, Status, etc.).
- Default size — 1x1, 2x1, 2x2 grid units.
- Refresh interval — how often to re-fetch data.
- Data source: write the query that produces values for this block. Could be a saved query, a custom SQL, or an HTTP fetch.
- Template: write HTML with handlebars tokens for the data values. Add CSS for styling. Optionally add JS for interactivity.
- Configure user-editable parameters — let dashboard owners pick a threshold, a time range, a colour.
- Preview against sample data; iterate.
- Save and publish to the block library.
Template Capabilities
- Handlebars tokens:
{{value}},{{trend}}, etc. - Conditionals:
{{#if breached}}…{{/if}}. - Loops:
{{#each rows}}…{{/each}}. - Helpers:
{{format value "currency"}}. - Scoped CSS — styles only apply inside the block.
- Sandboxed JS — runs in an isolated context with access to block data only.
Worked Examples
- Traffic light: Query returns breach_percent. Template uses
{{#if breach_percent > 5}}red{{else if breach_percent > 1}}amber{{else}}green{{/if}}. - NPS gauge: Query returns nps_score. Template renders SVG semicircle with needle at the right angle.
- Latest tweets: Query fetches from Twitter API. Template loops to render each tweet as a card.
- External Grafana embed: Template is a sandboxed iframe with the user's session token attached.