Ux Interactive Image Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require baztianzh/ux-interactive-image
   yarn install --force
   yarn watch
   

   Ensure symfony/ux is installed (this package depends on it).

2. First Use Case:

   • Create a controller method with InteractiveImageBuilderInterface dependency.
   • Build an interactive image with a path:

     $interactiveImage = $builder->createInteractiveImage('/build/images/my-image.jpg');
     

   • Add a TextItem (or other item types) to the image:

     $textItem = new TextItem(200, 20, 'title', 'description');
     $interactiveImage->addItem($textItem);
     

   • Render in Twig:

     {{ render_interactive_image(interactiveImage) }}
     

3. Verify:

   • Check the browser console for jQuery/Interactive Image initialization errors.
   • Inspect the rendered HTML to confirm the image and overlay elements are present.

Implementation Patterns

Core Workflows

1. Controller Integration:

   • Use InteractiveImageBuilderInterface to construct images dynamically (e.g., from database records).
   • Example: Fetch product images and annotations from a Product entity:

     $image = $builder->createInteractiveImage($product->getImagePath());
     foreach ($product->getAnnotations() as $annotation) {
         $image->addItem(new TextItem($annotation->getX(), $annotation->getY(), $annotation->getTitle()));
     }
     

2. Twig Rendering:

   • Pass the built InteractiveImage object to Twig and use the render_interactive_image function.
   • Customize with classes/attributes:

     {{ render_interactive_image(interactiveImage, {'class': 'interactive-product-image', 'data-id': product.id}) }}
     

3. Asset Management:

   • Ensure image paths are correct (e.g., /build/images/ for Webpack-encoded assets).
   • Use Symfony’s asset() helper in Twig for dynamic paths:

     {{ render_interactive_image(interactiveImage, {'imagePath': asset('images/my-image.jpg')}) }}
     

4. Event-Driven Interactions:

   • Listen for Interactive Image events (e.g., itemClick) via JavaScript:

     document.addEventListener('interactiveImageItemClick', (e) => {
         console.log('Clicked item:', e.detail.item);
     });
     

   • Dispatch custom events from Twig using data-* attributes or Symfony’s Stimulus bridge.

Integration Tips

1. Symfony UX Compatibility:

   • Leverage Symfony UX’s Stimulus controllers for advanced interactions.
   • Example: Combine with symfony/ux-turbo for real-time updates:

     {% block javascripts %}
         {{ parent() }}
         {{ stimulate_controller('interactive-image', {
             'imagePath': interactiveImage.path,
             'items': interactiveImage.items|json_encode
         }) }}
     {% endblock %}
     

2. Dynamic Item Types:

   • Extend the package by creating custom item classes (e.g., CircleItem, PolygonItem) by implementing the ItemInterface.
   • Register them in the builder’s configuration.

3. Localization:

   • Use Symfony’s translation system for item labels/descriptions:

     $textItem = new TextItem(100, 50, 'app.interactive.title', [], 'interactive');
     

4. Performance:

   • Lazy-load images or items using Intersection Observer:

     const observer = new IntersectionObserver((entries) => {
         entries.forEach(entry => {
             if (entry.isIntersecting) {
                 entry.target.interactiveImage('init');
                 observer.unobserve(entry.target);
             }
         });
     });
     

Gotchas and Tips

Pitfalls

1. jQuery Dependency:

   • The package relies on jQuery. Ensure it’s loaded before the Interactive Image script.
   • Debug missing interactions with:

     console.log(jQuery.fn.interactiveImage); // Should return a function
     

2. Asset Paths:

   • Hardcoded paths (e.g., /build/images/) may break in production if Webpack Encore’s public path changes.
   • Fix: Use asset() in Twig or configure Encore’s publicPath dynamically.

3. Twig Function Missing:

   • If render_interactive_image is undefined, clear the Twig cache:

     php bin/console cache:clear
     

4. Item Coordinates:

   • Coordinates are relative to the image container, not the viewport. Test with position: absolute on the container.

5. Stimulus Conflicts:

   • If using Symfony UX Stimulus, ensure the Interactive Image script runs after Stimulus is initialized.

Debugging

1. Console Errors:

   • Check for interactiveImage is not a function (missing jQuery plugin initialization).
   • Verify the script tag exists in the rendered HTML:

     <script src="/build/interactive-image.js"></script>
     

2. Network Tab:

   • Confirm the image path resolves correctly (404 errors will break rendering).

3. Twig Debug:

   • Dump the InteractiveImage object to verify items are added:

     {{ dump(interactiveImage) }}
     

Extension Points

1. Custom Items:

   • Implement BaztianZh\UX\InteractiveImage\Item\ItemInterface for new item types (e.g., VideoItem):

     class VideoItem implements ItemInterface {
         public function getHtml(): string {
             return '<video src="..."></video>';
         }
         // ... other methods
     }
     

2. Builder Configuration:

   • Override the default builder via dependency injection:

     # config/services.yaml
     BaztianZh\UX\InteractiveImage\Builder\InteractiveImageBuilderInterface: '@app.custom_interactive_image_builder'
     

3. Stimulus Controller:

   • Extend the default Stimulus controller to add custom logic:

     // assets/controllers/interactive_image_controller.js
     import { Controller } from '@hotwired/stimulus';
     import { InteractiveImage } from 'interactive-image';
     
     export default class extends Controller {
         connect() {
             new InteractiveImage(this.element, {
                 items: JSON.parse(this.data.get('items')),
             });
         }
     }
     

4. Webpack Encore:

   • Customize the Interactive Image entry in webpack.config.js:

     Encore
         .addEntry('interactive-image', './vendor/baztianzh/ux-interactive-image/resources/js/interactive-image.js')
         .copyFiles({
             from: './vendor/baztianzh/ux-interactive-image/resources/public',
             to: 'build/[path][name].[ext]',
         });
     

Config Quirks

1. Default Options:

   • The builder uses defaults like zoom: true, pan: true. Override via:

     $builder->setDefaultOptions(['zoom' => false, 'pan' => false]);
     

2. Twig Global:

   • The render_interactive_image function is registered as a Twig global. To override it, redefine it in a custom Twig extension.

3. Yarn Watch:

   • Run yarn watch in development to auto-rebuild assets. In production, use:

     yarn build