Filament Pinnable Navigation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devletes/filament-pinnable-navigation
   

2. Register Plugin: Add to your Panel registration in app/Providers/Filament/AdminPanelProvider.php:

   ->plugin(PinnableNavigationPlugin::make())
   

3. First Use Case: Pin a navigation item by clicking the pin icon (📌) in the sidebar. Pinned items appear in a collapsible "Pinned" group at the top of the navigation.

Where to Look First

• Config File: Published via php artisan vendor:publish --tag="pinnable-navigation-config".
• Blade Views: Located in resources/views/vendor/filament-pinnable-navigation/.
• JavaScript: Check resources/js/filament-pinnable-navigation.js for customization hooks.

Implementation Patterns

Core Workflow

1. Pinning Items:

   • Users pin items by clicking the pin icon (📌) next to navigation items.
   • Pinned items are stored in the user’s session (default) or database (configurable).
   • Example: Pin the "Dashboard" or "Reports" navigation items for quick access.

2. Grouping Pinned Items:

   • Pinned items appear in a collapsible "Pinned" group at the top of the sidebar.
   • Customize the group label via config:

     'pinned_group_label' => 'Favorites',
     

3. Dynamic Updates:

   • Pinned items persist across sessions (if using database storage).
   • Use PinnableNavigationService to programmatically manage pins:

     use Devletes\FilamentPinnableNavigation\Facades\PinnableNavigation;
     
     // Pin an item for the current user
     PinnableNavigation::pin('dashboard');
     
     // Unpin an item
     PinnableNavigation::unpin('dashboard');
     

Integration Tips

• Custom Navigation Items: Extend the PinnableNavigationItem class to add custom logic:

  use Devletes\FilamentPinnableNavigation\Contracts\PinnableNavigationItem;
  
  class CustomNavigationItem implements PinnableNavigationItem {
      public function isPinnable(): bool {
          return true; // or false for non-pinnable items
      }
  }
  

• Conditional Pinning: Use middleware or policies to restrict pinning for specific users/roles:

  ->middleware([PinnableNavigationMiddleware::class])
  

• Database Storage: Enable database storage in config to persist pins across devices:

  'storage' => 'database',
  

  Run migrations:

  php artisan migrate
  

Gotchas and Tips

Pitfalls

1. Session vs. Database Storage:

   • Session storage resets on logout or session expiry. Use database storage for persistence:

     'storage' => 'database',
     

   • Ensure the pinnable_navigation_items table exists after enabling database storage.

2. Navigation Item Keys:

   • Pins are stored by the navigation item’s key (e.g., 'dashboard'). Ensure keys are unique and stable.
   • Avoid dynamic keys (e.g., based on user input) to prevent pinning issues.

3. Plugin Registration:

   • Register the plugin after defining navigation items in your panel. Example:

     ->navigationItems([
         NavigationItem::make('Dashboard', 'heroicon-o-home')
             ->url('/dashboard')
             ->icon('heroicon-o-home'),
     ])
     ->plugin(PinnableNavigationPlugin::make()),
     

4. Caching:

   • If using Filament’s cache, clear it after pinning/unpinning to avoid stale data:

     php artisan filament:cache-clear
     

Debugging

• Check Storage: Inspect the pinnable_navigation_items table (if using database storage) or session data:

  dd(session()->get('filament-pinnable-navigation'));
  

• Logs: Enable debug mode in config to log pinning actions:

  'debug' => true,
  

• Blade Overrides: Override views in resources/views/vendor/filament-pinnable-navigation/ to debug rendering issues.

Extension Points

1. Custom Pin Button: Override the pin icon or tooltip via config:

   'pin_icon' => 'heroicon-o-star',
   'pin_tooltip' => 'Add to Favorites',
   'unpin_tooltip' => 'Remove from Favorites',
   

2. Event Listeners: Listen for pinning events to trigger custom logic (e.g., notifications):

   use Devletes\FilamentPinnableNavigation\Events\ItemPinned;
   
   ItemPinned::listen(function (ItemPinned $event) {
       Log::info("Item pinned: {$event->itemKey}");
   });
   

3. API Access: Expose pinned items via API for frontend frameworks:

   Route::get('/api/pinned-items', function () {
       return PinnableNavigation::getPinnedItems();
   });
   

4. Multi-Tenant Support: Use the tenant config option to scope pins to tenants:

   'tenant' => true,
   

   Ensure your User model includes a tenant_id column.