AutoCom Docs

Dashboard Module

The CoreDashboard module provides a fully customizable dashboard system with drag-and-drop widgets. Create personalized dashboards, add widgets from various modules, and visualize your business data in real-time.

Overview

Key Features:

  • Customizable Dashboards: Create multiple dashboards for different purposes
  • Drag-and-Drop Editor: Intuitive grid-based layout system
  • Widget Library: Pre-built widgets from all installed modules
  • Widget Registry: Extensible system for modules to contribute widgets
  • Templates: Start from pre-designed dashboard templates
  • Real-time Updates: Auto-refresh widgets with configurable intervals
  • Per-User Dashboards: Each user can have their own personalized dashboards

Quick Start

1. Access the Dashboard

  1. Navigate to Dashboard in the main navigation
  2. If no dashboards exist, you'll see an option to create one
  3. Click Create Dashboard to get started

2. Create a Dashboard

  1. Choose between Blank Dashboard or From Template
  2. Enter a name and optional description
  3. Toggle Set as default if you want it to load automatically
  4. Click Create Dashboard

3. Add Widgets

  1. Click the Add Widget button in the edit mode
  2. Browse the Widget Library organized by category
  3. Click on a widget to add it to your dashboard
  4. Drag and resize widgets to arrange your layout
  5. Changes are saved automatically

Dashboard Management

Creating Dashboards

POST /api/v1/dashboard/dashboards
Content-Type: application/json

{
  "name": "Sales Overview",
  "description": "Daily sales metrics and trends",
  "is_default": false
}

Dashboard Properties

Property Type Description Default
name string Dashboard display name Required
description string Optional description null
is_default boolean Load this dashboard by default false
is_shared boolean Share with team members false
layout object Grid configuration See below
widgets array Widget instances on the dashboard []

Default Layout Configuration

{
  "columns": 12,
  "rowHeight": 100,
  "margin": [16, 16],
  "containerPadding": [16, 16]
}

Dashboard Actions

Action Description
Edit Open drag-and-drop editor
Duplicate Create a copy of the dashboard
Delete Remove the dashboard
Set Default Make this the default dashboard

Widget System

Widget Structure

Each widget in the dashboard has:

{
  "id": "uuid-widget-instance-id",
  "widgetId": "core-dashboard:stat-card",
  "x": 0,
  "y": 0,
  "w": 3,
  "h": 2,
  "config": {
    "title": "Total Revenue",
    "dataSource": "analytics:revenue"
  }
}
Property Description
id Unique instance ID (auto-generated)
widgetId Widget definition ID (module:widget-name)
x Column position (0-11)
y Row position
w Width in columns (1-12)
h Height in rows
config Widget-specific configuration

Built-in Widget Types

The CoreDashboard module includes these base widgets:

Stat Card

Display a single metric with trend indicator.

{
  "widgetId": "core-dashboard:stat-card",
  "config": {
    "title": "Total Orders",
    "value": "2,847",
    "prefix": "",
    "suffix": "",
    "trend": 12.5,
    "icon": "ShoppingCart"
  }
}

Size: 3x2 (recommended)

Line Chart

Visualize trends over time.

{
  "widgetId": "core-dashboard:line-chart",
  "config": {
    "title": "Revenue Trend",
    "dataSource": "analytics:revenue-daily"
  }
}

Size: 6x3 (recommended)

Bar Chart

Compare values across categories.

{
  "widgetId": "core-dashboard:bar-chart",
  "config": {
    "title": "Sales by Category",
    "dataSource": "analytics:category-sales"
  }
}

Size: 6x3 (recommended)

Pie Chart

Show distribution or composition.

{
  "widgetId": "core-dashboard:pie-chart",
  "config": {
    "title": "Traffic Sources",
    "dataSource": "analytics:traffic-sources"
  }
}

Size: 4x3 (recommended)

Data Table

Display tabular data with columns.

{
  "widgetId": "core-dashboard:data-table",
  "config": {
    "title": "Category Performance",
    "columns": ["Category", "Revenue", "Change"],
    "dataSource": "analytics:category-table"
  }
}

Size: 6x4 (recommended)

List Widget

Show activity feed or list items.

{
  "widgetId": "core-dashboard:list",
  "config": {
    "title": "Recent Activity",
    "dataSource": "activity:recent"
  }
}

Size: 4x4 (recommended)

Gauge Widget

Display progress toward a goal.

{
  "widgetId": "core-dashboard:gauge",
  "config": {
    "title": "Monthly Target",
    "value": 72,
    "max": 100
  }
}

Size: 3x3 (recommended)

Recent Orders

Show latest orders with status.

{
  "widgetId": "core-dashboard:recent-orders",
  "config": {
    "title": "Recent Orders",
    "limit": 5
  }
}

Size: 4x4 (recommended)

Top Products

Display best-selling products.

{
  "widgetId": "core-dashboard:top-products",
  "config": {
    "title": "Top Products",
    "limit": 5,
    "period": "month"
  }
}

Size: 4x4 (recommended)

Quick Actions

Shortcut buttons for common tasks.

{
  "widgetId": "core-dashboard:quick-actions",
  "config": {
    "title": "Quick Actions",
    "actions": [
      { "icon": "Plus", "label": "New Order", "href": "/orders/create" },
      { "icon": "Package", "label": "Add Product", "href": "/products/create" }
    ]
  }
}

Size: 3x3 (recommended)

Widget Categories

Widgets are organized into categories:

Category Icon Description
Analytics BarChart3 Data visualization and metrics
Orders Package Order tracking and management
Customers Users Customer insights and data
Communication MessageSquare Messages and conversations
Fulfillment Truck Shipping and delivery
Inventory Box Stock and product management
Finance DollarSign Revenue and financial data
AI Operations Bot AI performance and metrics
Custom Puzzle Custom widgets

Widget Registry

Modules can register their own widgets using the WidgetRegistry service. This allows any module to contribute widgets to the dashboard without modifying the CoreDashboard module.

How It Works

  1. The WidgetRegistry is a singleton service provided by CoreDashboard
  2. Any module can inject it and register widgets during boot
  3. Widgets are automatically available in the dashboard editor
  4. Each widget has a unique ID in the format module:widget-name

Registering Widgets from Your Module

In your module's service provider, add a method to register dashboard widgets:

<?php

namespace Modules\YourModule;

use Illuminate\Support\ServiceProvider;

class YourModuleServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Other boot logic...

        // Register dashboard widgets
        $this->registerDashboardWidgets();
    }

    /**
     * Register dashboard widgets for this module
     */
    protected function registerDashboardWidgets(): void
    {
        // IMPORTANT: Check if CoreDashboard is installed first
        // This allows your module to work even if CoreDashboard is not installed
        if (!class_exists(\Modules\CoreDashboard\App\Services\WidgetRegistry::class)) {
            return;
        }

        $registry = $this->app->make(\Modules\CoreDashboard\App\Services\WidgetRegistry::class);

        $registry->registerMany([
            [
                'id' => 'your-module:stats',
                'moduleAlias' => 'your-module',
                'name' => 'Your Stats Widget',
                'description' => 'Display key metrics from your module',
                'category' => 'analytics',
                'icon' => 'BarChart',
                'defaultSize' => [
                    'w' => 3,
                    'h' => 2,
                    'minW' => 2,
                    'minH' => 2,
                    'maxW' => 6,
                    'maxH' => 3,
                ],
                'configSchema' => [
                    [
                        'key' => 'title',
                        'type' => 'text',
                        'label' => 'Title',
                        'default' => 'My Stats',
                    ],
                    [
                        'key' => 'metric',
                        'type' => 'select',
                        'label' => 'Metric',
                        'default' => 'total',
                        'options' => [
                            ['value' => 'total', 'label' => 'Total Count'],
                            ['value' => 'today', 'label' => 'Today'],
                            ['value' => 'week', 'label' => 'This Week'],
                        ],
                    ],
                ],
                'refreshConfig' => [
                    'enabled' => true,
                    'intervalSeconds' => 60,
                ],
            ],
            // Add more widgets here...
        ]);
    }
}

Real-World Example: Products Module

The Products module registers these widgets:

$registry->registerMany([
    // Product Stats Widget
    [
        'id' => 'products:stats',
        'moduleAlias' => 'products',
        'name' => 'Product Stats',
        'description' => 'Overview of product inventory metrics',
        'category' => 'inventory',
        'icon' => 'Package',
        'defaultSize' => ['w' => 3, 'h' => 2, 'minW' => 2, 'minH' => 2, 'maxW' => 6, 'maxH' => 3],
        'configSchema' => [
            ['key' => 'title', 'type' => 'text', 'label' => 'Title', 'default' => 'Product Stats'],
            ['key' => 'metric', 'type' => 'select', 'label' => 'Metric', 'default' => 'total', 'options' => [
                ['value' => 'total', 'label' => 'Total Products'],
                ['value' => 'active', 'label' => 'Active Products'],
                ['value' => 'out_of_stock', 'label' => 'Out of Stock'],
                ['value' => 'low_stock', 'label' => 'Low Stock'],
            ]],
        ],
        'refreshConfig' => ['enabled' => true, 'intervalSeconds' => 60],
    ],

    // Low Stock Alert Widget
    [
        'id' => 'products:low-stock-alert',
        'moduleAlias' => 'products',
        'name' => 'Low Stock Alert',
        'description' => 'List of products running low on stock',
        'category' => 'inventory',
        'icon' => 'AlertTriangle',
        'defaultSize' => ['w' => 4, 'h' => 4, 'minW' => 3, 'minH' => 3, 'maxW' => 6, 'maxH' => 8],
        'configSchema' => [
            ['key' => 'title', 'type' => 'text', 'label' => 'Title', 'default' => 'Low Stock Alert'],
            ['key' => 'threshold', 'type' => 'number', 'label' => 'Stock Threshold', 'default' => 10],
            ['key' => 'limit', 'type' => 'number', 'label' => 'Max Items', 'default' => 10],
        ],
        'refreshConfig' => ['enabled' => true, 'intervalSeconds' => 120],
    ],
]);

Available Module Widgets

These modules currently provide dashboard widgets:

Module Widget ID Description
Products products:stats Product inventory metrics
Products products:low-stock-alert Low stock product list
Products products:by-category Products by category chart
Products products:inventory-value Total inventory value
Orders orders:overview Order count metrics
Orders orders:by-status Orders by status chart
Orders orders:revenue-trend Revenue over time chart
Orders orders:pending Pending orders list
Orders orders:aov Average order value

Widget Definition Schema

Property Type Required Description
id string Yes Unique identifier (module:widget-name)
moduleAlias string Yes Module that provides this widget
name string Yes Display name
description string No Brief description
category string Yes Category for grouping
icon string No Lucide icon name
defaultSize object Yes Default dimensions
configSchema array No Configuration options
refreshConfig object No Auto-refresh settings

Config Schema Types

Type Description
text Single-line text input
textarea Multi-line text input
number Numeric input
select Dropdown selection
checkbox Boolean toggle
color Color picker
icon Icon selector

API Reference

Dashboards

GET    /api/v1/dashboard/dashboards              # List all dashboards
GET    /api/v1/dashboard/dashboards/default      # Get default dashboard
POST   /api/v1/dashboard/dashboards              # Create dashboard
GET    /api/v1/dashboard/dashboards/{id}         # Get dashboard by ID
GET    /api/v1/dashboard/dashboards/slug/{slug}  # Get dashboard by slug
PUT    /api/v1/dashboard/dashboards/{id}         # Update dashboard
DELETE /api/v1/dashboard/dashboards/{id}         # Delete dashboard
POST   /api/v1/dashboard/dashboards/{id}/duplicate    # Duplicate dashboard
PUT    /api/v1/dashboard/dashboards/{id}/positions    # Update widget positions

Templates

GET    /api/v1/dashboard/dashboards/templates     # List available templates
POST   /api/v1/dashboard/dashboards/from-template # Create from template

Widgets

GET    /api/v1/dashboard/widgets                  # List all widget definitions
GET    /api/v1/dashboard/widgets/grouped          # Get widgets grouped by category
GET    /api/v1/dashboard/widgets/categories       # List all categories
GET    /api/v1/dashboard/widgets/search?q={query} # Search widgets
GET    /api/v1/dashboard/widgets/category/{cat}   # Get widgets by category
GET    /api/v1/dashboard/widgets/module/{alias}   # Get widgets by module
GET    /api/v1/dashboard/widgets/definition/{id}  # Get widget definition
GET    /api/v1/dashboard/widgets/data/{source}    # Get widget data

Widget Instances (on Dashboards)

POST   /api/v1/dashboard/dashboards/{id}/widgets              # Add widget
PUT    /api/v1/dashboard/dashboards/{id}/widgets/{instanceId} # Update widget
DELETE /api/v1/dashboard/dashboards/{id}/widgets/{instanceId} # Remove widget

Frontend Integration

Dashboard Page

The main dashboard view (/dashboard) displays:

  • Dashboard selector dropdown
  • Current dashboard with rendered widgets
  • Edit and action buttons

Edit Page

The edit page (/dashboard/{id}/edit) provides:

  • Drag-and-drop grid layout (react-grid-layout)
  • Widget library sidebar
  • Widget configuration panel
  • Auto-save on position changes

Widget Renderer Component

The WidgetRenderer component handles widget display:

import { WidgetRenderer } from '@/components/dashboard/widget-renderer';

<WidgetRenderer
  widget={widgetInstance}
  definition={widgetDefinition}
/>

Configuration

Module Configuration

Located at modules/CoreDashboard/backend/Config/config.php:

return [
    // Default grid layout
    'layout' => [
        'columns' => 12,
        'row_height' => 100,
        'margin' => [16, 16],
        'container_padding' => [16, 16],
    ],

    // Widget data caching
    'cache' => [
        'enabled' => true,
        'ttl' => 60, // seconds
        'prefix' => 'dashboard_widget_',
    ],

    // Auto-refresh limits
    'refresh' => [
        'min_interval' => 10,  // minimum seconds
        'max_interval' => 3600, // maximum seconds
    ],

    // System limits
    'limits' => [
        'max_dashboards_per_user' => 20,
        'max_widgets_per_dashboard' => 50,
    ],
];

Data Model

Dashboard

id: integer (primary key)
name: string
slug: string (unique)
description: text (nullable)
is_default: boolean
is_shared: boolean
layout: json
widgets: json
created_by: integer (foreign key)
created_at: timestamp
updated_at: timestamp
deleted_at: timestamp (nullable)

Layout JSON Structure

{
  "columns": 12,
  "rowHeight": 100,
  "margin": [16, 16],
  "containerPadding": [16, 16]
}

Widgets JSON Structure

[
  {
    "id": "uuid",
    "widgetId": "module:widget-type",
    "x": 0,
    "y": 0,
    "w": 4,
    "h": 3,
    "config": {}
  }
]

Best Practices

Dashboard Design

  • Keep it focused: Each dashboard should have a clear purpose
  • Use consistent sizing: Align widgets to grid for cleaner layouts
  • Group related metrics: Place related widgets near each other
  • Consider hierarchy: Put most important metrics at the top-left

Widget Development

  • Unique IDs: Use module:widget-name format for widget IDs
  • Sensible defaults: Provide reasonable default configurations
  • Size constraints: Set appropriate min/max dimensions
  • Error handling: Handle loading and error states gracefully

Performance

  • Enable caching: Use widget data caching for expensive queries
  • Appropriate refresh rates: Don't refresh faster than needed
  • Limit widgets: Too many widgets can slow down the page

Troubleshooting

Dashboard Not Loading

  1. Check browser console for JavaScript errors
  2. Verify API endpoints are accessible
  3. Ensure authentication token is valid
  4. Check network tab for failed requests

Widget Not Displaying

  1. Verify widget definition is registered
  2. Check that module providing the widget is enabled
  3. Confirm widget data source returns valid data
  4. Look for errors in widget configuration

Drag-and-Drop Not Working

  1. Ensure react-grid-layout styles are imported
  2. Check that container has valid width
  3. Verify isDraggable is not set to false
  4. Look for conflicting CSS styles

Widget Data Not Updating

  1. Check cache TTL configuration
  2. Verify refresh interval settings
  3. Ensure data source endpoint is working
  4. Clear browser cache and reload

Next Steps