Dashboard Designer Guide

Build interactive, real-time dashboards with charts, metrics, and live data from multiple sources.

Table of Contents

1. Overview
2. Creating a Dashboard
3. Data Sources
4. Adding Elements
5. Chart Types
6. Metric Cards
7. Data Tables
8. Screen Parameters
9. Layout & Styling
10. Dashboard Settings
11. Best Practices

1. Overview

The Dashboard Designer allows you to create interactive, real-time dashboards that display data from various sources. Dashboards can include:

• Charts — Line, bar, pie, doughnut, radar, scatter, bubble, and more
• Metric Cards — KPIs and key numbers with change indicators
• Data Tables — Tabular data with sorting and filtering
• Text Blocks — Labels, headers, and descriptions
• Embedded Dashboards — Nest dashboards within dashboards

Key Features:

• Drag & Drop — Visual layout with resizable elements on a 12-column grid
• Multiple Data Sources — Static, webhook, or Script Engine
• Auto-Refresh — Configurable refresh interval (minimum 45 seconds)
• Screen Parameters — Dynamic filtering and customization
• Version Tracking — Dashboard layout versions are tracked
• Mobile Support — Toggle Show on Mobile for mobile access
• Public Access — Optionally make dashboards publicly accessible

2. Creating a Dashboard

Step 1: Navigate to Dashboards

Go to DataMagik → Dashboards in the main menu.

Step 2: Create New Dashboard

Click the New Dashboard button.

Step 3: Configure Settings

Step 4: Choose Data Source

Select your default data source type:

• Static Data — Hardcoded values for testing
• Webhook — External API endpoint
• Script Engine — Use a DataMagik script
• Mixed — Configure per element

Step 5: Add Elements

Drag elements from the palette onto the canvas.

3. Data Sources

Static Data

Best for testing or fixed values that rarely change.

{
  "sales": [
    { "month": "Jan", "revenue": 45000 },
    { "month": "Feb", "revenue": 52000 },
    { "month": "Mar", "revenue": 48000 }
  ],
  "totalRevenue": 145000,
  "averageOrder": 125.5
}

Webhook Data Source

Connect to any REST API endpoint.

Testing Your Webhook:

1. Configure the URL and authentication
2. Click Test Webhook
3. View the response preview
4. Use the Data Explorer to map fields to elements

Script Engine Data Source

Use a DataMagik script to fetch and transform data.

1. Select a script from the dropdown
2. Click Test Script to preview output
3. Map script output fields to dashboard elements

Example Script for Dashboard:

function main(context) {
  const orders = tables.list("orders");
  
  const totalRevenue = orders.reduce((sum, o) => sum + o.value.total, 0);
  const orderCount = orders.length;

  return {
    success: true,
    data: {
      orders: orders,
      totalRevenue: totalRevenue,
      orderCount: orderCount
    }
  };
}

Mixed Data Sources

Configure each element with its own data source:

1. Set Default Data Source to Mixed
2. When adding/editing elements, choose the source for each
3. Different elements can pull from different APIs or scripts

4. Adding Elements

Element Palette

The left sidebar contains all available elements:

Charts:

• Line Chart, Bar Chart, Horizontal Bar
• Pie Chart, Doughnut, Polar Area
• Radar, Scatter, Bubble
• Area (Ribbon), Stepped Line, Stepped Area

Other Elements:

• Metric Card
• Text Block
• Data Table
• Embed Dashboard

Drag & Drop

1. Click an element in the palette
2. Drag it onto the canvas
3. Drop where you want it
4. Resize by dragging corners/edges
5. Move by dragging the element body

Element Properties

Click any element on the canvas to open the Properties Panel, where you can configure data binding, styling, and display options.

5. Chart Types

Line Chart

Best for showing trends over time.

{
  "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
  "datasets": [
    {
      "label": "Revenue",
      "data": [12000, 19000, 15000, 22000, 18000]
    }
  ]
}

Configuration Options: Title, X/Y-axis labels, line tension, fill area, show data labels.

Bar Chart

Best for comparing categories or discrete values.

{
  "labels": ["Product A", "Product B", "Product C"],
  "datasets": [
    {
      "label": "Sales",
      "data": [450, 320, 280],
      "backgroundColor": ["#4F46E5", "#10B981", "#F59E0B"]
    }
  ]
}

Configuration Options: Horizontal/vertical orientation, stacked mode, bar width, colors.

Pie & Doughnut Charts

Best for showing proportions of a whole.

{
  "labels": ["Category A", "Category B", "Category C"],
  "datasets": [
    {
      "data": [30, 50, 20],
      "backgroundColor": ["#EF4444", "#3B82F6", "#10B981"]
    }
  ]
}

Configuration Options: Cutout percentage (doughnut), legend, percentage labels, animation.

Radar Chart

Best for comparing multiple variables across categories.

{
  "labels": ["Speed", "Power", "Defense", "Range", "Accuracy"],
  "datasets": [
    { "label": "Player A", "data": [80, 90, 70, 85, 75] },
    { "label": "Player B", "data": [65, 75, 95, 60, 90] }
  ]
}

Scatter & Bubble Charts

Best for showing relationships between variables.

// Scatter
{ "datasets": [{ "label": "Data", "data": [{ "x": 10, "y": 20 }, { "x": 15, "y": 25 }] }] }

// Bubble (includes radius)
{ "datasets": [{ "label": "Sales", "data": [{ "x": 10, "y": 20, "r": 15 }] }] }

Advanced Chart Configuration

For complex charts, use the Advanced Chart Editor to edit the raw Chart.js configuration JSON with a live preview.

6. Metric Cards

Display key performance indicators prominently.

Configuration

7. Data Tables

Display tabular data with sorting and filtering.

Configuration

Column Configuration

8. Screen Parameters

Add interactive filters to your dashboard.

Creating Parameters

Using Parameters in Scripts

Parameters are passed to your script's context:

function main(context) {
  const startDate = context.startDate || "2025-01-01";
  const endDate = context.endDate || "2025-12-31";
  const region = context.region || "all";

  // Use parameters to filter data
  const data = tables.list("sales").filter(s => 
    s.value.date >= startDate && s.value.date <= endDate
  );

  return { success: true, data: { sales: data } };
}

Using Parameters in Webhooks

Parameters are appended as query string or body fields based on method.

9. Layout & Styling

Grid System

The dashboard uses a responsive 12-column grid (GridStack):

• Elements snap to grid
• Drag corners to resize
• Drag body to reposition

Element Sizing

Styling Options

Each element can be styled with:

• Background Color — Card background
• Text Color — Title and label colors
• Border — Border style and color
• Shadow — Elevation effect
• Padding — Internal spacing

10. Dashboard Settings

Configure dashboard-level settings from the Settings panel.

General

Organization

11. Best Practices

Dashboard Design

• Focus on key metrics — Don't overcrowd; prioritize important data
• Use consistent styling — Same colors for same types of data
• Group related items — Place related charts/metrics together
• Consider the audience — Executives want KPIs, operators want details

Data Sources

• Cache when possible — Reduce API calls
• Use appropriate refresh rates — Don't refresh more often than data changes
• Handle errors gracefully — Show loading states and error messages
• Test with realistic data — Ensure charts scale with actual data volumes

Performance

• Limit elements — 10-15 elements maximum per dashboard
• Optimize scripts — Efficient queries and minimal processing
• Use pagination — For large data tables
• Minimum refresh interval is 45 seconds — Don't overload data sources