Getting Started

Minimal Steps to First Use

Install the package:

composer require osamaatef/filament-drilldown-sidebar

Publish the views (required for Filament 3.x/4.x/5.x compatibility):
```
php artisan vendor:publish --tag=drilldown-sidebar-views --force
```

Register the plugin in your PanelProvider (e.g., app/Providers/Filament/AdminPanelProvider.php):

use OsamaAtef\FilamentDrilldownSidebar\FilamentDrilldownSidebarPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentDrilldownSidebarPlugin::make())
        ->drilldownGroups(['Users', 'Products']); // Specify groups to enable drill-down
}

Test immediately: Navigate to your Filament admin panel. Groups like Users and Products will now appear as clickable drill-down buttons.

First Use Case: Converting a Resource Group to Drill-Down

If you have a UserResource registered under the Users group, users can now:

Click the Users group in the sidebar to expand it into a detail view.
Navigate directly to the Users list page without collapsing the sidebar.

Implementation Patterns

Workflow: Integrating with Existing Resources/Pages

Auto-Discovery: The plugin automatically detects resources/pages registered under the specified groups. No manual configuration is needed for individual items.
Mixed Sidebar Usage:
- Groups not in drilldownGroups() retain the default Filament accordion behavior.
- Groups in drilldownGroups() become drill-down buttons.
- Example:
```
->drilldownGroups(['Reports']) // Only 'Reports' becomes drill-down
```
Live Search Integration (Optional): Enable live search for drill-down groups by publishing the config:
```
php artisan vendor:publish --tag=drilldown-sidebar-config
```
Then configure in config/filament-drilldown-sidebar.php:
```
'enable_search' => true,
```
Nested Sub-Groups: Supports inline nested sub-groups (e.g., Users > Admins > Active). Configure via resource/page registration order.

Integration Tips

Customizing Drill-Down Behavior: Override the published view (resources/views/livewire/sidebar.blade.php for Filament 4/5) to modify the drill-down UI (e.g., icons, animations).

Dynamic Group Configuration: Use a service provider to dynamically set drilldownGroups based on user roles or other logic:

public function boot()
{
    FilamentDrilldownSidebarPlugin::make()
        ->configureUsing(function (FilamentDrilldownSidebar $plugin) {
            $plugin->drilldownGroups(['Dashboard', 'Settings']);
        });
}

Filament 5.x Specifics: For Filament 5.x, ensure your Panel extends Filament\Panel and the plugin is registered in the configurePanel method:
```
public function configurePanel(): Panel
{
    return Panel::make()
        ->plugin(FilamentDrilldownSidebarPlugin::make());
}
```

Gotchas and Tips

Pitfalls

View Publishing Required: Forgetting to run vendor:publish will break the sidebar entirely. Always include --force after Filament major updates.
Group Label Mismatches: The plugin matches group labels exactly (case-sensitive). If drilldownGroups(['users']) is set but your resource uses Users, it won’t work. Use:
```
->drilldownGroups(['Users']) // Exact match required
```
Livewire Caching: In Filament 4/5, clear Livewire cache if drill-down groups don’t update:
```
php artisan filament:cache-clear
```
Nested Group Conflicts: Overlapping group names (e.g., Users and Users/Admins) may cause unexpected behavior. Prefix groups explicitly:
```
->drilldownGroups(['Users', 'Users/Admins'])
```

Debugging

Check Published Views: Verify the correct view is published for your Filament version:
- Filament 3.x: resources/views/components/sidebar/index.blade.php
- Filament 4/5.x: resources/views/livewire/sidebar.blade.php
Log Group Detection: Enable debug mode in config/filament-drilldown-sidebar.php to log detected groups:
```
'debug' => true,
```
Clear Config Cache: After changing drilldownGroups, run:
```
php artisan config:clear
```

Extension Points

Custom Drill-Down Logic: Extend the plugin by binding to its events (e.g., DrilldownGroupSelected). Example:

FilamentDrilldownSidebar::listen(DrilldownGroupSelected::class, function (DrilldownGroupSelected $event) {
    // Custom logic when a group is clicked
});

Override Default Views: Copy the published view to your project and modify it (e.g., resources/views/livewire/sidebar.blade.php). The plugin will use your version instead.
Add Icons or Badges: Use Filament’s icon system to customize drill-down buttons. Example in the published view:
```
<x-filament::icon icon="heroicon-o-users" />
```

Conditional Drill-Down: Dynamically exclude groups based on user permissions:

->configureUsing(function (FilamentDrilldownSidebar $plugin) {
    $plugin->drilldownGroups(auth()->user()->can('manage_users') ? ['Users'] : []);
})

Filament Drilldown Sidebar Laravel Package