Filament Peek Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require pboivin/filament-peek:"^4.1"
   

   Ensure you’re using Filament v3+ (compatible with Filament 3.x and 4.x).

2. Register the Plugin: Add to your PanelProvider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel {
       return $panel
           ->plugins([
               FilamentPeekPlugin::make(),
           ]);
   }
   

3. Publish Assets:

   php artisan filament:assets
   

   This generates the modal UI and JavaScript.

4. First Use Case: Add the Peekable trait to a Form or Table resource:

   use Pboivin\FilamentPeek\Concerns\Peekable;
   
   class PostResource extends Resource {
       use Peekable;
       // ...
   }
   

   Now, a "Preview" button appears in the top-right corner of the form.

Implementation Patterns

Core Workflows

1. Form Previews:

   • Use Peekable trait on Forms to enable preview before saving.
   • Customize the preview URL via peekUrl() method:

     public function peekUrl(): string {
         return route('posts.preview', $this->record);
     }
     

2. Table Row Previews:

   • Add Peekable to Tables to preview records inline:

     use Pboivin\FilamentPeek\Concerns\Peekable;
     
     class PostTable extends Table {
         use Peekable;
         // ...
     }
     

   • Override peekUrl() for dynamic routes (e.g., route('posts.show', $record)).

3. Custom Preview Logic:

   • Extend the modal content via peekView():

     public function peekView(): string {
         return view('filament.peek.custom-preview', ['record' => $this->record]);
     }
     

4. Conditional Peek:

   • Disable peek for specific records:

     public function canPeek(): bool {
         return $this->record->isPublished();
     }
     

Integration Tips

• Livewire Forms: Works seamlessly with Filament’s Livewire forms.
• API Resources: Useful for previewing API responses (e.g., peekUrl() returning an API endpoint).
• Testing: Mock the peekUrl() method in unit tests:

  $resource->shouldReceive('peekUrl')->andReturn('/fake-preview');
  

Gotchas and Tips

Pitfalls

1. Asset Publishing:

   • Forgetting php artisan filament:assets after installation breaks the modal UI.
   • Fix: Run the command in a fresh terminal or clear cached views (php artisan view:clear).

2. Route Conflicts:

   • If peekUrl() returns a non-existent route, the modal fails silently.
   • Debug: Check Laravel logs or use dd($this->peekUrl()) in peekUrl().

3. Caching Issues:

   • Changes to peekView() or peekUrl() may not reflect due to Blade caching.
   • Fix: Clear Filament’s cache:

     php artisan filament:cache-clear
     

4. Permission Denied:

   • The modal may not appear if the user lacks permissions for the underlying resource.
   • Fix: Ensure canPeek() returns true or adjust Filament’s policies.

Debugging Tips

• Inspect Modal Content: Override peekView() to return a debug view:

  public function peekView(): string {
      return view('filament.peek.debug', [
          'record' => $this->record,
          'url' => $this->peekUrl(),
      ]);
  }
  

  This reveals the rendered URL and data passed to the preview.

• Disable Peek Temporarily: Comment out the Peekable trait to isolate issues.

Extension Points

1. Custom Modal Styling: Publish the package’s views and override them:

   php artisan vendor:publish --tag="filament-peek-views"
   

   Modify resources/views/vendor/filament-peek/modal.blade.php.

2. Event Hooks: Listen for peek.opening or peek.closing events (if the package supports them) to add logic:

   event(new FilamentPeekOpening($record, $url));
   

3. Multi-Tab Support: For SPAs, ensure the modal closes when navigating away (e.g., via window.onbeforeunload).