App Business Carousel Bundle Laravel Package

Getting Started

Minimal Setup

1. Install AlphaLemon CMS Sandbox (if not already installed):

   git clone https://github.com/alphalemon/AlphaLemonCmsSandbox.git
   cd AlphaLemonCmsSandbox
   composer install
   

2. Install the Bundle via Composer:

   composer require alphalemon/app-business-carousel-bundle
   

3. Enable the Bundle in app/AppKernel.php:

   new AlphaLemon\BusinessCarouselBundle\AlphaLemonBusinessCarouselBundle(),
   

4. Clear Cache:

   php app/console cache:clear
   

First Use Case

• Create a Carousel Content Type: Navigate to the AlphaLemon CMS admin panel (/admin) and locate the "Business Carousel" section under "Content Types". Click "Add" to create a new carousel.
• Add Slides: Use the built-in editor to add slides (images, text, links) via the "Slides" tab in the carousel management interface.
• Embed in a Page: Use the provided Twig function {{ alphalemon_business_carousel('carousel_id') }} in your templates to display the carousel.

Implementation Patterns

Workflow Integration

1. Content Creation Workflow:

   • Admin Panel: Use the "Business Carousel" editor to create and manage carousels directly in the CMS admin interface.
   • Slide Management: Add, reorder, or delete slides via drag-and-drop or manual input in the "Slides" tab.
   • Metadata: Assign SEO-friendly titles, descriptions, and alt text to slides for better accessibility and indexing.

2. Frontend Integration:

   • Twig Usage:

     {# Display carousel by ID #}
     {{ alphalemon_business_carousel('my_carousel_id') }}
     
     {# Display carousel with custom settings #}
     {{ alphalemon_business_carousel('my_carousel_id', {
         'autoplay': true,
         'speed': 500,
         'pause_on_hover': false
     }) }}
     

   • Dynamic Loading: Fetch carousel data via API (if extended) for SPAs or dynamic pages:

     fetch('/api/carousel/my_carousel_id')
         .then(response => response.json())
         .then(data => renderCarousel(data));
     

3. Theming and Styling:

   • Override default carousel styles by extending the bundle’s Twig templates (located in Resources/views/).
   • Customize slide transitions or animations via CSS/JS overrides in your theme’s assets.

4. Reusable Components:

   • Carousel Partial: Use the carousel as a reusable component in layouts or partials:

     {% include 'partials/carousel.html' with {
         'carousel_id': 'hero_carousel',
         'class': 'full-width'
     } %}
     

   • Conditional Rendering: Show/hide carousels based on context (e.g., user role, device):

     {% if app.user.hasRole('PREMIUM') %}
         {{ alphalemon_business_carousel('premium_carousel') }}
     {% endif %}
     

Gotchas and Tips

Pitfalls

1. Bundle Compatibility:

   • Symfony 2.1 Requirement: Ensure your project uses Symfony 2.1+ (not Symfony 3/4/5). If upgrading, test thoroughly or fork the bundle.
   • AlphaLemon CMS Dependency: The bundle only works with AlphaLemon CMS. Attempting to use it standalone will fail.

2. Caching Issues:

   • Carousel changes may not reflect immediately due to Symfony caching. Clear cache after updates:

     php app/console cache:clear --env=prod
     

   • For development, disable caching temporarily:

     # app/config/config_dev.yml
     framework:
         cache: false
     

3. Missing Documentation:

   • The bundle lacks detailed API docs. Inspect the source (/src/AlphaLemon/BusinessCarouselBundle/) for undocumented features (e.g., custom slide types).
   • Debugging Tip: Enable Symfony profiler (app_dev.php) to inspect carousel data and rendering.

4. Performance:

   • Large Carousels: Heavy carousels (e.g., 20+ slides with high-res images) may slow page load. Optimize images or lazy-load slides:

     {# Lazy-load slides #}
     {{ alphalemon_business_carousel('carousel_id', {'lazy_load': true}) }}
     

   • Database Bloat: Each slide is stored as a separate record. Archive old carousels to avoid table growth.

Tips

1. Extending Slide Types:

   • Add custom slide fields (e.g., videos, buttons) by extending the bundle’s Slide entity:

     // src/AlphaLemon/BusinessCarouselBundle/Entity/Slide.php
     /**
      * @ORM\Column(type="string", nullable=true)
      */
     private $videoUrl;
     

   • Register the new field in the admin form via an event subscriber or override the bundle’s templates.

2. Localization:

   • Translate carousel labels/text via AlphaLemon’s translation system. Add translations to Resources/translations/:

     # Resources/translations/messages.en.yml
     carousel:
         slide: "Slide"
         add_slide: "Add Slide"
     

3. Testing:

   • Use the bundle’s test suite as a reference for writing tests:

     ./vendor/bin/phpunit -c tests/
     

   • Test carousel rendering in isolation by mocking the CarouselManager service.

4. Debugging Rendering:

   • Dump carousel data before rendering to verify structure:

     {% set carousel = _context.getCarousel('my_carousel_id') %}
     {{ dump(carousel) }}
     {{ alphalemon_business_carousel('my_carousel_id') }}
     

   • Check for Twig errors in app/logs/dev.log.

5. Backup Slides:

   • Export carousel data before major updates:

     php app/console doctrine:fixtures:dump --append --em=default
     

   • Restore via fixtures if needed.

6. Custom JavaScript:

   • Override carousel behavior by extending the default JS. Hook into the carousel-init event:

     $(document).on('carousel-init', function(e, carouselId) {
         console.log('Carousel initialized:', carouselId);
         // Custom logic here
     });