Filament Tour Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require yacoubalhaidari/filament-tour
   

   No additional configuration is required for basic usage—just register the plugin in your PanelProvider.

2. First Use Case: Trigger the tour via the Tour button in the Filament user menu (top-right dropdown). This opens a default welcome screen with a "Start Tour" button.

3. Where to Look First:

   • Video Demo (visual workflow)
   • config/filament-tour.php (default settings)
   • app/Providers/Filament/AdminPanelProvider.php (registration)

Implementation Patterns

Core Workflows

1. Registering the Plugin:

   // app/Providers/Filament/AdminPanelProvider.php
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(FilamentTourPlugin::make())
           ->id('admin');
   }
   

2. Customizing Tour Steps: Define steps in a TourSteps class (e.g., app/Models/TourSteps.php):

   use FilamentTour\TourSteps;
   
   class CustomTourSteps extends TourSteps
   {
       public static function getSteps(): array
       {
           return [
               [
                   'title' => 'Welcome to the Dashboard',
                   'text' => 'This is your starting point.',
                   'attachTo' => '.filament-main-content',
                   'buttons' => [
                       ['text' => 'Next', 'type' => 'next'],
                   ],
               ],
               // Add more steps...
           ];
       }
   }
   

   Register the custom steps in PanelProvider:

   ->plugin(FilamentTourPlugin::make()
       ->tourSteps(CustomTourSteps::class)
   )
   

3. Dynamic Step Logic: Use closures for dynamic content (e.g., fetch user-specific data):

   'text' => fn () => "Hello, {$this->auth->user()->name}! This is your tour.",
   

4. Conditional Tours: Restrict tours to specific users/roles:

   ->canAccessTour(fn () => auth()->user()->isAdmin())
   

Integration Tips

• Localization: Override tour texts via language files (resources/lang/).
• Theming: Extend the published CSS (filament-tour-styles.css) for custom styling.
• Event Hooks: Listen to tour.started or tour.finished events for analytics/logging.

Gotchas and Tips

Pitfalls

1. Asset Loading:

   • If publishing assets manually, clear Laravel’s cache:

     php artisan optimize:clear
     

   • Ensure public/js and public/css directories are writable.

2. Step Targeting:

   • Use valid CSS selectors (e.g., .filament-main-content) for attachTo. Avoid overly generic selectors like body.
   • Debug with browser dev tools if steps don’t appear.

3. Caching:

   • Tours may cache in the browser. Force a refresh (Ctrl+F5) or clear cache during development.

Debugging

• Console Logs: Shepherd.js logs errors to the browser console. Check for:

  console.error // Shepherd.js errors
  

• Step Validation: Test each step individually by commenting out others in getSteps().

Extension Points

1. Custom Buttons: Add custom buttons to steps:

   'buttons' => [
       ['text' => 'Skip', 'type' => 'cancel'],
       ['text' => 'Save & Continue', 'type' => 'next', 'action' => 'saveData'],
   ],
   

   Handle actions via JavaScript (extend filament-tour-scripts.js).

2. Welcome/Finish Screens: Customize the default screens by overriding views:

   ->welcomeView('filament-tour::welcome')
   ->finishView('filament-tour::finish')
   

   Publish views first:

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

3. Tour Completion Tracking: Use Laravel’s session or a database to track completed tours:

   session()->put('tour_completed', true);
   

   Check in middleware or controllers:

   if (!session()->has('tour_completed')) {
       return redirect()->route('filament.admin.tour');
   }
   

Pro Tips

• A/B Testing: Use different TourSteps classes for varied user groups.
• Performance: Lazy-load tour assets if not always needed:

  ->loadAssetsOnlyWhenActive()
  

• Accessibility: Ensure tour steps comply with WCAG (e.g., keyboard navigation). Shepherd.js supports this out-of-the-box.