Filament Progressbar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require njxqlus/filament-progressbar
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Njxqlus\FilamentProgressbar\FilamentProgressbarServiceProvider"
   

2. First Integration: Add the plugin to your PanelProvider (e.g., AdminPanelProvider):

   use Njxqlus\FilamentProgressbar\FilamentProgressbarPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(FilamentProgressbarPlugin::make());
   }
   

3. First Use Case: Immediately observe the progress bar during navigation between Filament pages (e.g., from Resources to Pages or between table records).

Implementation Patterns

Core Workflows

1. Customization via PanelProvider: Configure appearance globally in the panel() method:

   FilamentProgressbarPlugin::make()
       ->color('#29b')          // Custom color (hex, rgb, or named)
       ->height(4)             // Height in pixels (default: 3)
       ->showOnMobile(true)    // Enable/disable on mobile
       ->animate(true);        // Enable/disable animation
   

2. Conditional Rendering: Disable for specific pages by overriding the shouldRender() method in a custom plugin class:

   class CustomProgressbarPlugin extends FilamentProgressbarPlugin
   {
       public static function shouldRender(): bool
       {
           return !request()->routeIs('filament.pages.*');
       }
   }
   

3. Dynamic Styling: Use Blade directives to inject custom CSS/JS:

   FilamentProgressbarPlugin::make()
       ->extraCss('
           .filament-progressbar { transition: width 0.3s ease-in-out !important; }
       ')
       ->extraJs('
           document.addEventListener("filament-progressbar-update", (e) => {
               console.log("Progress:", e.detail.progress);
           });
       ');
   

4. Integration with Filament Events: Trigger custom events (e.g., for analytics):

   FilamentProgressbarPlugin::make()
       ->onProgressUpdate(fn ($progress) => {
           // Log progress or dispatch an event
           event(new ProgressUpdated($progress));
       });
   

Gotchas and Tips

Pitfalls

1. Mobile Responsiveness:

   • Default behavior hides the bar on mobile (showOnMobile(false)). Test on target devices to ensure usability.
   • Override with CSS if needed:

     @media (max-width: 768px) {
         .filament-progressbar { display: block !important; }
     }
     

2. Performance Impact:

   • Heavy animations or complex pages may cause jank. Use animate(false) for smoother performance:

     FilamentProgressbarPlugin::make()->animate(false);
     

3. Route-Specific Issues:

   • If the bar doesn’t appear on certain routes, verify:
     • The PanelProvider is correctly registered.
     • No JavaScript errors (check browser console).
     • The route isn’t excluded via shouldRender().

4. Caching Conflicts:

   • Clear Filament’s view cache if changes aren’t reflected:

     php artisan filament:cache:clear
     

Debugging Tips

1. Inspect Element: Use browser dev tools to check if the progress bar DOM element exists (<div class="filament-progressbar">). If missing, the plugin may not be registered.

2. Log Progress Events: Add temporary logging to debug progress updates:

   ->onProgressUpdate(fn ($progress) => {
       \Log::debug("Progress:", $progress);
   })
   

3. Disable Other Plugins: Temporarily disable other Filament plugins to isolate conflicts.

Extension Points

1. Custom Progress Logic: Extend the plugin to show progress for AJAX-heavy operations (e.g., bulk actions):

   class AjaxProgressbarPlugin extends FilamentProgressbarPlugin
   {
       public static function register(): void
       {
           \Filament\Support\Facades\FilamentAsset::registerScript(
               __DIR__.'/js/ajax-progress.js'
           );
       }
   }
   

2. Theming: Override the default Blade view (resources/views/vendor/filament-progressbar/progressbar.blade.php) for custom markup.

3. Localization: Add translations for dynamic text (e.g., "Loading...") via Filament’s localization system:

   FilamentProgressbarPlugin::make()
       ->translationPrefix('filament-progressbar');