Filament Collapsible Subnav Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require emuniq/filament-collapsible-subnav
   

   • No additional configuration required; the plugin auto-registers to all Filament panels.

2. First Use Case:

   • Navigate to a resource page with sub-navigation (e.g., resources/posts). Observe the new collapsible toggle button (⋯) in the sub-navigation sidebar.
   • Click the toggle to collapse/expand the sidebar. The state persists across page reloads via cookies.

3. Optional Optimization: For reduced HTTP requests, integrate the CSS into your Filament theme:

   php artisan collapsible-subnav:install
   npm run build
   

Where to Look First

• Default Behavior: The plugin works out-of-the-box on any Filament panel with sub-navigation. No manual registration is needed unless customizing behavior.
• Debugging: Check the browser’s DevTools (Elements > head) for the injected critical CSS. Look for the data-cfasync="false" attribute if using Cloudflare Rocket Loader.
• State Persistence: Verify cookies (subnav_collapsed) are set correctly for persistent state.

Implementation Patterns

Usage Patterns

1. Auto-Registration:

   • The plugin registers globally to all panels. No need to modify Panel classes unless overriding defaults.
   • Example of manual registration (if needed):

     use Emuniq\FilamentCollapsibleSubnav\CollapsibleSubnavPlugin;
     
     public function panel(Panel $panel): Panel {
         return $panel->plugin(CollapsibleSubnavPlugin::make());
     }
     

2. Sub-Navigation Targeting:

   • Only affects sub-navigation sidebars (e.g., tabs within a resource page). The main panel navigation (top/sidebar) remains unchanged.
   • Works with both sidebar layouts (no top navigation) and top navigation layouts.

3. SPA Mode Integration:

   • Automatically re-syncs collapsed state on Livewire navigation via livewire:navigated. No additional code required for SPA-compatible panels (->spa()).

4. Responsive Design:

   • Sub-navigation collapses automatically on mobile (<768px). The toggle button remains visible for manual control.

Workflows

1. Adding to a New Panel:

   • Install the package. The plugin works immediately on any Filament panel with sub-navigation.

2. Customizing Appearance:

   • Override the default CSS by extending your Filament theme. Target classes like:
     • .fi-sidebar-item-btn (toggle button)
     • .fi-sidebar-item-badge-ctn (badges in collapsed state)
     • .collapsible-subnav-tooltip (CSS-only tooltips)

3. Disabling for Specific Panels:

   • Use the ->ignoreSubNavigation() method on the panel:

     ->plugin(CollapsibleSubnavPlugin::make()->ignoreSubNavigation())
     

4. Testing State Persistence:

   • Verify cookies (subnav_collapsed) are set when toggling. Test across page reloads and Livewire SPA navigation.

Integration Tips

• Filament v5 Migration:

  • No breaking changes. Update composer.json to support v5:

    "require": {
        "emuniq/filament-collapsible-subnav": "^1.0"
    }
    

  • Test tooltips and dark mode in v5’s new sidebar structure.

• Dark Mode Compatibility:

  • The plugin respects Filament’s dark class for tooltips. Ensure your theme’s dark mode CSS targets .collapsible-subnav-tooltip::after.

• Performance Optimization:

  • Use the collapsible-subnav:install Artisan command to bundle CSS with your theme, reducing HTTP requests.

• Accessibility:

  • The plugin adds aria-label to collapsed items. Extend with custom labels if needed:

    CollapsibleSubnavPlugin::make()->ariaLabel('Collapse sub-navigation')
    

Gotchas and Tips

Pitfalls

1. Cloudflare Rocket Loader:

   • Issue: May strip the critical inline script, causing a flash of unstyled content (FOUC).
   • Fix: The plugin marks its script with data-cfasync="false". If still an issue, exclude the script from Rocket Loader or use the theme-integrated CSS.

2. SPA Mode Desync (Pre-v1.6.0):

   • Issue: Collapsed state might not persist across Livewire navigation in older versions.
   • Fix: Update to v1.6.0+, which listens to livewire:navigated for re-sync.

3. Tooltips in Filament v4:

   • Issue: Tooltips may not appear due to renamed classes (.fi-sidebar-item-btn instead of .fi-sidebar-item-button).
   • Fix: v1.6.0+ uses CSS-only tooltips (::after pseudo-elements) that work across v3/v4/v5.

4. Mobile Responsiveness:

   • Issue: Sub-navigation may not collapse on mobile if custom CSS overrides the default breakpoint (<768px).
   • Fix: Ensure no conflicting media queries target .fi-sidebar or .collapsible-subnav-toggle.

5. Cookie Conflicts:

   • Issue: Other packages might set a subnav_collapsed cookie, causing conflicts.
   • Fix: Use the plugin’s cookieName() method to customize:

     CollapsibleSubnavPlugin::make()->cookieName('my_custom_subnav_state')
     

Debugging

1. Toggle Not Appearing:

   • Check: Ensure the page has sub-navigation (e.g., ->subNavigationPosition(SubNavigationPosition::Start)).
   • Debug: Inspect the DOM for the .collapsible-subnav-toggle button. If missing, verify the plugin is registered.

2. State Not Persisting:

   • Check: Open DevTools (Application > Cookies) and look for subnav_collapsed.
   • Debug: Ensure no JavaScript errors block cookie setting. Test with ->ignoreSubNavigation() to isolate the issue.

3. CSS Overrides:

   • Check: Use DevTools to inspect .fi-sidebar-item-btn or .collapsible-subnav-tooltip. Conflicting styles may hide the toggle or tooltips.
   • Fix: Increase specificity in your theme’s CSS or use !important sparingly.

4. SPA Mode Issues:

   • Check: Listen for livewire:navigated events in the browser console. Ensure the plugin’s script re-runs.
   • Debug: Temporarily add console.log to the plugin’s JS to verify execution.

Tips

1. Custom Toggle Icon:

   • Replace the default chevron icon by overriding the CSS:

     .collapsible-subnav-toggle::after {
         content: "▶";
         font-size: 1.2rem;
     }
     

2. Conditional Registration:

   • Register the plugin only for specific panels:

     if ($this->isAdminPanel()) {
         $panel->plugin(CollapsibleSubnavPlugin::make());
     }
     

3. Theme Integration:

   • For better performance, integrate the CSS into your theme:

     php artisan collapsible-subnav:install
     

   • This bundles the CSS with your assets, reducing HTTP requests.

4. Dark Mode Styling:

   • Customize dark mode tooltips by targeting:

     .dark .collapsible-subnav-tooltip::after {
         background: #333;
         color: white;
     }
     

5. Testing:

   • Use Filament’s --test flag to verify behavior in a clean environment:

     php artisan filament:test --panel=admin
     

   • Check for visual regressions in sub-navigation toggles and tooltips.

6. Extension Points:

   • Custom Cookie Domain: Set a custom domain for cookies (e.g., for multi-tenant apps):

     CollapsibleSubnavPlugin::make()->cookieDomain('.yourdomain.com')
     

   • Disable for Specific Routes: Use middleware to exclude routes from sub-navigation:

     $panel->middleware([DisableSubnavMiddleware::class]);