Fancybox Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexandermatveev/fancybox-bundle
   

   Ensure your project uses Symfony 3+ (compatible with Symfony 2.1+ in dev).

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Alexandermatveev\FancyboxBundle\AlexandermatveevFancyboxBundle::class => ['all' => true],
   

3. First Use Case: Include assets in a Twig template (e.g., base.html.twig):

   <link href="{{ asset('bundles/alexandermatveevfancybox/dist/jquery.fancybox.min.css') }}" rel="stylesheet">
   <script src="{{ asset('bundles/alexandermatveevfancybox/dist/jquery.fancybox.min.js') }}"></script>
   

   Initialize Fancybox for a gallery:

   <a data-fancybox="gallery" href="image.jpg">Image 1</a>
   <a data-fancybox="gallery" href="image2.jpg">Image 2</a>
   

4. Verify: Check the Fancybox 3 docs for basic usage (e.g., data-fancybox, data-src, data-caption).

Implementation Patterns

Core Workflows

1. Basic Image Gallery: Use data-fancybox="gallery" for grouped images. Example:

   <div class="gallery">
       {% for image in images %}
           <a data-fancybox="gallery" href="{{ asset(image.path) }}" data-caption="{{ image.title }}">
               <img src="{{ asset(image.thumbnail) }}" alt="{{ image.title }}">
           </a>
       {% endfor %}
   </div>
   

2. Dynamic Initialization: Initialize Fancybox via JavaScript after DOM load (e.g., for AJAX-loaded content):

   $(document).on('click', '[data-fancybox]', function() {
       $.fancybox.open($(this));
   });
   

3. Custom Templates: Override Fancybox’s default UI by extending its CSS/JS. Place custom files in web/bundles/alexandermatveevfancybox/ to override bundle assets.

4. Symfony Integration:

   • Assets: Use asset() for paths (e.g., {{ asset('bundles/...') }}).
   • Twig Extensions: Create a custom Twig extension to generate Fancybox markup dynamically:

     // src/Twig/FancyboxExtension.php
     class FancyboxExtension extends \Twig\Extension\AbstractExtension
     {
         public function getFunctions()
         {
             return [
                 new \Twig\TwigFunction('fancybox_link', [$this, 'generateFancyboxLink']),
             ];
         }
     
         public function generateFancyboxLink(string $href, string $caption = null): string
         {
             $attributes = ['data-fancybox="gallery"', 'href="' . htmlspecialchars($href) . '"'];
             if ($caption) {
                 $attributes[] = 'data-caption="' . htmlspecialchars($caption) . '"';
             }
             return '<a ' . implode(' ', $attributes) . '></a>';
         }
     }
     

     Usage in Twig:

     {{ fancybox_link(asset(image.path), image.title) }}
     

5. Lazy Loading: Combine with lazy-loading libraries (e.g., ozymko/vite-plugin-lazy) for performance:

   <a data-fancybox data-src="{{ asset(image.path) | lazyload }}" href="javascript:;">
       <img src="placeholder.jpg" data-src="{{ asset(image.thumbnail) }}" loading="lazy">
   </a>
   

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • The bundle assumes assets are placed in bundles/alexandermatveevfancybox/. If using Symfony Flex or custom paths, override via config/packages/alexandermatveev_fancybox.yaml (if supported) or manually update paths in Twig.

2. jQuery Dependency:

   • Fancybox 3 requires jQuery. Ensure it’s loaded before Fancybox’s JS:

     <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
     <script src="{{ asset('bundles/alexandermatveevfancybox/dist/jquery.fancybox.min.js') }}"></script>
     

3. Outdated Version:

   • The bundle ships Fancybox 3.5.2 (released 2018). For newer features, manually replace assets in vendor/alexandermatveev/fancybox-bundle/ with latest Fancybox 3.

4. Twig Autoloading:

   • If using Symfony 4+, ensure Twig is configured to autoload templates from the bundle’s Resources/views/ (though this bundle lacks Twig templates).

5. License Compliance:

   • Fancybox’s license requires attribution. Include a link to Fancybox’s license in your project’s credits.

Debugging Tips

1. Console Errors:

   • Check for Uncaught TypeError if jQuery is missing or loaded after Fancybox. Use browser dev tools (F12) to verify.

2. Fancybox Not Initializing:

   • Ensure data-fancybox attributes are present. Test with a hardcoded link first:

     <a data-fancybox href="https://example.com/image.jpg">Test</a>
     

3. Custom CSS Overrides:

   • Use !important sparingly. Inspect elements to confirm your CSS is loaded after Fancybox’s.

Extension Points

1. Custom Events:

   • Bind to Fancybox events (e.g., afterLoad) via jQuery:

     $(document).on('click', '[data-fancybox]', function() {
         $.fancybox.open({
             src: this.href,
             afterLoad: function() {
                 console.log('Image loaded');
             }
         });
     });
     

2. API Integration:

   • Use Fancybox’s API methods to control instances programmatically:

     $.fancybox.close(); // Close current instance
     $.fancybox.open({ src: '/new-image.jpg' }); // Open a new image
     

3. Symfony Event Listeners:

   • Trigger Fancybox initialization after a Symfony event (e.g., kernel.response):

     // src/EventListener/FancyboxListener.php
     class FancyboxListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [KernelEvents::RESPONSE => 'onKernelResponse'];
         }
     
         public function onKernelResponse(FilterResponseEvent $event)
         {
             $response = $event->getResponse();
             if ($response->headers->contains('Content-Type', 'text/html')) {
                 $this->addFancyboxJS($response);
             }
         }
     
         private function addFancyboxJS(Response $response)
         {
             $content = $response->getContent();
             $content = str_replace('</body>', '
                 <script src="' . asset('bundles/alexandermatveevfancybox/dist/jquery.fancybox.min.js') . '"></script>
                 <script>$(document).ready(function(){$("[data-fancybox]").fancybox();});</script>
             </body>', $content);
             $response->setContent($content);
         }
     }
     

4. Webpack Encore:

   • Replace bundle assets with your own build. Add to webpack.config.js:

     Encore
         .addEntry('fancybox', './vendor/alexandermatveev/fancybox-bundle/Resources/public/js/fancybox.js')
         .enableSingleRuntimeChunk()
         .copyFiles({
             from: './vendor/alexandermatveev/fancybox-bundle/Resources/public/css/',
             to: 'bundles/alexandermatveevfancybox/[path][name].[hash].[ext]',
         });