# Vertical Sub-Menu (Cluster Sub-Navigation) Help

## What This Documents

Filament v4 clusters automatically generate sub-navigation for every page and resource registered within them. This appears in two places:

1. **Top tabs** — a horizontal tab bar across the top of the content area listing all cluster items (e.g. Operations, Products, Warehouses…)
2. **Left sidebar panel** — a vertical sub-menu grouped by navigation group (e.g. "General" > Manage Activities, Manage Currency, Manage Users)

Both are redundant when the main sidebar already provides full navigation to every item.

---

## How It Works (Why It Appears)

In Filament v4, every page that belongs to a cluster automatically inherits sub-navigation via the `HasSubNavigation` trait (in `vendor/filament/filament/src/Pages/Concerns/HasSubNavigation.php`):

```php
public function getSubNavigation(): array
{
    if (filled($cluster = static::getCluster())) {
        return $this->generateNavigationItems($cluster::getClusteredComponents());
    }
    return [];
}
```

This calls `getClusteredComponents()` on the cluster, which returns every page and resource Filament has registered in that cluster. The result is rendered as tabs (position `Top`) or a sidebar panel (position `Start`).

Key point: overriding `getSubNavigation()` on the **cluster class itself** does NOT suppress this — the trait on each individual **page** calls `getClusteredComponents()` directly and ignores the cluster's own `getSubNavigation()`.

---

## The Fix

### Step 1 — Suppress cluster-level sub-navigation index redirect

In the cluster class, override `getSubNavigation()` as an **instance method** (not static):

```php
// plugins/webkul/support/src/Filament/Clusters/Settings.php

public function getSubNavigation(): array
{
    return [];
}
```

This prevents the cluster's own index page from trying to redirect to its first sub-nav item.

> **Gotcha:** If you accidentally declare this as `public static function`, PHP throws a fatal 500 error: *"Cannot make non-static method static"* because the base `Cluster` class declares it as an instance method.

---

### Step 2 — Suppress sub-navigation on individual pages

For every Settings page (SettingsPage subclass inside the cluster), add the same override:

```php
public function getSubNavigation(): array
{
    return [];
}
```

There are ~19 Settings pages across multiple plugins. Rather than editing each manually, a PHP script was used to insert the method before the final closing brace of each file:

```php
$method = "\n    public function getSubNavigation(): array\n    {\n        return [];\n    }\n";

foreach ($files as $file) {
    $content = file_get_contents($file);
    if (str_contains($content, 'getSubNavigation')) {
        continue; // already patched
    }
    $pos = strrpos($content, '}');
    $content = substr($content, 0, $pos) . $method . substr($content, $pos);
    file_put_contents($file, $content);
}
```

Files patched (all under `plugins/webkul/*/src/Filament/*/Clusters/Settings/Pages/`):

- channel-orders: `ManageOrders`
- inventories: `ManageLogistics`, `ManageOperations`, `ManageProducts`, `ManageTraceability`, `ManageWarehouses`
- invoices: `Products`
- projects: `ManageTasks`, `ManageTime`
- purchases: `ManageOrders`, `ManageProducts`
- sales: `ManageInvoice`, `ManagePricing`, `ManageProducts`, `ManageQuotationAndOrder`
- security: `ManageActivity`, `ManageCurrency`, `ManageUsers`
- website: `ManageContacts`

---

## CSS Classes (for reference)

If you ever need to target these elements via CSS instead:

| Element | CSS class |
|---|---|
| Left sidebar panel container | `fi-page-sub-navigation-sidebar-ctn` |
| Left sidebar panel list | `fi-page-sub-navigation-sidebar` |
| Top tab bar | `fi-page-sub-navigation-tabs` |

---

## Suppressing Navigation Within a Cluster (Resources)

For **resources** (not pages) that were moved into the Settings cluster but should not appear in the cluster's sub-nav, set:

```php
protected static bool $shouldRegisterNavigation = false;
```

This is used on the four inventory management resources that were moved from the Configurations cluster to Settings:

- `WarehouseResource`
- `LocationResource`
- `OperationTypeResource`
- `StorageCategoryResource`

These resources are still navigable via `NavigationItem` entries registered manually in `InventoryPlugin.php`.

---

## Related Files

| File | Purpose |
|---|---|
| `plugins/webkul/support/src/Filament/Clusters/Settings.php` | Settings cluster — has `getSubNavigation()` instance override |
| `plugins/webkul/inventories/src/InventoryPlugin.php` | Manual `NavigationItem` registrations replacing auto-nav |
| `vendor/filament/filament/src/Pages/Concerns/HasSubNavigation.php` | Filament trait that generates sub-nav per page |
| `vendor/filament/filament/src/Clusters/Cluster.php` | Cluster base class |