Carruselbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require edemy/carruselbundle
   

   Enable the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Edemy\CarruselBundle\EdemyCarruselBundle::class => ['all' => true],
   ];
   

2. First Use Case Create a carousel in Twig:

   {{ carrusel({
       'items': [
           {'image': '/path/to/image1.jpg', 'title': 'Slide 1'},
           {'image': '/path/to/image2.jpg', 'title': 'Slide 2'},
       ],
       'options': {
           'autoplay': true,
           'interval': 3000,
       }
   }) }}
   

3. Configuration Check config/packages/edemy_carrusel.yaml for default settings (e.g., default autoplay, transition speed). Override as needed:

   edemy_carrusel:
       default_options:
           autoplay: false
           interval: 5000
   

Implementation Patterns

Common Workflows

1. Dynamic Data Binding Fetch carousel items from a database (e.g., Doctrine entities) and pass them to the Twig template:

   // Controller
   $slides = $entityManager->getRepository(Slide::class)->findBy(['active' => true]);
   return $this->render('homepage.html.twig', ['slides' => $slides]);
   

   {{ carrusel({
       'items': slides|map(attribute='toArray')|first,
       'options': {'interval': 4000}
   }) }}
   

2. Reusable Components Create a base template for carousels (e.g., components/carrusel.html.twig) and extend it:

   {% extends 'components/carrusel.html.twig' %}
   {% block carrusel_content %}
       <div class="custom-slide">{{ item.title }}</div>
   {% endblock %}
   

3. Event-Driven Customization Listen to the edemy_carrusel.init event to modify options globally:

   // src/EventListener/CarruselListener.php
   public function onCarruselInit(CarruselEvent $event) {
       $event->setOption('autoplay', false);
   }
   

   Register in services.yaml:

   services:
       App\EventListener\CarruselListener:
           tags:
               - { name: kernel.event_listener, event: edemy_carrusel.init }
   

4. Asset Management Override default assets (JS/CSS) by publishing the bundle’s assets:

   php bin/console assets:install public
   

   Customize paths in config/packages/edemy_carrusel.yaml:

   assets:
       js: '/custom/path/carrusel.js'
       css: '/custom/path/carrusel.css'
   

Gotchas and Tips

Pitfalls

1. Twig Template Paths Ensure Twig templates (resources/views/) are in the correct location. The bundle assumes a standard Symfony structure. If using custom paths, override the twig.path in the bundle’s configuration.

2. Asset Loading Order If the carousel fails to initialize, verify that the bundle’s JS is loaded after jQuery (if dependent). Use Twig’s {% block javascripts %} to inject scripts in the correct order:

   {% block javascripts %}
       {{ parent() }}
       {{ asset('bundles/edemycarrusel/js/carrusel.js') }}
   {% endblock %}
   

3. Circular Dependencies Avoid circular references when extending the bundle’s templates. Use {% block %} sparingly and prefer composition over inheritance for complex carousels.

4. Database-Driven Slides If fetching slides from a database, ensure the items array in Twig matches the expected structure:

   {# ❌ Fails #}
   {{ carrusel({'items': slides}) }} {# Missing 'image'/'title' keys #}
   
   {# ✅ Works #}
   {{ carrusel({
       'items': slides|map(attribute=['image', 'title'])
   }) }}
   

Debugging

• Check Console Errors: Look for Uncaught ReferenceError or TypeError in the browser console. Common causes:
  • Missing jQuery ($ is not defined).
  • Incorrect Twig syntax (e.g., unclosed braces).
• Enable Debug Mode: Set APP_DEBUG=true in .env to see detailed errors from the bundle.
• Log Events: Use Symfony’s event dispatcher to log carousel initialization:

  public function onCarruselInit(CarruselEvent $event) {
      $this->logger->debug('Carrusel initialized with options:', $event->getOptions());
  }
  

Extension Points

1. Custom Transitions Override the default transition effect by extending the bundle’s JavaScript:

   // public/bundles/edemycarrusel/js/custom-carrusel.js
   $(document).ready(function() {
       $('.carrusel').carrusel('option', 'transition', 'fade');
   });
   

2. Add Interactive Elements Use the onInit callback in Twig to attach custom behavior:

   {{ carrusel({
       'items': slides,
       'options': {
           'onInit': 'function(carrusel) {
               carrusel.on("slideChange", function() {
                   console.log("Slide changed!");
               });
           }'
       }
   }) }}
   

3. Server-Side Pagination For large datasets, implement pagination via AJAX:

   // In your custom JS
   $('.carrusel').on('slideToEnd', function() {
       $.get('/api/slides?page=2', function(data) {
           $('.carrusel').carrusel('addSlides', data.slides);
       });
   });
   

4. Configuration Validation Validate custom options in a compiler pass:

   // src/DependencyInjection/Compiler/CarruselPass.php
   public function process(ContainerBuilder $container) {
       $definition = $container->findDefinition('edemy_carrusel.twig_extension');
       $options = $definition->getArgument(0);
       if (!isset($options['interval']) || $options['interval'] < 1000) {
           throw new \InvalidArgumentException('Interval must be >= 1000ms');
       }
   }