Slidewire Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wendelladriel/slidewire
   php artisan vendor:publish --provider="WendellAdriel\SlideWire\SlideWireServiceProvider" --tag="slidewire-config"
   

2. Generate a Deck:

   php artisan make:slidewire MyPresentation
   

   This creates:

   • resources/views/presentations/MyPresentation.blade.php (main deck file)
   • resources/views/presentations/MyPresentation/slides/ (slide templates)
   • config/slidewire.php (configuration)

3. First Use Case: Edit MyPresentation.blade.php to include slides:

   @slidewireDeck
       @slidewireSlide(title="Introduction")
           <h1>Welcome to SlideWire</h1>
           <p>This is your first slide.</p>
       @endslidewireSlide
   
       @slidewireSlide(title="Features")
           <h2>Key Features</h2>
           <ul>
               <li>Livewire-powered</li>
               <li>Markdown support</li>
               <li>Syntax highlighting</li>
           </ul>
       @endslidewireSlide
   @endslidewireDeck
   

4. Route the Deck: Add to routes/web.php:

   SlideWire::route('my-presentation', 'MyPresentation');
   

   Visit /my-presentation to see the presentation.

5. Run Locally:

   php artisan serve
   

Where to Look First

• Documentation: https://slidewire.dev (official docs)
• Example Decks: Check the resources/views/presentations/ directory after generating a deck.
• Configuration: config/slidewire.php for theme, auto-slide, and transition settings.
• Components: Built-in components like @slidewireCode, @slidewireDiagram, and @slidewireMarkdown.

Implementation Patterns

Core Workflows

1. Deck Structure

• Single File Decks: Use @slidewireDeck and @slidewireSlide directives in a single Blade file.
• Composed Decks: Split slides into partials (e.g., resources/views/presentations/MyPresentation/slides/1.blade.php) and include them:

  @slidewireSlide(include="slides/1")
  @endslidewireSlide
  

• Markdown Slides: Use @slidewireMarkdown for content-heavy slides:

  @slidewireMarkdown
      # Slide Title
      This is **Markdown** content.
      ```php
      <?php
      // Code block
      ?>
      ```
  @endslidewireMarkdown
  

2. Navigation and Controls

• Default Navigation: Keyboard arrows, click/tap, and swipe gestures work out-of-the-box.
• Hash-Based Links: Link directly to slides via URL hashes (e.g., /my-presentation#slide-2).
• Custom Controls: Override navigation logic in a Livewire component:

  public function nextSlide()
  {
      $this->slideNumber++;
      $this->emit('slideChanged');
  }
  

3. Dynamic Content

• Livewire Integration: Pass data to slides via Livewire properties:

  @slidewireSlide
      <h1>{{ $title }}</h1>
      <p>Current slide: {{ $slideNumber }}</p>
  @endslidewireSlide
  

  public $title = "Dynamic Slide";
  public $slideNumber = 1;
  

• Database-Driven Slides: Fetch slide content from a database and render dynamically:

  @foreach($slides as $slide)
      @slidewireSlide(title="{{ $slide->title }}")
          {!! $slide->content !!}
      @endslidewireSlide
  @endforeach
  

4. Theming and Styling

• Built-in Themes: Configure in config/slidewire.php:

  'theme' => 'dark',
  

  Available themes: light, dark, custom.
• Custom Themes: Extend the theme schema in config/slidewire.php:

  'themes' => [
      'custom' => [
          'colors' => [
              'primary' => '#3b82f6',
              'background' => '#f8fafc',
          ],
          'typography' => [
              'font-family' => 'Inter, sans-serif',
          ],
      ],
  ],
  

• Global CSS: Add custom styles via public/css/slidewire.css or publish the package assets:

  php artisan vendor:publish --provider="WendellAdriel\SlideWire\SlideWireServiceProvider" --tag="slidewire-assets"
  

5. Auto-Slides and Timers

• Deck-Level Auto-Slide: Configure in config/slidewire.php:

  'auto_slide' => [
      'enabled' => true,
      'interval' => 5, // seconds
  ],
  

• Slide-Level Overrides: Set per slide:

  @slidewireSlide(autoSlideInterval=10)
      <!-- Content -->
  @endslidewireSlide
  

• Pause on Interaction: Auto-slides pause when the user interacts (e.g., clicks, keyboard input).

6. Components and Fragments

• Built-in Components:
  • @slidewireCode: Syntax-highlighted code blocks.
  • @slidewireDiagram: Mermaid.js diagrams.
  • @slidewireMarkdown: Markdown rendering.
  • @slidewireFragment: Reusable slide fragments.
• Example Usage:

  @slidewireCode(language="php")
      <?php
      // Code snippet
      ?>
  @endslidewireCode
  

7. Vertical Slides

• Group slides vertically within a horizontal deck:

  @slidewireVerticalGroup
      @slidewireSlide(title="Vertical Slide 1")
          <!-- Content -->
      @endslidewireSlide
      @slidewireSlide(title="Vertical Slide 2")
          <!-- Content -->
      @endslidewireSlide
  @endslidewireVerticalGroup
  

Integration Tips

Laravel Ecosystem

• Authentication: Protect decks with Laravel middleware:

  Route::middleware(['auth'])->group(function () {
      SlideWire::route('private-deck', 'PrivateDeck');
  });
  

• Localization: Use Laravel’s localization features for multilingual decks:

  @slidewireSlide(title="{{ __('slides.intro.title') }}")
      {{ __('slides.intro.content') }}
  @endslidewireSlide
  

• Events: Listen to slide changes via Livewire events:

  protected $listeners = ['slideChanged' => 'handleSlideChange'];
  
  public function handleSlideChange()
  {
      // Custom logic
  }
  

Testing

• Unit Tests: Test slide rendering logic:

  public function test_slide_rendering()
  {
      $deck = new MyPresentation();
      $this->assertStringContainsString('Welcome to SlideWire', $deck->renderSlide(1));
  }
  

• Browser Tests: Use Playwright for end-to-end testing:

  public function test_presentation_navigation()
  {
      $this->browse()
          ->visit('/my-presentation')
          ->press('ArrowRight')
          ->assertSee('Features');
  }
  

Performance

• Lazy Loading: Load heavy slides (e.g., large diagrams) dynamically:

  @slidewireSlide(lazyLoad=true)
      <img src="{{ asset('large-diagram.svg') }}" alt="Diagram">
  @endslidewireSlide
  

• Caching: Cache compiled decks for faster rendering:

  // In a service provider
  SlideWire::setCacheEnabled(true);
  

Extending Functionality

• Custom Components: Create reusable slide components:

  @component('presentations.components.my-component', ['data' => $data])
  @endcomponent
  

• Livewire Hooks: Extend slide behavior:

  public function mount()
  {
      $this->dispatchBrowserEvent('slidewire:init');
  }
  

• API Integration: Fetch slide content from an external API:

  @slidewireSlide
      @foreach($apiData as $item)
          <div>{{ $item->title }}</div>
      @endforeach
  @endslidewireSlide
  

Gotchas and Tips

Pitfalls

1. Livewire Dependency

• Issue: SlideWire requires Livewire. If Livewire is not installed or configured, the package will fail silently or throw cryptic errors.
• Fix: Ensure Livewire is installed and the Livewire service provider is registered in config/app.php:

  'providers' => [
      // ...
      Livewire\LivewireServiceProvider::class,
      WendellAd