# Dynamic Breadcrumbs Usage Guide

This application includes a dynamic breadcrumb system that automatically tracks navigation flow and displays the complete path from the originating page to the current page.

## How It Works

1. **Navigation Tracking**: The `TrackNavigation` middleware automatically tracks every page visit in the admin panel and stores navigation history in the session.

2. **Breadcrumb Generation**: The `BreadcrumbService` builds breadcrumb trails from the navigation history, showing the path users took to reach the current page.

3. **Automatic Display**: Breadcrumbs are automatically available in all Filament views through a view composer.

## Adding Breadcrumbs to a Page

### Method 1: Using the Blade Component (Recommended)

Simply include the breadcrumbs component in your Blade template:

```blade
<x-filament-panels::page>
    {{-- Breadcrumbs Navigation --}}
    <x-breadcrumbs />
    
    {{-- Your page content --}}
    <div class="your-content">
        ...
    </div>
</x-filament-panels::page>
```

The breadcrumbs will automatically use the navigation history to build the trail.

### Method 2: Using the HasBreadcrumbs Trait

If you want more control, use the `HasBreadcrumbs` trait in your page class:

```php
<?php

namespace App\Filament\Resources\YourResource\Pages;

use App\Filament\Concerns\HasBreadcrumbs;
use Filament\Resources\Pages\Page;

class YourPage extends Page
{
    use HasBreadcrumbs;
    
    // Optionally override the breadcrumb title
    protected function getBreadcrumbTitle(): ?string
    {
        return 'Custom Page Title';
    }
}
```

Then in your Blade template:

```blade
<x-filament-panels::page>
    {{-- Breadcrumbs Navigation --}}
    {!! $this->renderBreadcrumbs() !!}
    
    {{-- Your page content --}}
</x-filament-panels::page>
```

### Method 3: Custom Breadcrumbs

You can also pass custom breadcrumbs to the component:

```blade
@php
    use App\Services\BreadcrumbService;
    $breadcrumbService = app(BreadcrumbService::class);
    $customBreadcrumbs = $breadcrumbService->getFullPathBreadcrumbs('Custom Title');
@endphp

<x-breadcrumbs :breadcrumbs="$customBreadcrumbs" />
```

## Breadcrumb Service Methods

The `BreadcrumbService` provides several methods:

### `getFullPathBreadcrumbs(?string $currentTitle = null): array`

Returns the complete navigation path breadcrumbs, including all visited pages.

```php
$breadcrumbs = app(BreadcrumbService::class)->getFullPathBreadcrumbs('Current Page');
```

### `getSimpleBreadcrumbs(?string $currentTitle = null): array`

Returns simplified breadcrumbs showing only the previous page and current page.

```blade
<x-breadcrumbs :breadcrumbs="$breadcrumbService->getSimpleBreadcrumbs()" simple="true" />
```

### `clearHistory(): void`

Clears the navigation history (useful for resetting breadcrumbs).

```php
app(BreadcrumbService::class)->clearHistory();
```

## Customization

### Styling

Breadcrumb styles are included in the component. To customize, modify:
- `resources/views/components/breadcrumbs.blade.php`

### Page Titles

Page titles are automatically extracted from:
1. Route names (if mapped in middleware)
2. Filament resource/page names
3. URL paths

To customize titles for specific routes, edit:
- `app/Http/Middleware/TrackNavigation.php` - `getPageTitle()` method

## Examples

### Example 1: Simple Page with Breadcrumbs

```blade
<x-filament-panels::page>
    <x-breadcrumbs />
    
    <div class="page-content">
        <h1>My Page</h1>
        <!-- Content here -->
    </div>
</x-filament-panels::page>
```

### Example 2: Page with Custom Title

```php
// In your Page class
use App\Filament\Concerns\HasBreadcrumbs;

class MyPage extends Page
{
    use HasBreadcrumbs;
    
    protected function getBreadcrumbTitle(): ?string
    {
        return 'My Custom Page Title';
    }
}
```

### Example 3: Conditional Breadcrumbs

```blade
@if(request()->path() !== 'admin')
    <x-breadcrumbs />
@endif
```

## How Navigation Tracking Works

1. When a user visits a page, the `TrackNavigation` middleware:
   - Captures the current URL, path, and page title
   - Stores the previous page in navigation history
   - Updates session with current page information

2. Navigation history is stored in session with:
   - URL
   - Path
   - Title
   - Timestamp

3. History is limited to the last 10 pages to prevent session bloat

4. Breadcrumbs are built by:
   - Starting with Dashboard
   - Adding pages from navigation history
   - Ending with the current page (marked as active)

## Notes

- Breadcrumbs automatically exclude duplicate pages
- The system tracks the complete navigation flow, not just parent-child relationships
- Breadcrumbs are limited to 5 items maximum (Dashboard + 4 history items)
- Only admin routes (`/admin*`) are tracked
- Page refreshes don't add duplicate entries to history