Filament Layout Manager Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require asosick/filament-layout-manager
   

   Publish the config file:

   php artisan vendor:publish --provider="Asosick\FilamentLayoutManager\FilamentLayoutManagerServiceProvider" --tag="config"
   

2. First Use Case: Generate a new page using Artisan:

   php artisan make:layout-manager-page dashboard
   

   This creates a new page class in app/Filament/Pages/DashboardPage.php.

3. Register the Page: Add the page to your Filament admin panel configuration (e.g., app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->pages([
               // ...
               \App\Filament\Pages\DashboardPage::class,
           ]);
   }
   

4. Access the Page: Visit the page in your Filament admin panel to see the interactive layout manager UI.

Implementation Patterns

Core Workflows

1. Creating Dynamic Dashboards

• Use DashboardPage as a base for customizable dashboards.
• Define widgets/components in the $widgets property:

  public array $widgets = [
      \App\Filament\Widgets\StatsOverviewWidget::class,
      \App\Filament\Widgets\RecentActivityWidget::class,
  ];
  

• Users can drag, drop, and resize widgets via the UI.

2. Reusable Layout Components

• Extend LayoutManagerPage for custom pages:

  use Asosick\FilamentLayoutManager\Pages\LayoutManagerPage;
  
  class CustomPage extends LayoutManagerPage
  {
      protected static ?string $navigationIcon = 'heroicon-o-document-duplicate';
      protected static string $view = 'filament-layout-manager::pages.layout-manager';
  }
  

3. Passing Data to Widgets

• Use $widgetData to pass dynamic data to widgets:

  public function getWidgetData(): array
  {
      return [
          'stats' => Stats::query()->latest()->limit(5)->get(),
      ];
  }
  

• Access data in widgets via $this->widgetData['stats'].

4. Multiple Layouts

• Store layouts in the database (requires filament-layout-manager:install migration):

  php artisan migrate
  

• Users can save, load, and switch between layouts.

5. Integrating with Filament Pages

• Wrap the layout manager in a Filament page for additional controls:

  use Filament\Pages\Page;
  
  class Dashboard extends Page
  {
      public function mount(): void
      {
          LayoutManager::setPage($this);
      }
  
      public function render()
      {
          return view('filament-layout-manager::pages.layout-manager');
      }
  }
  

Integration Tips

• Widget Development: Ensure widgets extend Filament\Widgets\Widget and are registered in $widgets. Example:

  class StatsOverviewWidget extends Widget
  {
      protected static string $view = 'filament.widgets.stats-overview';
  }
  

• Customizing Layout UI: Override the default layout manager view by publishing assets:

  php artisan vendor:publish --provider="Asosick\FilamentLayoutManager\FilamentLayoutManagerServiceProvider" --tag="views"
  

  Then modify resources/views/vendor/filament-layout-manager/pages/layout-manager.blade.php.

• Conditional Widgets: Use closures in $widgets to conditionally include widgets:

  public array $widgets = [
      fn() => auth()->user()->can('view_stats') ? \App\Filament\Widgets\StatsWidget::class : null,
  ];
  

Gotchas and Tips

Pitfalls and Debugging

1. Widget Registration Issues:

   • Ensure all widget classes are fully qualified (e.g., \App\Filament\Widgets\...).
   • Verify widgets are listed in the $widgets property of the page class.
   • Debug: Check the browser console for errors if widgets fail to load.

2. Layout Not Saving:

   • Confirm the layouts table exists (run migrations if needed).
   • Ensure the LayoutManager facade is properly initialized in your page:

     public static function getLayoutManager(): LayoutManager
     {
         return app(LayoutManager::class);
     }
     

3. Data Not Passing to Widgets:

   • Verify getWidgetData() is defined and returns the expected array.
   • Check for typos in the data keys (e.g., $widgetData['stats'] vs. $widgetData['stat']).

4. Conflicting CSS/JS:

   • If the UI appears broken, clear Filament’s cache:

     php artisan filament:cache:clear
     

   • Disable other Filament plugins temporarily to isolate issues.

Configuration Quirks

1. Default Layout Behavior:

   • The package auto-generates a default layout if none is saved. To disable this, set default_layout to null in config/filament-layout-manager.php:

     'default_layout' => null,
     

2. Customizing Selection Options:

   • Rename widget options in the UI by overriding the getWidgetOptions() method in your page class:

     public function getWidgetOptions(): array
     {
         return [
             'stats' => 'Statistics',
             'activity' => 'Recent Activity',
         ];
     }
     

3. Extending LayoutManager:

   • To add custom logic (e.g., validation), extend the LayoutManager class:

     use Asosick\FilamentLayoutManager\LayoutManager as BaseLayoutManager;
     
     class CustomLayoutManager extends BaseLayoutManager
     {
         public function saveLayout(array $layout): void
         {
             // Custom logic before saving
             parent::saveLayout($layout);
         }
     }
     

   • Bind the custom class in AppServiceProvider:

     public function register(): void
     {
         $this->app->bind(
             \Asosick\FilamentLayoutManager\LayoutManager::class,
             \App\Services\CustomLayoutManager::class
         );
     }
     

Extension Points

1. Adding Header Actions: Use the $headerActions property to add buttons or dropdowns:

   public array $headerActions = [
       \Asosick\FilamentLayoutManager\Actions\ResetLayoutAction::class,
       \Asosick\FilamentLayoutManager\Actions\SaveLayoutAction::class,
   ];
   

2. Child Component Data Stores:

   • Why Use?: Isolate widget state or share data between widgets without polluting the parent page.
   • Implementation:

     use Filament\Forms\Components\Actions\Action;
     use Filament\Forms\Components\Field;
     
     public function form(FieldsForm $form): FieldsForm
     {
         return $form->schema([
             Field::make('shared_data')
                 ->label('Shared Data')
                 ->columnSpanFull(),
             Action::make('saveData')
                 ->action(fn() => $this->saveSharedData()),
         ]);
     }
     
     public function saveSharedData(): void
     {
         $this->callHook('saveSharedData');
     }
     

   • Access shared data in widgets via $this->callHook('getSharedData').

3. Custom Storage Backends:

   • Override the default database storage by implementing a custom LayoutRepository:

     use Asosick\FilamentLayoutManager\Repositories\LayoutRepositoryInterface;
     
     class CustomLayoutRepository implements LayoutRepositoryInterface
     {
         public function save(array $layout, string $pageClass): void
         {
             // Custom logic (e.g., save to Redis, S3, etc.)
         }
     
         public function get(string $pageClass): ?array
         {
             // Custom logic
         }
     }
     

   • Bind the repository in AppServiceProvider:

     $this->app->bind(
         LayoutRepositoryInterface::class,
         CustomLayoutRepository::class
     );