Custom Dashboard Blocks

A custom dashboard block is a reusable widget that appears on dashboards — a KPI tile, a chart, a recent-activity feed, a status indicator, an embedded form. ActiveManage ships with a small library of built-in blocks and lets you author unlimited custom ones.

Built-In Block Types

• KPI tile: Big number, optional trend arrow and small chart.
• Chart: Bar, line, area, pie, gauge.
• Table: Rows with optional sparklines.
• Status: Green/amber/red traffic light with details.
• Activity feed: Chronological list of recent events.
• Embedded form: Inline form for quick data entry.
• Text/markdown: Notes, announcements, links.

Why Custom Blocks

• Built-ins can't match every business need.
• Embed external content (Grafana panel, BI tool snippet, vendor widget).
• Show a custom-shaped visualisation (waffle chart, calendar heat map, geo map).
• Show a specialised summary tailored to your domain (e.g. “SLA breach risk for top customers”).

How Custom Blocks Are Defined

• Each block has a unique key, a friendly name, and an HTML/template body.
• The body can use platform tokens, JavaScript, and CSS.
• Optionally a data-source declaration so the block automatically receives query results.
• Block is then placeable on any dashboard.

Worked Examples

• SLA traffic light: Red if > 5% tickets are past SLA, amber 1-5%, green < 1%.
• Calendar heat map: Last 90 days of activity colour-coded by daily volume.
• Sales pipeline funnel: Stage counts shown as a funnel chart.
• External Grafana embed: Iframe a Grafana panel with the company auth token.
• NPS dial: Custom semicircle gauge showing the rolling NPS score.

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

1. Open Architect Panel → Dashboards → Custom Blocks and click New Block.
2. 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.
3. Data source: write the query that produces values for this block. Could be a saved query, a custom SQL, or an HTTP fetch.
4. Template: write HTML with handlebars tokens for the data values. Add CSS for styling. Optionally add JS for interactivity.
5. Configure user-editable parameters — let dashboard owners pick a threshold, a time range, a colour.
6. Preview against sample data; iterate.
7. 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.