MarkupProcesswirePhotoswipe by blynx

Easily include Photoswipe by Dmitry Semenov


Petersburger Hängung image credits

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:

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);

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) !!


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


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.



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


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"


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
0.5.0 - 2017/07/05, Initial release

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

  • Weekly update – 31 March 2023 – More
    31 March 2023
  • This week ProcessWire 3.0.214 is on the dev branch. Relative to 3.0.213 this version has 16 new commits which include the addition of 3 new pull requests, 6 issue fixes, a new WireNumberTools utility class, and various other improvements. More
    17 March 2023
  • ProcessWire 3.0.213 core updates: This week we’ll look at the new WireSitemapXML module, a new WireNumberTools core class, and a new ability for Fieldtype modules to specify useful ready-to-use configurations when creating new fields. More
    24 February 2023

Latest news

  • ProcessWire Weekly #464
    In the 464th issue of ProcessWire Weekly we're going to check out the latest core updates, introduce a new third party textformatter module for handling footnotes in text, and more. Read on! / 1 April 2023
  • ProcessWire 3.0.213 core updates
    This week we’ll look at the new WireSitemapXML module, a new WireNumberTools core class, and a new ability for Fieldtype modules to specify useful ready-to-use configurations when creating new fields.
    Blog / 24 February 2023
  • Subscribe to weekly ProcessWire news

“The end client and designer love the ease at which they can update the website. Training beyond how to log in wasn’t even necessary since ProcessWire’s default interface is straightforward.” —Jonathan Lahijani