MarkupProcesswirePhotoswipe

MarkupProcesswirePhotoswipe is a module for an easy yet customizable image gallery integration into your ProcessWire website. It uses Photoswipe by Dmitry Semenov, @dimsemenov, a very very good Javascript lightbox/gallery which does not depend on jQuery or anything else.

This guide is likely incomplete but hopefully sufficient enough to get you started. Please let me know if you find any errors and bugs or if you have any suggestions and requests!

You may get support directly from me or in the official ProcessWire forum thread

In the processwire modules directory

Installing the module

The ProcessWire way of life: http://modules.processwire.com/install-uninstall/

I recommend to install the module via Modules > New > Add Module From Directory. Paste the class name MarkupProcesswirePhotoswipe into the text field and click Download And Install.

How To

Plug In Module

You can simply create a gallery and insert a thumbnail view by passing an image field to the module like so:

$pwpswp = $modules->get('MarkupProcesswirePhotoswipe');
echo $pwpswp->renderGallery($page->nicePictures);

All necessary scripts will then be automatically inserted into the page markup via hook after page render. They won't if you do not call the function.

Mind that renderGallery() returns the markup string for delayed output. So you will have to echo the markup at a desired place.

The default gallery is "Petersburger Hängung" (wtf?). You can choose the default gallery style in the module config or you can choose different galleries during runtime like so:

echo $pwpswp->renderGallery($page->nicePictures, 'plain');
echo $pwpswp->renderGallery($page->nicePictures, $optionsArray, 'plain');
echo $pwpswp->renderGallery($page->nicePictures, ['gallery' => 'plain', 'moreOptions' => ...]);

Every gallery module has a short alias which is used here. You can find it in the description of the module. Otherwise, here is the list:

petersburger: A balanced gallery (default).
plain: Base module, nothing is styled here.
flex: Basic grid using flexbox.
h-scroller: Horizontally scrollable box.

BYOM (Build Your Own Module)

Extend MarkupPwpswpGallery class
implement ::alias() method which returns unique short name
implement ::render() function and process images to your liking
there are severel helper functions which are probabyly useful
- $this->resizeImage($image, $resizeOptions)
  resize an image
- $this->prepareImageData(WireData $image, $options = [])
  prepares array of data for
- $this->renderImageElement($data)
  receives prepared image data and renders markup for an image
- $this->wrapMarkup($innerMarkup, $options = [])
  wraps up the whole package
- $this->getPswpOptionsAttribute($pswpOptions)
  returns the pswp options as escaped json

[...]

BYOM (Bring Your Own Markup) DEPRECATED

[...]

echo $pwpswp->renderGallery($images, $options, 'to/template/file.php');
echo $pwpswp->renderGallery($images, 'to/template/file.php');
echo $pwpswp->renderGallery($page->nicePictures, ['theme' => 'to/template/file.php']);

Options And Configuration

ProcesswirePhotoswipe tries to stick to the original configuration and options terminology and structure Processwire and Photoswipe are using.

Here are the availbale options with examples:

$galleryOptions = [

    // Choose gallery
    'gallery' => 'petersburger',

    // Image resize options for thumbnail image.
    // Example: Default module configuration.
    'imageResizerOptions' => [
        'size' => '500x500',
        'quality' => 70,
        'upscaling' => false,
        'cropping' => false
    ],

    // Image resize options for quick preview image in Photoswipe.
    // Example: Default module configuration.
    'loresResizerOptions' => [
        'size' => '500x500',
        'quality' => 20,
        'upscaling' => false,
        'cropping' => false
    ],

    // options for Photoswipe; will be JSON encoded.
    // example: Some random options.
    'pswpOptions' => (object) [ // <-- cast as stdClass !!!
        'shareEl' => false,
        'indexIndicatorSep' => ' von ',
        'closeOnScroll' => false
    ]
];

echo $pwpswp->renderGallery($page->images, $galleryOptions);

imageResizerOptions

Options for the thumbnail images of the galleries. It uses Processwires ImageSizer options and is also configurable in the module configuration. See a list of available options here.

Note: Size is provided as a string like 150x430 (width x height) !!

loresResizerOptions

Options for lowres images for fast previews in Photoswipe. Same principle as above.

pswpOptions

Options for Photoswipe; see the Photoswipe documentation for available options. The options will be provided to the script as json.

Note how pswpOptions is cast as a stdClass object to mimic Photoswipes options object. Do the same to avoid complications.

Custom scripts and usage of AMD

You can deactiveate the automatic insertion of the script tags in the modules configuration.

If you want to use eg. require.js you can also activate that option. The photoswipe initiation script will be compatible then. Also you will need to initiate the galleries manually by calling the init() method of the JS module.

Compatibility

Legacy

I rewrote the module for version 0.99.0. The legacy code is still available on the legacy branch.

Javascript

Javascript stuff should work from ie10+ upwards. You may still provide your own more compatible gallery init script. (See Custom scripts and usage of AMD)

ToDos, perspective and notes

srcset
individual images lightbox mode
- options:
  - manual trigger
  - "auto on all pages" (default)
- groupable
gallery module: "click on single preview image opens gallery with multiple images"

Changelog

0.99.1 - 2017/11/16

fixed: ProcessWirePhotoswipe.module was not able to get correct url when modules directory differed from class name. Determine module urls with actual file path via reflector class now.

0.99.0 - 2017/11/13

other: Refactoring. No more 'themes', instead gallery modules.
added: Basic gallery module (MarkupPwpswpGallery) to extend from
added: Gallery 'Petersburger Hängung'
added: Photoswipe animation on gallery init
added: Galleries open automatically via url hash e.g. "#&gid=1&pid=2"

0.7.5 - 2017/10/24,

breaking change: Renamed getResizeLamda() to getResizeClosure()
fixed: Removal of scalar type hints for compatibility to php 5.6
other: Very minor code refactoring

0.7.1 - 2017/07/13, rubberband fix

fixed: Added rubberband/momentum scrolling on ios for h-scroller theme.

0.7 - 2017/07/12, themes

fixed: Size option correctly adopts height value
added: Theme functionality
added: Simple themes 'plain' (previous default), 'flex', 'h-scroller'
other: Updated readme
other: No notice on undefined photoswipe options
other: Refactoring

0.6 - 2017/07/06, liberated renderGallery()

added: Liberated renderGallery() to accept arrays and WireArray derivatives
removed: Removed pointless shortcut alias class
fixed: Use of correct module/class name for file paths
fixed: Configuration instructions for file paths
other: Updated readme
other: Updated readme

blynx / MarkupProcesswirePhotoswipe