Custom Dashboards Integration

Data Lens integrates with Filament Custom Dashboards to let users add report summaries as widgets on drag-and-drop dashboards.

Prerequisites

  • Data Lens v2.x (Filament 4.x) or v3.x (Filament 5.x)
  • Filament Custom Dashboards Plugin installed and configured
  • At least one Data Lens report with a configured summary

How It Works

Data Lens provides four widget types that appear in the Custom Dashboards widget picker:

| Widget | Description | Configuration | |--------|-------------|---------------| | Data Lens Stats | Displays statistics from a report summary (KPIs, counts, totals) | Report + Summary + Stats Widget | | Data Lens Chart | Renders a chart from a report summary (line, bar, pie, etc.) | Report + Summary + Chart Widget | | Data Lens Summary Table | Shows summary data as a formatted table with grouping and aggregations | Report + Summary | | Data Lens Report Table | Displays the full report results table with sortable columns | Report |

Data Lens automatically registers the Livewire components for these widgets when the Custom Dashboards plugin is detected. To make them available in the Custom Dashboards widget picker, you must also register them in your panel provider (see setup below).

Setup

1. Install Custom Dashboards Plugin

Follow the Custom Dashboards installation guide to install and configure the plugin.

2. Run Migrations

Data Lens includes a migration for the widget configuration table. If you have already published Data Lens migrations previously, publish the new migration first:

php artisan vendor:publish --tag="data-lens-migrations"
php artisan migrate

This creates the data_lens_cd_widget_configurations table that stores which report, summary, and widget each dashboard widget should display.

Note: If you installed Data Lens using php artisan data-lens:install, the migration is published automatically.

3. Register Widgets in Your Panel

Add Data Lens widgets to the Custom Dashboards plugin in your panel provider:

use Filament\CustomDashboardsPlugin\CustomDashboardsPlugin;
use Padmission\DataLens\DataLensPlugin;
use Padmission\DataLens\Widgets\CustomDashboards\DataLensChartWidget;
use Padmission\DataLens\Widgets\CustomDashboards\DataLensReportTableWidget;
use Padmission\DataLens\Widgets\CustomDashboards\DataLensStatsWidget;
use Padmission\DataLens\Widgets\CustomDashboards\DataLensSummaryTableWidget;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            DataLensPlugin::make(),
            CustomDashboardsPlugin::make()
                ->widgets([
                    DataLensChartWidget::class,
                    DataLensReportTableWidget::class,
                    DataLensStatsWidget::class,
                    DataLensSummaryTableWidget::class,
                    // ... your other custom dashboard widgets
                ]),
        ]);
}

Creating a Dashboard with Data Lens Widgets

Step 1: Create a Report with Summaries

Before adding widgets to a dashboard, ensure you have at least one Data Lens report with a configured summary. Summaries define the aggregations and groupings that power the widgets.

See Usage Guide for details on creating reports and summaries.

Step 2: Add a Widget to a Dashboard

  1. Navigate to Custom Dashboards in your panel
  2. Create or edit a dashboard
  3. Click "Add Widget" and select one of the Data Lens widget types
  4. Configure the widget:
    • Report: Select which Data Lens report to pull data from
    • Summary: Choose a summary from the selected report (not required for Report Table)
    • Widget (Stats and Chart only): Pick which specific widget from the summary to display

Step 3: Arrange and Resize

Use the drag-and-drop interface to position and resize widgets. Each widget respects the column span set in the Custom Dashboards layout, or falls back to its default:

  • Stats and Chart widgets default to their summary-defined span
  • Summary Table and Report Table widgets default to full width

Widget Details

Data Lens Stats Widget

Displays a stats overview from a report summary. This renders the same KPI cards you see on the report's summary tab -- totals, counts, averages, etc.

Configuration form fields:

  • Report (searchable dropdown)
  • Summary (filtered by selected report)
  • Widget (filtered by selected summary, shows only stats-type widgets)

Data Lens Chart Widget

Renders a chart visualization from a report summary. Supports all chart types configured in the summary (line, bar, pie, doughnut, etc.).

Configuration form fields:

  • Report (searchable dropdown)
  • Summary (filtered by selected report)
  • Widget (filtered by selected summary, shows only chart-type widgets)

Data Lens Summary Table Widget

Displays summary data as a formatted table with grouping columns and aggregation values. This is useful for tabular breakdowns like "Revenue by Category" or "Orders by Status".

Configuration form fields:

  • Report (searchable dropdown, filtered to reports with summaries)
  • Summary (filtered by selected report)

The table automatically renders:

  • Grouping columns as row identifiers
  • Aggregation values with proper formatting (currency, percentages, etc.)

Data Lens Report Table Widget

Displays the full results table from a Data Lens report with sortable columns. Unlike the Summary Table which shows aggregated data, this widget renders the raw report query results -- useful for showing detailed record-level data on a dashboard.

Configuration form fields:

  • Report (searchable dropdown)

The table renders all configured report columns with sorting support and defaults to full width.

Auto-Registration

Data Lens conditionally registers the Livewire components for its Custom Dashboard widgets only when the Custom Dashboards plugin is installed:

if (class_exists(CustomDashboardsPlugin::class)) {
    // Register Livewire components for Data Lens dashboard widgets
}

This means Data Lens remains fully functional without the Custom Dashboards plugin -- the integration is entirely optional. The Livewire components are registered automatically, but you still need to register the widget classes in your panel provider's CustomDashboardsPlugin::make()->widgets([...]) array so they appear in the widget picker.

Multi-Tenant Support

When tenant awareness is enabled in Data Lens, dashboard widgets automatically scope their data to the current tenant. The report selector only shows reports belonging to the current tenant, and all query data respects tenant boundaries.

Troubleshooting

Widgets not appearing in the widget picker

  • Verify the Custom Dashboards plugin is installed: composer show filament/custom-dashboards-plugin
  • Ensure all four widgets are registered in your panel provider's CustomDashboardsPlugin::make()->widgets([...]) array
  • Clear cached views: php artisan view:clear

"No summary data available" message

  • The selected report may not have any summaries configured
  • The summary may not have any widgets defined (for Stats and Chart types)
  • Check that the report has data -- empty reports produce empty summaries

Widget shows stale data

Summary data is computed live from the report's underlying query. If the data appears stale:

  • Clear the Data Lens cache: php artisan data-lens:clear-cache
  • Check that the report's model and filters are correct