MFPanZoom - image pan zoomer & gallery module

Having spent some time investigating image zooming, I had been using the anavaka panzoom from GitHub but decided it was just too painful and the support/documentation was lacking; the final straw was the initial centering and the swipe support - so decided it was time just to do my own: MFPanZoom.

The aim was to provide a light weight mouse/touch device capable, simple to implement image pan-zoomer, with gallery lightbox facility with swipe gestures supported and no additional network activity.

Mouse & Touch capable (as of release 1.0)

• Windows: check
• Android: check
• iOS: check

Key Features

• Mouse zoom and move check
• Touch zoom and move check
• Gallery Lightbox viewer check
• Gallery Lightbox fit-content initialisationcheck
• Gallery Lightbox thumb/full-size awarecheck
• Gallery Lightbox swipe left/right built-incheck
• Zero additional network activity (unless necessary for images not yet loaded)check
• Optional Captionscheck

The class also manages the understanding that galleries might show thumbnails, but the lightbox behind each will want to show the full-sized image.

Implementation requires the .js and .css files to be included

html

<script src='https://www.methodfish.com/Download/MFPanZoom/files/latest/js/mf-panzoom.js'></script>
<link rel='stylesheet preload prefetch' as='style' href='https://methodfish.com/Download/MFPanZoom/files/latest/css/mf-panzoom.css'>

Then all that is needed is for any <img> you wish to be managed to include the mfpanzoom class.

html

<img class="mfpanzoom" src="https://......">

When the .js file loads, it will create the _mfpanzoom global, and automatically calls _mfpanzoom.init() to initialise the images on the page.

Any <img> within a .mfpanzoom-gallery class will be presented as a gallery thumbnail with click to view functionality.

html

<div class="mfpanzoom-gallery">
     <img src="https://...">
     <img src="https://...">
     <img src="https://...">
     <img src="https://...">
</div>

If you are wishing to show the gallery with thumbnails, but lightbox the full sized image then you can use _mfpanzoom.setOption('fullsizeAttrArr', ['data-alt-src']); with your chosen alt-src attribute:

html

<div class="mfpanzoom-gallery">
     <img src="https://...thumb...">
     <img src="https://...thumb..." data-alt-src="https://...full...">
     <img src="https://...thumb...">
     <img src="https://...thumb...">
</div>

js

document.addEventListener('DOMContentLoaded', function () {
    _mfpanzoom.setOption('fullsizeAttrArr', ['data-alt-src']);
});

To include a caption against each <img> as you lightbox view them, you can include a data-caption attribute:

html

<div class="mfpanzoom-gallery">
     <img src="https://..." data-caption="Caption 1">
     <img src="https://..." data-caption="Caption 2">
     <img src="https://..." data-caption="Caption 3">
     <img src="https://..." data-caption="Caption 4">
</div>

Outside of the .mfpanzoom-gallery, any <img> with the class .mfpanzoom will support panzoom from the existing position; to do this it will add a container around those images to support the zooming.

By default, the images will be presented centered and fitting the container space. To adjust this you can call

js

document.addEventListener('DOMContentLoaded', function () {
   _mfpanzoom.setOption('initialPosition',''); // center or ''
   _mfpanzoom.setOption('initialZoomPct', 'fit-content'); // i.e. make image fit
   _mfpanzoom.setOption('initialZoomPct', '50'); // i.e. 50%
});

To configure a boundary space around the zoomed image:

js

document.addEventListener('DOMContentLoaded', function () {
   _mfpanzoom.setOption('dragBoundaryLimited','false'); // true or false
   _mfpanzoom.setOption('dragBoundsPaddingPct','10'); // ie. 10%
}

To turn on or off drifting after a pan move

js

document.addEventListener('DOMContentLoaded', function () {
   _mfpanzoom.setOption('drift','false'); // true or false
});

If you want to capture swipe left/right events then include the swipeLeftRight option, e.g.

js

document.addEventListener('DOMContentLoaded', function () {
   _mfpanzoom.setOption('swipeLeftRightCB', function (direction, newImgElem) {
    // Note, newImgElem is the displayed img - not necessarily the one from the original gallery when fullsizeAttrArr alternatives are taken into account
    // If you need to map this elem back to the original gallery entry then it's worth using a data attribute as a uid
    console.log("I "+direction+" to", newImgElem);
    });
});

This is also called on first view in the lightbox; direction arguments include:

• "swipe-prev" (change image to the one before/left of the current)
• "swipe-next" (change image to the one after/right of the current)
• "clicked" (first view click)

To add in an hourglass when a large image is being loaded, you can use hourglassShowCB and hourglassRemoveCB, e.g.

html

<script defer src='https://methodfish.com/Download/MFHourglass/files/latest/js/mf-hourglass.js'></script>
<link rel='stylesheet preload prefetch' as='style' href='https://methodfish.com/Download/MFHourglass/files/latest/css/mf-hourglass.css'>

...and...

js

document.addEventListener('DOMContentLoaded', function () {
   _mfpanzoom.setOption('hourglassShowCB', () => MFHourglass.show());
   _mfpanzoom.setOption('hourglassRemoveCB', () => MFHourglass.remove());
});

Custom Lightboxes

If you want to implement your own lighbox instead of the out-of-the-box mfpanzoom lightbox, then you can but there are some steps:

1. call _mfpanzoom.setCustomLightbox(true); to declare you are using your own lightbox
2. use a lightbox with the class mfpanzoom-lightbox and a sub-element with class container

php

echo "
<div id="url-preview">
                    <div class="my-lightbox mfpanzoom-lightbox">
                        <div class="container">${imgTag}</div>
                        <span class="material-icons btn-toggle">keyboard_double_arrow_up</span>
                        <span class="material-icons btn-cropper">crop</span>
                        <span class="material-icons custom btn-previous">play_arrow</span>
                        <span class="material-icons custom btn-next">play_arrow</span>
                    </div>
                </div>
";

3. call _mfpanzoom.init(); to initialise the lightbox popup
4. call _mfpanzoom.setLightbox(qs('.mfpanzoom-lightbox')); to point to your custom box structure
5. call _mfpanzoom.setCurrentImage(imgElem); to extract your chosen gallery image and put it into the lightbox
6. for the previous and next buttons, call _mfpanzoom.doSwipe('prev', lightboxImgElem, _mfpanzoom.getPrevGalleryImg()); and _mfpanzoom.doSwipe('next', lightboxImgElem, _mfpanzoom.getNextGalleryImg());
7. Use _mfpanzoom.applyInitialPosition(lightboxImgElem)
8. Use _mfpanzoom.restoreCurrentImage(); on closing the lightbox, to put the lightbox element back into the gallery