Filament Tour Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require jibaymcs/filament-tour:"^5.0"
   

   Publish config (optional):

   php artisan vendor:publish --tag="filament-tour-config"
   

2. Register Plugin: Add to your panel() method in AppServiceProvider or PanelProvider:

   ->plugins([FilamentTourPlugin::make()])
   

3. First Tour:

   • Use the HasTour trait in your dashboard/page class:

     use JibayMcs\FilamentTour\Tour\HasTour;
     
     class Dashboard extends FilamentDashboard {
         use HasTour;
     
         public function tours(): array {
             return [
                 Tour::make('dashboard')
                     ->steps(
                         Step::make()
                             ->title("Welcome!")
                             ->description("This is your first tour step.")
                     )
             ];
         }
     }
     

First Use Case

Create a simple dashboard tour to guide new users through key features:

public function tours(): array {
    return [
        Tour::make('dashboard')
            ->steps(
                Step::make('.fi-header-heading')
                    ->title("Dashboard Overview")
                    ->description("This is your main dashboard area.")
                    ->icon('heroicon-o-home')
                    ->iconColor('primary'),

                Step::make('.fi-avatar')
                    ->title("User Profile")
                    ->description("Click here to manage your account.")
            )
    ];
}

Implementation Patterns

Core Workflows

1. Tour Creation Patterns

• Element-Based Tours:

  Step::make('.filament-table')
      ->title("Data Tables")
      ->description("Interact with your data here.")
  

• Modal Steps (no element selector):

  Step::make()
      ->title("Important Notice")
      ->description(view('tours.notice'))
      ->uncloseable(true)
  

• Dynamic Tours (using closures):

  Step::make('.filament-widget')
      ->title(fn() => "Widget: " . auth()->user()->name)
      ->description(fn() => "Your personalized widget area.")
  

2. Conditional Tours

Use Livewire events to trigger tours based on logic:

#[On('filament-tour::loaded-elements')]
public function checkTourConditions(bool $onlyVisibleOnce, array $tours): void {
    if (auth()->user()->hasRole('admin') && empty(auth()->user()->completedTours)) {
        $this->dispatch('filament-tour::open-tour', 'admin-onboarding');
    }
}

3. JSON Tours

For complex tours, define in JSON and load dynamically:

Tour::make(json: Storage::disk('local')->get('complex-tour.json'))
    ->route('/admin/reports')

4. Highlight Integration

Combine tours with persistent highlights:

public function highlights(): array {
    return [
        Highlight::make('.fi-actions')
            ->element('.fi-actions')
            ->title("Actions Menu")
            ->description("Quick actions for this resource.")
            ->icon('heroicon-o-chevron-down')
            ->position('bottom-right')
    ];
}

Integration Tips

1. Event-Driven Triggers:

   • Use filament-tour::open-tour/open-highlight events for button-triggered tours:

     <button wire:click="$dispatch('filament-tour::open-tour', 'wizard-tour')">
         Start Wizard Tour
     </button>
     

2. Tour States Management:

   • Override onlyVisibleOnce for reusable tours:

     FilamentTourPlugin::make()->onlyVisibleOnce(false)
     

3. Dark/Light Mode:

   • Set consistent colors for both themes:

     Tour::make('dashboard')
         ->colors('gray-100', 'gray-800')
     

4. Development Workflow:

   • Enable CSS selector tool during development:

     FilamentTourPlugin::make()->enableCssSelector()
     

   • Use Ctrl+Space to open the selector tool and copy elements.

Gotchas and Tips

Common Pitfalls

1. Element Selector Issues:

   • Problem: Tour steps fail to highlight elements.
   • Solution:
     • Verify selectors are unique (e.g., .filament-table vs .filament-table tr).
     • Use the built-in CSS selector tool (Ctrl+Space) to debug.
     • For dynamic content, use parent-child selectors:

       Step::make('#resource-table tbody tr')
       

2. Route Mismatches:

   • Problem: Tours don’t appear on expected routes.
   • Solution:
     • Explicitly set the route:

       Tour::make()->route('/admin/resources')
       

     • Use ignoreRoutes(true) for global tours (use sparingly).

3. Event Conflicts:

   • Problem: clickOnNext or dispatchOnNext events don’t fire.
   • Solution:
     • Ensure disableEvents(false) is set.
     • For Livewire events, verify the event name matches exactly (case-sensitive).

4. Caching:

   • Problem: Tours persist even after onlyVisibleOnce(false).
   • Solution:
     • Clear localStorage manually or reset via:

       localStorage.removeItem('filament-tour-seen');
       

Debugging Tips

1. Inspect Tour Data:

   • Add this to your Livewire component to log tour data:

     #[On('filament-tour::loaded-elements')]
     public function debugTours(bool $onlyVisibleOnce, array $tours) {
         \Log::info('Available Tours:', $tours);
     }
     

2. DriverJS Console:

   • Check browser console for DriverJS errors (e.g., missing elements).

3. View Source:

   • Inspect the rendered HTML to verify tour elements exist:

     <div class="driverjs-tour" style="display: none;">
     

Extension Points

1. Custom Step Types:

   • Extend Step to add custom behaviors:

     class CustomStep extends Step {
         public function customAction(string $action) {
             // Logic for custom actions
         }
     }
     

2. Theme Overrides:

   • Publish and modify the filament-tour views to customize styling:

     php artisan vendor:publish --tag="filament-tour-views"
     

3. Storage Backend:

   • Override the onlyVisibleOnce logic to use a database:

     FilamentTourPlugin::make()->onlyVisibleOnce(
         fn() => !TourSeen::where('user_id', auth()->id())->exists()
     );
     

4. Advanced Events:

   • Listen for DriverJS events directly:

     document.addEventListener('driverjs:step:show', (e) => {
         console.log('Step shown:', e.detail);
     });
     

Configuration Quirks

1. only_visible_once:

   • Defaults to true; set to false for reusable tours:

     FilamentTourPlugin::make()->onlyVisibleOnce(false);
     

2. Tour ID Prefixing:

   • The package auto-prepends a prefix to tour IDs (e.g., tour_dashboard). Account for this when dispatching events:

     $this->dispatch('filament-tour::open-tour', 'tour_dashboard');
     

3. JSON Validation:

   • Ensure JSON tours include all required fields (id, steps). Missing fields may cause silent failures.

4. Livewire Compatibility:

   • For Livewire components, ensure the HasTour trait is used on the root component (not nested components).