Filament Popup Modal Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require maystro/filament-popup-modal
   

   Publish the config file:

   php artisan vendor:publish --provider="Maystro\FilamentPopupModal\FilamentPopupModalServiceProvider"
   

2. Basic Usage Register the modal in your Filament resource/page:

   use Maystro\FilamentPopupModal\Modal;
   
   public function getModal(): Modal
   {
       return Modal::make('Confirm Action')
           ->content('Are you sure you want to proceed?')
           ->action('Confirm', fn() => $this->performAction())
           ->cancel('Cancel');
   }
   

3. First Use Case Trigger the modal from a button in your Filament view:

   <x-filament-actions::modal-button
       action="getModal"
       label="Delete Record"
       icon="heroicon-o-trash"
   />
   

Where to Look First

• Documentation: Check the package’s README.md for basic examples and API reference.
• Config File: config/filament-popup-modal.php for global settings like default animations or theme overrides.
• Service Provider: FilamentPopupModalServiceProvider for bootstrapping logic.

Implementation Patterns

Common Workflows

1. Progress Bars Use for async operations (e.g., file uploads):

   Modal::make('Uploading')
       ->progressBar()
       ->action('Upload', fn() => $this->uploadFiles())
       ->onProgressUpdated(fn(int $progress) => $this->updateProgress($progress));
   

2. Dynamic Content Pass data to the modal via closures:

   Modal::make('Edit User')
       ->content(fn() => view('filament.modals.edit-user', ['user' => $this->record]))
       ->action('Save', fn() => $this->save());
   

3. Theme Integration Extend default themes (e.g., dark mode):

   Modal::make('Theme Example')
       ->theme('dark')
       ->content('Custom dark-themed content');
   

4. Nested Modals Trigger a secondary modal from within another:

   Modal::make('Primary Modal')
       ->action('Open Secondary', fn() => $this->getSecondaryModal());
   

Integration Tips

• Filament Resources/Pages: Use getModals() in your resource/page class to register modals globally.
• Livewire Components: Attach modals to Livewire components for dynamic interactions:

  public function mount()
  {
      $this->modal = Modal::make('Livewire Modal')
          ->action('Submit', fn() => $this->submitForm());
  }
  

• Form Integration: Combine with Filament Forms for data collection:

  Modal::make('Create Record')
      ->form(YourForm::make())
      ->action('Create', fn() => $this->createRecord());
  

Gotchas and Tips

Pitfalls

1. Modal Stacking

   • Issue: Modals may stack unexpectedly if not closed properly.
   • Fix: Use ->closeAfterAction() to auto-close after actions:

     Modal::make('Auto-Close')
         ->action('OK', fn() => $this->doSomething())
         ->closeAfterAction();
     

2. Progress Bar Stuck

   • Issue: Progress bars may freeze if the underlying operation doesn’t update progress.
   • Fix: Ensure onProgressUpdated is called periodically:

     $this->emit('progress-updated', $progress); // If using Livewire
     

3. Theme Conflicts

   • Issue: Custom themes may override Filament’s default styles.
   • Fix: Use ->theme('custom') and override CSS in your assets:

     .filament-popup-modal-theme-custom { ... }
     

4. Callback Delays

   • Issue: Async callbacks may not trigger due to timing issues.
   • Fix: Use ->deferAction() for delayed execution:

     Modal::make('Deferred Action')
         ->action('Later', fn() => $this->deferAction())
         ->deferAction();
     

Debugging Tips

• Log Modal Events: Use ->onOpened()/->onClosed() for debugging:

  Modal::make('Debug')
      ->onOpened(fn() => Log::info('Modal opened'))
      ->onClosed(fn() => Log::info('Modal closed'));
  

• Inspect HTML: Check the rendered modal structure in browser dev tools for styling issues.
• Clear Cache: Run php artisan optimize:clear if modals fail to load.

Extension Points

1. Custom Animations Override animations in the config:

   'animations' => [
       'open' => 'fadeIn',
       'close' => 'fadeOut',
   ],
   

2. Modal Presets Create reusable presets in a trait:

   trait UsesCustomModals
   {
       public function confirmDeleteModal(): Modal
       {
           return Modal::make('Delete')
               ->content('Are you sure?')
               ->action('Delete', fn() => $this->delete())
               ->cancel('Cancel');
       }
   }
   

3. Event Listeners Listen for modal events globally:

   FilamentPopupModal::listen('modal.opened', fn(Modal $modal) => {
       // Logic here
   });