Swipe Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/swipe
   npm install @contao-components/swipe
   

   • Ensure node_modules and public/js are properly linked in Laravel’s asset pipeline (e.g., via Laravel Mix or Vite).

2. Basic Initialization Add the CSS and JS to your layout (e.g., resources/js/app.js or resources/css/app.css):

   import Swipe from '@contao-components/swipe';
   import '@contao-components/swipe/dist/swipe.css';
   

   <link rel="stylesheet" href="{{ mix('css/app.css') }}">
   <script src="{{ mix('js/app.js') }}" defer></script>
   

3. First Use Case: Simple Slider

   <div class="swipe-container">
     <div class="swipe-slide">Slide 1</div>
     <div class="swipe-slide">Slide 2</div>
     <div class="swipe-slide">Slide 3</div>
   </div>
   
   <script>
     document.addEventListener('DOMContentLoaded', () => {
       new Swipe('.swipe-container');
     });
   </script>
   

   • Key Classes:
     • .swipe-container: Wrapper for the slider.
     • .swipe-slide: Individual slides.

Implementation Patterns

1. Configuration Options

Pass options via the constructor or init() method:

new Swipe('.swipe-container', {
  startSlide: 1,       // Zero-based index (default: 0)
  speed: 400,          // Transition speed (ms)
  auto: 3000,          // Auto-advance interval (ms, set to `false` to disable)
  continuous: true,    // Infinite loop
  disableScroll: true, // Disable touch/scroll on body
  callback: (index) => {
    console.log('Slide changed to:', index);
  }
});

2. Programmatic Control

Access the slider instance via data-swipe attribute:

<div class="swipe-container" data-swipe></div>

const swipe = document.querySelector('[data-swipe]').swipe;
swipe.next();    // Advance to next slide
swipe.prev();    // Go back
swipe.goto(2);   // Jump to slide 2
swipe.stop();    // Pause auto-advance

3. Dot Navigation

Add a dot menu dynamically:

new Swipe('.swipe-container', {
  dotMenu: true,
  dotClass: 'custom-dot',  // Custom CSS class
  dotActiveClass: 'active' // Active state class
});

<div class="dot-menu"></div>

• The package auto-generates dots in the first .dot-menu element found.

4. Integration with Laravel Blade

Use @stack or @push for dynamic initialization:

<div class="swipe-container" id="hero-slider">
  @foreach($slides as $slide)
    <div class="swipe-slide">{{ $slide->content }}</div>
  @endforeach
</div>

@push('scripts')
<script>
  document.addEventListener('DOMContentLoaded', () => {
    new Swipe('#hero-slider', {
      auto: {{ $autoAdvance ? $autoAdvance : 'false' }},
      callback: (index) => {
        @this->emit('slide-changed', index);
      }
    });
  });
</script>
@endpush

5. Event Listeners

Bind to swipe events:

const swipe = new Swipe('.swipe-container');
swipe.on('slideChange', (index) => {
  console.log('Slide changed to:', index);
});
swipe.on('beforeSlideChange', (oldIndex, newIndex) => {
  console.log(`Transitioning from ${oldIndex} to ${newIndex}`);
});

Gotchas and Tips

Pitfalls

1. CSS Conflicts

   • Ensure .swipe-slide has width: 100% and float: left (or display: flex).
   • Override default transitions if using CSS animations:

     .swipe-container .swipe-slide {
       transition: none !important;
     }
     

2. Auto-Advance Timing

   • auto: 3000 may feel jarring; test with auto: 5000 or disable entirely for static sliders.

3. Mobile Touch Delays

   • Add touch-action: pan-y to .swipe-container to prevent OS-level touch delays:

     .swipe-container {
       touch-action: pan-y;
     }
     

4. Laravel Mix/Vite Caching

   • Clear cached assets after updates:

     npm run dev -- --clear
     

Debugging

• Check Initialization:

  console.log(document.querySelector('.swipe-container').swipe);
  

  • Should return the Swipe instance. If undefined, the element wasn’t found or the script ran too early.

• Event Debugging:

  swipe.on('error', (err) => {
    console.error('Swipe error:', err);
  });
  

Extension Points

1. Custom Transitions Override the default slide animation by extending the Swipe class:

   class FadeSwipe extends Swipe {
     slide(index) {
       this.slides.forEach((slide, i) => {
         slide.style.opacity = i === index ? 1 : 0;
       });
     }
   }
   new FadeSwipe('.swipe-container');
   

2. Laravel Service Provider Register a global Swipe helper:

   // app/Providers/AppServiceProvider.php
   use ContaoComponents\Swipe\Swipe;
   
   public function boot() {
       if (!function_exists('swipe')) {
           function swipe($selector, $options = []) {
               return new Swipe($selector, $options);
           }
       }
   }
   

   Usage in Blade:

   @swipe('#slider', ['auto' => 2000])
   

3. Server-Side Slide Data Fetch slides via AJAX and update dynamically:

   fetch('/api/slides')
     .then(res => res.json())
     .then(slides => {
       const container = document.querySelector('.swipe-container');
       container.innerHTML = slides.map(slide => `<div class="swipe-slide">${slide.content}</div>`).join('');
       new Swipe(container);
     });
   

Performance Tips

• Lazy-Load Slides: Use Intersection Observer to load slides only when they’re near the viewport.
• Debounce Resize Events: Reinitialize the slider only after window resizing stops:

  let resizeTimeout;
  window.addEventListener('resize', () => {
    clearTimeout(resizeTimeout);
    resizeTimeout = setTimeout(() => {
      new Swipe('.swipe-container');
    }, 200);
  });