Dashboard Component

Introduction

The Dashboard Component is a grid-based container component that provides a flexible layout system for organizing and displaying multiple widgets. It features a configurable toolbar with input controls whose values are shared across all child widgets, and supports an edit mode that allows users to resize, reposition, add, and remove widgets dynamically.

YAML Structure

The dashboard component uses a grid system to position child components and requires all children to be of type dashboard-widget.

Basic Structure

component: dashboard
name: dashboardName
props:
  title: Dashboard Title
  toolbar: [] # Array of input components
  options: {} # Configuration options
children: [] # Array of dashboard-widget components

Attribute Description

Main Properties

Property	Type	Description	Required
name	string	Unique identifier for the dashboard	Yes
title	string	Display title for the dashboard	No
toolbar	array	Array of input components (fields) that provide values to all widgets	No
options	object	Dashboard configuration settings	No
children	array	Array of dashboard-widget components only	Yes

Options Object

Property	Type	Description	Default
rows	number	Number of rows in the dashboard grid	12
columns	number	Number of columns in the dashboard grid	12
gridGap	number	Spacing between grid cells in pixels	8
responsive	boolean	Enable responsive breakpoints for different screen sizes	false
allowEdit	boolean	Show edit mode button allowing users to modify dashboard layout	false
showGridLines	boolean	Display grid guidelines when in edit mode	true
autoSave	boolean	Automatically save layout changes	false

Examples

Basic Dashboard with Toolbar

component: dashboard
name: salesDashboard
props:
  title: Sales Dashboard
  toolbar:
    - component: field
      name: dateRange
      props:
        type: daterange
        label: Date Range
    - component: field
      name: customer
      props:
        type: select
        label: Customer
        placeholder: Select a customer
        options:
          query: customers
          valueField: customerId
          labelField: customerName
    - component: field
      name: division
      props:
        type: select
        label: Division
        options:
          - value: north
            label: North
          - value: south
            label: South
          - value: east
            label: East
          - value: west
            label: West
  options:
    rows: 12
    columns: 12
    gridGap: 10
    allowEdit: true
    responsive: true
children:
  - component: dashboard-widget
    name: revenueMetrics
    props:
      options:
        row: 1
        col: 1
        rowSpan: 3
        colSpan: 6
        title: Revenue Metrics
    children:
      - component: summary
        props:
          items:
            - label: Total Revenue
              value: "{{ format query.totalRevenue '$0,0.00' }}"
              filter:
                dateRange: "{{ dashboard.dateRange }}"
                customer: "{{ dashboard.customer }}"
            - label: Average Order Value
              value: "{{ format query.avgOrderValue '$0,0.00' }}"
              filter:
                dateRange: "{{ dashboard.dateRange }}"
                customer: "{{ dashboard.customer }}"

  - component: dashboard-widget
    name: ordersGrid
    props:
      options:
        row: 1
        col: 7
        rowSpan: 6
        colSpan: 6
        title: Recent Orders
    children:
      - component: datagrid
        props:
          query: orders
          filters:
            dateRange: "{{ dashboard.dateRange }}"
            customerId: "{{ dashboard.customer }}"
            division: "{{ dashboard.division }}"
          columns:
            - name: orderNumber
              label: Order #
            - name: customerName
              label: Customer
            - name: orderDate
              label: Date
            - name: totalAmount
              label: Amount

  - component: dashboard-widget
    name: chartSection
    props:
      options:
        row: 4
        col: 1
        rowSpan: 9
        colSpan: 6
        title: Trend Analysis
    children:
      - component: chart
        props:
          type: line
          dataSource:
            query: salesTrend
            filters:
              dateRange: "{{ dashboard.dateRange }}"
              division: "{{ dashboard.division }}"

Dashboard with Multiple Layout Widgets

component: dashboard
name: operationsDashboard
props:
  title: Operations Dashboard
  toolbar:
    - component: field
      name: warehouse
      props:
        type: select
        label: Warehouse
        options:
          query: warehouses
    - component: field
      name: status
      props:
        type: select
        label: Status
        multiple: true
        options:
          - value: pending
            label: Pending
          - value: processing
            label: Processing
          - value: completed
            label: Completed
  options:
    rows: 10
    columns: 10
    gridGap: 12
    allowEdit: true
    autoSave: true
children:
  - component: dashboard-widget
    name: inventoryWidget
    props:
      options:
        row: 1
        col: 1
        rowSpan: 5
        colSpan: 5
        title: Inventory Overview
    children:
      - component: layout
        props:
          orientation: vertical
        children:
          - component: summary
            props:
              title: Stock Levels
              filter:
                warehouse: "{{ dashboard.warehouse }}"
          - component: datagrid
            props:
              query: inventoryItems
              filters:
                warehouse: "{{ dashboard.warehouse }}"

  - component: dashboard-widget
    name: shipmentsWidget
    props:
      options:
        row: 1
        col: 6
        rowSpan: 10
        colSpan: 5
        title: Shipments
        showHeader: true
    children:
      - component: collection
        props:
          dataSource:
            query: shipments
            filters:
              warehouse: "{{ dashboard.warehouse }}"
              status: "{{ dashboard.status }}"
          template:
            component: card
            props:
              title: "{{ item.shipmentNumber }}"
              subtitle: "{{ item.destination }}"
              status: "{{ item.status }}"

Minimal Dashboard Configuration

component: dashboard
name: simpleDashboard
props:
  title: Simple Dashboard
  options:
    rows: 8
    columns: 8
    allowEdit: false
children:
  - component: dashboard-widget
    name: mainContent
    props:
      options:
        row: 1
        col: 1
        rowSpan: 8
        colSpan: 8
        title: Main Content
    children:
      - component: text
        props:
          value: Dashboard content goes here

Best Practices

Grid Layout Design

1. Plan Your Grid: Design your dashboard layout on paper first, considering the importance and size requirements of each widget
2. Responsive Considerations: Use appropriate rowSpan and colSpan values that work well on different screen sizes
3. Spacing: Use consistent gridGap values for visual harmony
4. Widget Sizing: Make frequently-used widgets larger and more prominent

Toolbar Design

1. Common Filters First: Place the most commonly used filters at the beginning of the toolbar
2. Logical Grouping: Group related filters together
3. Default Values: Provide sensible default values for toolbar inputs
4. Labels: Use clear, concise labels for toolbar inputs

Performance Optimization

1. Lazy Loading: Consider loading widget content only when visible
2. Data Caching: Reuse data queries across widgets when possible
3. Toolbar Debouncing: Implement debouncing for toolbar inputs to avoid excessive re-queries
4. Widget Count: Limit the number of widgets to maintain performance

Edit Mode

1. Permissions: Control allowEdit based on user roles
2. Auto-Save: Enable autoSave for better user experience
3. Grid Guidelines: Keep showGridLines enabled to help users align widgets
4. Constraints: Set appropriate min/max spans in dashboard-widget options

Data Binding

All toolbar input values are automatically available to child widgets through the dashboard context:

# In any child component within a dashboard-widget:
filters:
  dateRange: "{{ dashboard.dateRange }}"
  customer: "{{ dashboard.customer }}"
  division: "{{ dashboard.division }}"

Values update in real-time as users interact with toolbar inputs, automatically refreshing dependent widgets.

Edit Mode Features

When options.allowEdit is set to true, users can:

1. Enter/Exit Edit Mode: Toggle button appears in dashboard header
2. Resize Widgets: Drag resize handles on widget borders
3. Reposition Widgets: Drag widgets to new grid positions
4. Add Widgets: Add new dashboard-widget components
5. Remove Widgets: Delete unwanted widgets
6. Save Layout: Persist layout changes (with autoSave or manual save)

Responsive Behavior

When options.responsive is enabled:

• Mobile (< 768px): Widgets stack vertically, full width
• Tablet (768px - 1024px): Reduced column count, adjusted spans
• Desktop (> 1024px): Full grid layout as configured

Related Topics

• Dashboard Widget Component - Required child component for dashboards
• Layout Component - Can be used within dashboard widgets
• Field Component - Used in toolbar for input controls
• DataGrid Component - Common widget content
• Summary Component - Display metrics in widgets