Filament Multi Widget Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require vodafoneziggonl/filament-multi-widget
   

   Ensure compatibility with your Filament version (5.x for Filament 5.x, 3.x for Filament 4.x).

2. Publish Assets (if needed) Run php artisan vendor:publish --provider="VodafoneZiggoNL\MultiWidget\MultiWidgetServiceProvider" to customize default styles (e.g., tab styling).

3. First Use Case Create a simple multi-widget combining two existing widgets:

   // app/Filament/Widgets/DashboardMultiWidget.php
   use VodafoneZiggoNL\MultiWidget\MultiWidget;
   
   class DashboardMultiWidget extends MultiWidget
   {
       public array $widgets = [
           \App\Filament\Widgets\StatsOverview::class,
           \App\Filament\Widgets\RecentActivity::class,
       ];
   
       public string $heading = 'Dashboard Analytics';
   }
   

   Register it in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->widgets([
               DashboardMultiWidget::class,
           ]);
   }
   

Implementation Patterns

Core Workflows

1. Tab-Based Organization

   • Group related widgets (e.g., "User Analytics," "System Health") into a single widget with tabs.
   • Example:

     public array $widgets = [
         UserActivityWidget::class,
         UserEngagementWidget::class,
     ];
     public string $heading = 'User Insights';
     

2. Dynamic Widget Loading

   • Use dependency injection to pass data to sub-widgets:

     public function getWidgets(): array
     {
         return [
             fn () => new StatsWidget($this->userId),
             fn () => new AlertsWidget($this->alertThreshold),
         ];
     }
     

3. Conditional Widgets

   • Hide/show tabs based on user roles or permissions:

     public function getWidgets(): array
     {
         $widgets = [AdminStats::class];
         if (auth()->user()->can('view_reports')) {
             $widgets[] = SalesReports::class;
         }
         return $widgets;
     }
     

4. Nested Multi-Widgets

   • Combine multi-widgets for hierarchical dashboards:

     // Parent MultiWidget
     public array $widgets = [
         MarketingMultiWidget::class,
         SupportMultiWidget::class,
     ];
     

5. Custom Tab Icons/Colors

   • Override default tab styling via published config or CSS:

     protected static string $tabIcon = 'heroicon-o-chart-bar';
     protected static string $tabColor = 'success';
     

Integration Tips

• Leverage Filament’s Widget Features: Sub-widgets inherit Filament’s features (e.g., polling, columnSpanFull).

  public array $widgets = [
      fn () => new RecentOrdersWidget(['polling' => 60]),
  ];
  

• Shared State: Use Filament’s use trait to share data between tabs:

  use Filament\Widgets\Concerns\HasWidgets;
  
  public function mount(): void
  {
      $this->sharedData = $this->getSharedData();
  }
  

• Localization: Translate tab labels via Filament’s __() helper:

  public string $heading = __('widgets.multi.heading');
  

Gotchas and Tips

Pitfalls

1. Widget Initialization Order

   • Sub-widgets are instantiated lazily (on first tab load). Avoid relying on constructor state shared across tabs.
   • Fix: Use mount() or getWidgets() for initialization.

2. CSS Conflicts

   • Default tab styling may clash with Filament themes. Override via:

     /* resources/css/filament/multi-widget.css */
     .filament-multi-widget-tabs [data-tab] {
         background: #f0f0f0;
     }
     

3. Performance with Heavy Widgets

   • Tabs load widgets on-demand. For large datasets, use polling or lazy-loading:

     fn () => new DataTableWidget(['query' => fn () => User::lazy()]),
     

4. Missing Tab Labels

   • If a widget lacks a heading, tabs will show its class name. Ensure all sub-widgets define:

     protected static string $heading = 'Orders';
     

5. Service Provider Registration

   • Forgetting to register the provider in config/app.php under providers will break the widget.

Debugging

• Check Widget Loading: Use dd($this->widgets) in getWidgets() to verify the array structure.
• Tab Switching Issues: Clear Filament’s cache (php artisan filament:cache:clear) if tabs fail to render.
• Console Errors: Inspect browser dev tools for missing assets (e.g., un-published CSS).

Extension Points

1. Custom Tab Rendering Override the default tab template:

   public function getTabView(): string
   {
       return 'filament-multi-widget::tabs.custom';
   }
   

2. Widget Filtering Dynamically filter widgets based on context:

   public function getWidgets(): array
   {
       return array_filter($this->widgets, fn ($widget) => $this->shouldShow($widget));
   }
   

3. Event Hooks Listen to tab changes via JavaScript:

   document.addEventListener('filament-multi-widget-tab-changed', (e) => {
       console.log('Active tab:', e.detail.tab);
   });
   

4. Server-Side Logic Use Filament’s beforeRender to modify widgets before display:

   protected function beforeRender(): void
   {
       $this->widgets = collect($this->widgets)->map(fn ($widget) => $this->modifyWidget($widget));
   }