blackbird/hyva-photo-swipe

An implementation of PhotoSwipe library in Hyvä Theme for Magento 2

1.0.0 2023-09-26 15:42 UTC

Requires

• hyva-themes/magento2-default-theme: *
• magento/framework: *

MIT

• Blackbird Agency

README

An implementation of PhotoSwipe library in Hyvä Theme for Magento 2

You no longer need to worry about how to implement PhotoSwipe in your Magento 2 Hyvä Theme projects.
No manipulations required, instant use after installation.

PhotoSwipe allows you to create full-screen sliders, zoomable, and fully customizable.

The librairy is lazily loaded and does not affect performances accoding to Hyvä documentation.

How It Works • Installation • Usage • More modules

How It Works

The module simply loads PhotoSwipe on all pages that use the PhotoSwipeLightbox class in the DOM
(the class provied by PhotoSwipe).

When the library has been loaded on the page, a state stored in the Alpine.store is updated, indicating that PhotoSwipe is ready for use.

The state can also be used to force the library to be loaded at any time, here is an example using forceLoad()

Installation

Requirements

• Hyvä Magento 2 Theme

composer require blackbird/hyva-photo-swipe

php bin/magento setup:upgrade

In production mode, do not forget to recompile and redeploy the static resources.

Usage

Once the module has been installed, simply add the HTML code required to create a slider, don't forget to specify for each child the data-pswp-width and data-pswp-height.

<div id="my-gallery">
  <a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-2500.jpg" 
    data-pswp-width="1669" 
    data-pswp-height="2500" 
    target="_blank">
    <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-200.jpg" alt="" />
  </a>
  <a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-2500.jpg" 
    data-pswp-width="1875" 
    data-pswp-height="2500" 
    target="_blank">
    <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-200.jpg" alt="" />
  </a>
  <a href="https://unsplash.com" 
    data-pswp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"
    data-pswp-width="2500" 
    data-pswp-height="1666" 
    target="_blank">
    <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg" alt="" />
  </a>
</div>

Next, create a function to listen the Alpine.store state is_loading indicating that PhotoSwipe has been loaded, and apply PhotoSwipe to the HTML elements, as described in the PhotoSwipe documentation.

Don't forget to fill in the important options :

• gallery: query selection of your parent gallery node
• children: query selection of your children repetiting nodes
• pswpModule: just give it PhotoSwipe

<?php
use \Blackbird\HyvaPhotoSwipe\Api\HyvaPhotoSwipeInterface;
?>
<script>
    function myXData () {
        return {
            initPhotoSwipe() {
                if (Alpine.store('<?= HyvaPhotoSwipeInterface::HYVA_PHOTO_SWIPE ?>').is_loaded) {
                    new PhotoSwipeLightbox({
                        gallery: '#my-gallery',
                        children: 'a',
                        pswpModule: PhotoSwipe,
                        ...options
                    }).init();
                }
            }
        }
     }
</script>

You can specify any of the PhotoSwipe options as shown here

Finally, set up the x-data directive and do not forget to call the previous function in an x-effect, to prevent PhotoSwipe being applied until the library is loaded, and to allow it to be automatically applied when the library is loaded.

<div id="my-gallery" x-data="myXData()" x-effect="initPhotoSwipe">
  ...
</div>

Full example

<?php
use \Blackbird\HyvaPhotoSwipe\Api\HyvaPhotoSwipeInterface;
?>
<div id="my-gallery" x-data="myXData()" x-effect="initPhotoSwipe">
  <a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-2500.jpg" 
    data-pswp-width="1669" 
    data-pswp-height="2500" 
    target="_blank">
    <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-200.jpg" alt="" />
  </a>
  <a href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-2500.jpg" 
    data-pswp-width="1875" 
    data-pswp-height="2500" 
    target="_blank">
    <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-200.jpg" alt="" />
  </a>
  <a href="https://unsplash.com" 
    data-pswp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"
    data-pswp-width="2500" 
    data-pswp-height="1666" 
    target="_blank">
    <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg" alt="" />
  </a>
</div>
<script>
    function myXData () {
        return {
            initPhotoSwipe() {
                if (Alpine.store('<?= HyvaPhotoSwipeInterface::HYVA_PHOTO_SWIPE ?>').is_loaded) {
                    new PhotoSwipeLightbox({
                        gallery: '#my-gallery',
                        children: 'a',
                        pswpModule: PhotoSwipe,
                        ...options
                    }).init();
                }
            }
        }
     }
</script>

You can specify any of the PhotoSwipe options as shown here

Example : usage of forceLoad()

Imagine the following case: you do not have the script calling the PhotoSwipeLightbox class provided by the librairy in your DOM, and you want to add it when a user's action is triggered.

In this case, PhotoSwipe won't be loaded by default on the page, you will have to explicitly request that PhotoSwipe be loaded.

Alpine.store('<?= HyvaPhotoSwipeInterface::HYVA_PHOTO_SWIPE ?>').forceLoad()

or

$store.<?= HyvaPhotoSwipeInterface::HYVA_PHOTO_SWIPE ?>.forceLoad()

To find out exactly which one to use, please see the official Alpine documentation for $store or for Alpine.store.

This will force the library to load on the page, even if no script call the PhotoSwipeLightbox class. You can then follow the classic Usage procedure to apply PhotoSwipe.

More modules

hyva-splide-js : An implementation of SplideJS library in Hyvä Theme for Magento 2, highly optimized and customizable sliders.