Filament Tour Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require viezel/filament-tour
   

   For Filament v3.x, use "^3.0" tag.

2. Register Plugin: Add the plugin to your Panel configuration in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->default()
           ->plugins([
               \Viezel\FilamentTour\FilamentTourPlugin::make(),
           ]);
   }
   

3. Define a Tour: Create a tour in a service provider or a dedicated class:

   use Viezel\FilamentTour\Tour;
   
   Tour::create('welcome_tour')
       ->title('Welcome to Your Panel')
       ->steps([
           Tour::step()
               ->target('#widgets')
               ->popover([
                   'title' => 'Widgets',
                   'description' => 'Manage your widgets here.',
               ]),
           // Add more steps as needed
       ]);
   

4. Trigger the Tour: The tour will autostart by default. To disable autostart, configure it in the plugin:

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

First Use Case

Use this package to guide new users through your Filament admin panel. For example, highlight key sections like:

• Dashboard widgets
• Navigation menus
• Common actions (e.g., creating a new record).

Implementation Patterns

Workflows

1. Tour Creation:

   • Define tours in a dedicated service provider or a Tour class.
   • Use Tour::create() to initialize a tour and chain methods like title(), steps(), and onlyVisibleOnce().
   • Example:

     Tour::create('admin_tour')
         ->onlyVisibleOnce(fn() => true) // Only show once
         ->steps([
             Tour::step()->target('#resources-table')->popover(['title' => 'Resources', 'description' => 'View and manage resources here.']),
         ]);
     

2. Dynamic Tours:

   • Use closures to dynamically generate steps based on user roles or permissions:

     Tour::create('admin_dashboard_tour')
         ->steps(fn() => [
             auth()->user()->can('access_dashboard') ? Tour::step()->target('#dashboard-stats') : null,
         ]);
     

3. Integration with Filament Resources/Pages:

   • Attach tours to specific resources or pages by checking the current URL or resource class:

     Tour::create('create_post_tour')
         ->onlyVisibleOnce()
         ->steps([
             Tour::step()->target('#title-field')->popover(['title' => 'Post Title', 'description' => 'Enter your post title here.']),
         ]);
     

4. Conditional Tour Activation:

   • Enable or disable tours based on environment or user attributes:

     FilamentTourPlugin::make()
         ->onlyVisibleOnce(fn() => app()->environment('production'))
         ->autoStart(fn() => auth()->check());
     

Integration Tips

• Localization: Localize tour popovers by passing translated strings:

  Tour::step()->popover([
      'title' => __('filament-tour.steps.title'),
      'description' => __('filament-tour.steps.description'),
  ]);
  

• Styling: Customize the DriverJS appearance by publishing the views and overriding the CSS:

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

  Then modify the published Blade files in resources/views/vendor/filament-tour/.

• Event Listeners: Listen to tour events (e.g., tour-started, tour-ended) to trigger additional logic:

  event(new TourStarted($tour));
  

• Testing: Test tours in a staging environment before deploying to production. Use the onlyVisibleOnce config to control visibility:

  FilamentTourPlugin::make()->onlyVisibleOnce(fn() => false); // Disable for testing
  

Gotchas and Tips

Pitfalls

1. CSS Selector Conflicts:

   • If enable_css_selector is set to false (default), DriverJS uses IDs for targeting elements. Ensure your target elements have unique IDs or adjust the config:

     'enable_css_selector' => true, // Enable if using CSS selectors
     

   • Debugging: Use browser dev tools to verify if the target element is correctly selected.

2. Local Storage Issues:

   • The only_visible_once feature relies on localStorage. If users clear their browser data, they may see the tour again. Handle this gracefully with a fallback:

     FilamentTourPlugin::make()->onlyVisibleOnce(fn() => !session()->has('tour_completed'));
     

3. Tour Autostart Timing:

   • Tours autostart on page load. If the target elements are dynamically loaded (e.g., via AJAX), the tour may fail to find them. Delay the tour start or use event listeners to trigger it after elements are loaded:

     document.addEventListener('DOMContentLoaded', function() {
         setTimeout(() => {
             window.FilamentTour.startTour('welcome_tour');
         }, 1000); // Delay for 1 second
     });
     

4. Plugin Registration Order:

   • Ensure FilamentTourPlugin is registered after other plugins that might modify the DOM, as tours rely on the final state of the page.

5. Performance:

   • Complex tours with many steps or heavy popovers may impact page load performance. Optimize by:
     • Limiting the number of steps.
     • Using minimal popover content.
     • Lazy-loading tour assets.

Debugging

• Check Tour Steps:

  • Inspect the generated HTML to ensure target elements exist and are accessible. Use the browser console to test DriverJS directly:

    window.FilamentTour.startTour('tour_name');
    

• Console Logs:

  • Enable DriverJS debug mode by publishing the config and setting:

    'debug' => true,
    

  • Check the browser console for errors or warnings.

• Clear Local Storage:

  • To test the only_visible_once feature, clear your browser’s local storage or use incognito mode.

Extension Points

1. Custom Tour Steps:

   • Extend the Tour class to add custom step types or behaviors:

     class CustomTour extends Tour
     {
         public function customStep(array $options)
         {
             return $this->steps[] = [
                 'type' => 'custom',
                 'options' => $options,
             ];
         }
     }
     

2. Override Default Views:

   • Publish and modify the Blade views to customize the appearance of popovers or buttons:

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

   • Override resources/views/vendor/filament-tour/partials/popover.blade.php.

3. Add Tour Buttons:

   • Manually trigger tours via JavaScript or Filament buttons:

     document.getElementById('start-tour-button').addEventListener('click', function() {
         window.FilamentTour.startTour('tour_name');
     });
     

4. Integrate with Filament Notifications:

   • Show notifications when a tour is completed or skipped:

     event(new TourEnded($tour));
     // Listen for the event and trigger a Filament notification.
     

5. Multi-Language Support:

   • Use Laravel’s localization features to support multiple languages in tour popovers:

     Tour::step()->popover([
         'title' => __('filament-tour.steps.welcome.title'),
         'description' => __('filament-tour.steps.welcome.description'),
     ]);