Filament Topbar Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require jeffersongoncalves/filament-topbar:^3.0
   

   • Automatically registers the service provider and replaces the default Filament topbar.

2. Enable in Admin Panel: Add the plugin to your AdminPanelProvider.php:

   use JeffersonGoncalves\Filament\Topbar\TopbarPlugin;
   
   ->plugins([
       TopbarPlugin::make(),
   ])
   

3. First Use Case:

   • Refresh your Filament admin panel. The default topbar is now replaced with the enhanced version.
   • No additional configuration is required for basic functionality.

Implementation Patterns

Usage Patterns

1. Basic Integration:

   • The plugin replaces the default topbar with minimal setup. No manual component registration is needed.

2. Customizing the Topbar View:

   • Publish the default view for customization:

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

   • Modify the published Blade file at resources/views/vendor/filament-topbar/components/topbar.blade.php.

3. Adding Custom Elements:

   • Extend the topbar by injecting custom Blade components or JavaScript:

     // In your AdminPanelProvider.php
     TopbarPlugin::make()
         ->customTopbarContent(function () {
             return view('custom.topbar-content');
         })
     

4. Conditional Rendering:

   • Use Filament’s built-in logic to conditionally show/hide elements based on user roles or permissions:

     TopbarPlugin::make()
         ->showOnPages(function ($page) {
             return $page instanceof YourCustomPage;
         })
     

5. Theming:

   • Override Tailwind CSS classes or add custom styles via your Filament panel’s CSS file.

Workflows

• Iterative Development:

  • Test changes in the published view file without touching the package directly.
  • Use php artisan view:clear to refresh Blade views after modifications.

• Plugin Composition:

  • Combine with other Filament plugins (e.g., notifications, search) by leveraging the topbar’s additional slots:

    TopbarPlugin::make()
        ->extraTopbarItems([
            YourCustomTopbarItem::class,
        ])
    

• Localization:

  • Localize topbar labels by extending the Blade file and using Laravel’s __() helper.

Integration Tips

• Filament Widgets:

  • Integrate widgets (e.g., stats, charts) into the topbar for quick access:

    TopbarPlugin::make()
        ->widgets([
            YourTopbarWidget::class,
        ])
    

• Responsive Adjustments:

  • Use Filament’s responsive helpers (e.g., @stack('topbar.right')) to manage mobile/desktop layouts.

• Event Listeners:

  • Hook into Filament events (e.g., TopbarRendered) to dynamically alter topbar content:

    event(new TopbarRendered($topbar));
    

Gotchas and Tips

Pitfalls

1. Filament Version Compatibility:

   • Ensure your Filament version (^5.3) matches the plugin’s requirements. Downgrade if needed:

     composer require filament/filament:^5.3
     

2. Caching Issues:

   • Clear Filament’s view cache after publishing custom views:

     php artisan filament:cache:clear
     

3. Blade Component Conflicts:

   • Avoid naming custom topbar components identically to Filament’s internal components (e.g., topbar).

4. Mobile Responsiveness:

   • Test mobile layouts thoroughly. The plugin inherits Filament’s responsive design but may need adjustments for complex topbars.

Debugging

• View Overrides Not Applying:

  • Verify the published view file is in the correct location (resources/views/vendor/filament-topbar/components/topbar.blade.php).
  • Check for typos in Blade directives (e.g., @stack vs @push).

• Plugin Not Loading:

  • Ensure TopbarPlugin::make() is added to the plugins() array in AdminPanelProvider.
  • Check for composer autoload issues:

    composer dump-autoload
    

• CSS/JS Conflicts:

  • Use browser dev tools to inspect conflicts. Isolate custom styles by scoping them to .filament-topbar.

Tips

1. Extending Functionality:

   • Create a custom topbar service provider to add logic before/after rendering:

     public function boot()
     {
         Topbar::macro('addCustomItem', function () {
             // Custom logic
         });
     }
     

2. Performance:

   • Lazy-load heavy topbar elements (e.g., dropdowns) to improve initial load times.

3. Testing:

   • Use Filament’s testing helpers to assert topbar content:

     $this->filament()->assertSeeInTopbar('Expected Text');
     

4. Dark Mode:

   • Leverage Filament’s dark mode support by adding dark: variants to your custom CSS classes.

5. Accessibility:

   • Ensure custom topbar elements meet WCAG standards (e.g., proper ARIA labels, keyboard navigation).

6. Backup Original Topbar:

   • Before customizing, save a copy of the default view for reference:

     cp vendor/jeffersongoncalves/filament-topbar/resources/views/components/topbar.blade.php resources/views/vendor/filament-topbar/components/topbar.original.blade.php