Filament Dynamic Dashboard Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require mddev31/filament-dynamic-dashboard
   php artisan vendor:publish --tag=filament-dynamic-dashboard-migrations
   php artisan migrate
   php artisan filament:assets
   

2. Create a Dashboard Page: Extend MDDev\DynamicDashboard\Pages\DynamicDashboard in your Filament panel:

   namespace App\Filament\Pages;
   
   use MDDev\DynamicDashboard\Pages\DynamicDashboard;
   
   class MyDashboard extends DynamicDashboard {}
   

3. Create a Dynamic Widget: Implement DynamicWidget and use helper traits:

   use MDDev\DynamicDashboard\Concerns\{HasEmptySettings, HasSizeDefaults};
   use MDDev\DynamicDashboard\Contracts\DynamicWidget;
   
   class MyWidget extends Filament\Widgets\StatsOverviewWidget implements DynamicWidget {
       use HasEmptySettings, HasSizeDefaults;
       public static function getWidgetLabel(): string { return 'My Widget'; }
   }
   

4. Register Widget: Add the widget to your Filament panel’s widget list (via getWidgets() in your panel provider).

5. Access Dashboard: Visit the dashboard page in Filament. Click + Widget to add your dynamic widget to the canvas.

First Use Case

Build a customizable analytics dashboard:

• Add a SalesChartWidget with configurable settings (e.g., time range, metrics).
• Use getDynamicDashboardDefaultWidth() to set a default 6-column width.
• Lock height with getDynamicDashboardMinHeight()/getDynamicDashboardMaxHeight().
• Drag the widget to a new section (e.g., "KPIs") and resize it interactively.

Implementation Patterns

Core Workflows

1. Widget Development:

   • Settings: Use getSettingsFormSchema() to expose widget-specific configs (e.g., chart type, data source).

     public static function getSettingsFormSchema(): array {
         return [Select::make('chartType')->options(['line', 'bar'])];
     }
     

   • Size Constraints: Override only constrained axes (e.g., lock height for charts):

     public static function getDynamicDashboardMaxHeight(): int { return 3; }
     

   • Filters: Leverage InteractsWithPageFilters for dashboard-wide filters:

     use Filament\Widgets\Concerns\InteractsWithPageFilters;
     

2. Dashboard Layouts:

   • Templates: Assign a template_key (e.g., 'split-6') to a dashboard via the manager UI.
   • Sections: Use named sections (e.g., 'main', 'sidebar') to organize widgets logically.
   • Presets: Start with built-in presets ('standard-12', 'kpi-4') and customize via JSON templates.

3. Access Control:

   • Roles: Integrate Spatie’s laravel-permission to restrict dashboard visibility:

     public static function canDisplay(): bool {
         return auth()->user()->hasRole('analyst');
     }
     

   • Personal Dashboards: Mark dashboards as is_personal to scope them to the creator.

4. Filter Management:

   • Defaults: Set default filter values via getDefaultFilterSchema():

     public static function getDefaultFilterSchema(): array {
         return [TextInput::make('date')->default('2024-01-01')];
     }
     

   • Visibility: Toggle filter visibility per-dashboard in the manager UI.

Integration Tips

• Livewire Widgets: Use showWidgetLoader() to control loading states:

  public static function showWidgetLoader(): bool { return true; }
  

• Custom Templates: Extend layouts by adding JSON files to resources/json/dynamic-dashboard/ (e.g., custom-8.json).
• Migration Hooks: Override canEdit() to disable edits for read-only dashboards:

  public static function canEdit(): bool { return false; }
  

• Asset Optimization: Rebuild assets after changes:

  php artisan filament:assets
  

Gotchas and Tips

Pitfalls

1. Upgrade Migrations:

   • The v2 upgrade migration is irreversible. Backup your database before running:

     php artisan migrate --pretend  # Review changes first
     

   • Post-upgrade, update widget classes to include HasSizeDefaults or implement size methods manually.

2. Size Method Conflicts:

   • Avoid naming collisions with Filament’s instance methods (e.g., getMaxHeight()). Use the getDynamicDashboard... prefix.

3. GridStack.js Quirks:

   • Drag Limits: Widgets cannot be dragged outside their section’s column bounds. Use getDynamicDashboardMaxWidth() to enforce limits.
   • Resizing Gaps: Set getDynamicDashboardMinWidth()/getDynamicDashboardMinHeight() to 1 to prevent widgets from collapsing.

4. Filter Persistence:

   • Defaults are stored as raw values. Use resolveFilterDefaults() to transform them (e.g., convert strings to Carbon instances):

     public static function resolveFilterDefaults(): array {
         return ['date' => Carbon::parse($defaults['date'])];
     }
     

5. Performance:

   • Heavy Widgets: Charts or tables with large datasets may lag during drag/resize. Use showWidgetLoader() to mask delays.
   • Template Bloat: Avoid overly complex JSON templates (e.g., nested sections). Stick to flat structures for performance.

Debugging

1. Layout Issues:

   • Check the template_key in the database (dashboards table). Verify the JSON file exists in resources/json/dynamic-dashboard/.
   • Clear Filament’s view cache:

     php artisan view:clear
     

2. Widget Settings:

   • Validate getSettingsCasts() matches the form schema. Mismatched types cause silent failures.
   • Dump settings during development:

     dd($this->settings); // Inside widget's mount() or render() methods
     

3. Permission Errors:

   • Ensure Spatie’s laravel-permission is installed if using role-based access:

     composer require spatie/laravel-permission
     

   • Test permissions with:

     dd(auth()->user()->getAllPermissions());
     

4. Asset Loading:

   • If GridStack.js fails to load, verify the filament:assets publish step ran:

     php artisan filament:assets
     

   • Check browser console for 404s on /vendor/gridstack/gridstack.js.

Extension Points

1. Custom Templates:

   • Add new layouts by creating JSON files in resources/json/dynamic-dashboard/:

     {
       "key": "custom-6",
       "label": "Custom 6-Column",
       "columns": 6,
       "sections": [
         {"slug": "main", "columns": 6, "rowHeight": 20}
       ]
     }
     

   • Reference the new key in the dashboard manager.

2. Widget Settings Validation:

   • Extend getSettingsFormSchema() with validation rules:

     TextInput::make('limit')
         ->required()
         ->integer()
         ->min(1)
         ->max(100)
     

3. Dynamic Sections:

   • Create sections programmatically by extending the DynamicDashboard class:

     protected function getDefaultTemplateKey(): string {
         return 'custom-template';
     }
     

4. Event Listeners:

   • Hook into dashboard events (e.g., widget added/removed) via Filament’s event system:

     use MDDev\DynamicDashboard\Events\DashboardWidgetAdded;
     
     DashboardWidgetAdded::listen(function (DashboardWidgetAdded $event) {
         // Log or process widget additions
     });
     

5. API Access:

   • Expose dashboard layouts via API by extending the DynamicDashboard resource:

     public function toArray($request): array {
         return [
             'layout' => $this->layout,
             'widgets' => $this->widgets,
         ];
     }