304 lines
14 KiB
Markdown
304 lines
14 KiB
Markdown
---
|
||
title: Automagical image gallery in Hugo with PhotoSwipe and jQuery
|
||
date: 2017-03-06T00:00:00Z
|
||
lastmod: 2022-03-25T00:00:00Z
|
||
author: Li-Wen Yip
|
||
avatar: /img/authors/liwenyip.jpg
|
||
authorlink: https://www.liwen.id.au/photoswipe/
|
||
cover: /img/authors/liwenyip.jpg
|
||
# images:
|
||
# - /img/cover.jpg
|
||
categories:
|
||
- Docs
|
||
tags:
|
||
- Photoswipe
|
||
draft: false
|
||
---
|
||
|
||
<!--more-->
|
||
|
||
Update 25/03/2017: I’ve combined this PhotoSwipe implementation with a shortcode that generates a responsive css gallery of all the images in a directory - see [Hugo Easy Gallery](/posts/heg).
|
||
|
||
There are various solutions for implementing [PhotoSwipe](http://photoswipe.com/) in [Hugo](https://gohugo.io/), including [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) and [Tom Helmer’s blog post](http://www.thehome.dk/article/photoswipe-gallery-hugo/), but they all require you group all your images in the once place on the page.
|
||
|
||
What I wanted was:
|
||
|
||
- A lightbox/carousel-style image gallery that loads all of the images in my post, regardless of where in the post they appear;
|
||
- Works with any existing images I’ve embedded using the figure shortcode without me having to change anything; and
|
||
- Does not require me to [pre-define the image sizes](http://photoswipe.com/documentation/faq.html#image-size);
|
||
|
||
I couldn’t find a ready-made solution that met my requirements, so I made my own.
|
||
|
||
All the code in this post is available on [GitHub](https://github.com/liwenyip/hugo-pswp).
|
||
|
||
## New `figure` shortcode
|
||
|
||
If all your existing figures already have a `link` that points to a larger version of the image, then actually Hugo’s built-in `figure` [shortcode](https://gohugo.io/extras/shortcodes/#figure) will work just fine. But if not, we can override the built-in `figure` shortcode to make it work better with PhotoSwipe:
|
||
|
||
Put this file in `/layouts/shortcodes/figure.html`:
|
||
|
||
```html
|
||
<figure {{ with .Get "class" }}class="{{.}}"{{ end }} itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
|
||
<a href="{{ with .Get "link" }}{{.}}{{ else }}{{ .Get "src" }}{{ end }}" {{ with .Get "size" }}data-size="{{.}}"{{ end }} itemprop="contentUrl">
|
||
<img itemprop="thumbnail"
|
||
src="{{ with .Get "src" }}{{.}}{{ else }}{{ printf "%s." (.Get "thumb") | replace (.Get "link") "." }}{{ end }}"
|
||
{{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt" }}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }}
|
||
{{ with .Get "width" }}width="{{.}}"{{ end }}/>
|
||
</a>
|
||
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
|
||
<figcaption>
|
||
{{ with .Get "title" }}<h4>{{.}}</h4>{{ end }}
|
||
{{ if or (.Get "caption") (.Get "attr")}}
|
||
<p>
|
||
{{ .Get "caption" }}
|
||
{{ with .Get "attrlink"}}<a href="{{.}}">{{ .Get "attr" }}</a>{{ else }}{{ .Get "attr"}}{{ end }}
|
||
</p>
|
||
{{ end }}
|
||
</figcaption>
|
||
{{ end }}
|
||
</figure>
|
||
```
|
||
|
||
This new shortcode accepts two new parameters size and thumb, and behaves differently as follows:
|
||
|
||
`{{</* figure src="/img/homepage/cc_jeepers.jpg" */>}}` does the same as normal, but with a hyperlink to itself:
|
||
|
||
{{< figure src="/img/homepage/cc_jeepers.jpg" >}}
|
||
|
||
`{{</* figure link="/img/homepage/cc_jeepers.jpg" thumb="-thumb" */>}}` will display `/img/homepage/cc_jeepers-thumb.jpg` and a hyperlink to `/img/homepage/cc_jeepers.jpg`:
|
||
|
||
{{< figure link="/img/homepage/cc_jeepers.jpg" thumb="-thumb" >}}
|
||
|
||
That’s already kind of useful by itself, but wait, there’s more…
|
||
|
||
## Shortcode to enable PhotoSwipe
|
||
|
||
To initialise PhotoSwipe we need to add some html and include the PhotoSwipe css/js libraries, which we’ll do by creating a `pswp-init` shortcode and calling it anywhere on the page/post where you want to use PhotoSwipe. Note the bulk of this file is as per the PhotoSwipe [getting started docs](http://photoswipe.com/documentation/getting-started.html#initialization), except that I’m linking the PhotoSwipe css/js libraries from a CDN.
|
||
|
||
Put this file in `/layouts/shortcodes/pswp-init.html`:
|
||
|
||
```html
|
||
<!-- Photoswipe css/js libraries -->
|
||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.1/photoswipe.min.css" integrity="sha256-sCl5PUOGMLfFYctzDW3MtRib0ctyUvI9Qsmq2wXOeBY=" crossorigin="anonymous" />
|
||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.1/default-skin/default-skin.min.css" integrity="sha256-BFeI1V+Vh1Rk37wswuOYn5lsTcaU96hGaI7OUVCLjPc=" crossorigin="anonymous" />
|
||
<script src="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.1/photoswipe.min.js" integrity="sha256-UplRCs9v4KXVJvVY+p+RSo5Q4ilAUXh7kpjyIP5odyc=" crossorigin="anonymous"></script>
|
||
<script src="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.1/photoswipe-ui-default.min.js" integrity="sha256-PWHOlUzc96pMc8ThwRIXPn8yH4NOLu42RQ0b9SpnpFk=" crossorigin="anonymous"></script>
|
||
|
||
<!-- Root element of PhotoSwipe. Must have class pswp. -->
|
||
<div class="pswp" tabindex="-1" role="dialog" aria-hidden="true">
|
||
<!-- Background of PhotoSwipe.
|
||
It's a separate element, as animating opacity is faster than rgba(). -->
|
||
<div class="pswp__bg"></div>
|
||
<!-- Slides wrapper with overflow:hidden. -->
|
||
<div class="pswp__scroll-wrap">
|
||
<!-- Container that holds slides.
|
||
PhotoSwipe keeps only 3 of them in DOM to save memory.
|
||
Don't modify these 3 pswp__item elements, data is added later on. -->
|
||
<div class="pswp__container">
|
||
<div class="pswp__item"></div>
|
||
<div class="pswp__item"></div>
|
||
<div class="pswp__item"></div>
|
||
</div>
|
||
<!-- Default (PhotoSwipeUI_Default) interface on top of sliding area. Can be changed. -->
|
||
<div class="pswp__ui pswp__ui--hidden">
|
||
<div class="pswp__top-bar">
|
||
<!-- Controls are self-explanatory. Order can be changed. -->
|
||
<div class="pswp__counter"></div>
|
||
<button class="pswp__button pswp__button--close" title="Close (Esc)"></button>
|
||
<button class="pswp__button pswp__button--share" title="Share"></button>
|
||
<button class="pswp__button pswp__button--fs" title="Toggle fullscreen"></button>
|
||
<button class="pswp__button pswp__button--zoom" title="Zoom in/out"></button>
|
||
<!-- Preloader demo http://codepen.io/dimsemenov/pen/yyBWoR -->
|
||
<!-- element will get class pswp__preloader--active when preloader is running -->
|
||
<div class="pswp__preloader">
|
||
<div class="pswp__preloader__icn">
|
||
<div class="pswp__preloader__cut">
|
||
<div class="pswp__preloader__donut"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="pswp__share-modal pswp__share-modal--hidden pswp__single-tap">
|
||
<div class="pswp__share-tooltip"></div>
|
||
</div>
|
||
<button class="pswp__button pswp__button--arrow--left" title="Previous (arrow left)">
|
||
</button>
|
||
<button class="pswp__button pswp__button--arrow--right" title="Next (arrow right)">
|
||
</button>
|
||
<div class="pswp__caption">
|
||
<div class="pswp__caption__center"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!--jQuery must be loaded before you load init-pswp.js; If your template already loads jQuery in the header then you don't need to load it again here; if your template already loads jQuery in the footer, then you could load init-pswp.js there instead so you don't load jQuery twice (although as long as you're loading jQuery from the same source it doesn't matter if you load it twice) -->
|
||
<script src="https://code.jquery.com/jquery-1.12.4.min.js" integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
|
||
<script src="/js/pswp-init.js"></script>
|
||
```
|
||
Right at the end, we link to jQuery, and then a js and a css file. If you wanted to, you could put the js and css below in a `<script>` and a `<style>` tag so it’s all contained in the shortcode file, but I prefer to keep my js and css in separate files.
|
||
|
||
## The JavaScript
|
||
|
||
This script runs once the page is loaded, and does three things:
|
||
|
||
- [Create an array of slide objects](http://photoswipe.com/documentation/getting-started.html#dom-to-slide-objects) from all the figures on the page.
|
||
- If size wasn’t pre-defined, load the image to determine its size
|
||
- Binds click event to links/thumbnails to activate PhotoSwipe
|
||
|
||
Put this file in `/static/js/pswp-init.js`:
|
||
|
||
```js
|
||
$( document ).ready(function() {
|
||
var items = []; // array of slide objects that will be passed to PhotoSwipe()
|
||
// for every figure element on the page:
|
||
$('figure').each( function() {
|
||
// get properties from child a/img/figcaption elements,
|
||
var $figure = $(this),
|
||
$a = $figure.find('a'),
|
||
$src = $a.attr('href'),
|
||
$title = $figure.find('figcaption').html(),
|
||
$msrc = $figure.find('img').attr('src');
|
||
// if data-size on <a> tag is set, read it and create an item
|
||
if ($a.data('size')) {
|
||
var $size = $a.data('size').split('x');
|
||
var item = {
|
||
src : $src,
|
||
w : $size[0],
|
||
h : $size[1],
|
||
title : $title,
|
||
msrc : $msrc
|
||
};
|
||
// if not, set temp default size then load the image to check actual size
|
||
} else {
|
||
var item = {
|
||
src : $src,
|
||
w : 800, // temp default size
|
||
h : 600, // temp default size
|
||
title : $title,
|
||
msrc : $msrc
|
||
};
|
||
// load the image to check its dimensions
|
||
// update the item as soon as w and h are known (check every 30ms)
|
||
var img = new Image();
|
||
img.src = $src;
|
||
var wait = setInterval(function() {
|
||
var w = img.naturalWidth,
|
||
h = img.naturalHeight;
|
||
if (w && h) {
|
||
clearInterval(wait);
|
||
item.w = w;
|
||
item.h = h;
|
||
}
|
||
}, 30);
|
||
}
|
||
// Save the index of this image then add it to the array
|
||
var index = items.length;
|
||
items.push(item);
|
||
// Event handler for click on a figure
|
||
$figure.on('click', function(event) {
|
||
event.preventDefault(); // prevent the normal behaviour i.e. load the <a> hyperlink
|
||
// Get the PSWP element and initialise it with the desired options
|
||
var $pswp = $('.pswp')[0];
|
||
var options = {
|
||
index: index,
|
||
bgOpacity: 0.8,
|
||
showHideOpacity: true
|
||
}
|
||
new PhotoSwipe($pswp, PhotoSwipeUI_Default, items, options).init();
|
||
});
|
||
});
|
||
});
|
||
```
|
||
## Demo with individual images
|
||
|
||
With the `pswp-init` shortcode called, our image should now show a carousel when clicked:
|
||
|
||
`{{</* figure link="/img/homepage/cc_jeepers.jpg" thumb="-thumb" */>}}`:
|
||
|
||
{{< figure link="/img/homepage/cc_jeepers.jpg" thumb="-thumb" >}}
|
||
|
||
Note that the large image was already loaded - this is because we didn’t pre-define the image size, so the script had to load the image to check its size. If we pre-define the size, your browser won’t need to load it until you click on it (or any other image). We can also include a caption.
|
||
|
||
`{{</* figure link="/img/homepage/sydney-harbour.jpg" thumb="-thumb" size="1920x928" caption="Sydney Harbour" */>}}`:
|
||
|
||
{{< figure link="/img/homepage/sydney-harbour.jpg" thumb="-thumb" size="1920x928" caption="Sydney Harbour" >}}
|
||
|
||
If you refresh the page and then click on the image above, you’ll see it is pixellated for a litle while whilst it loads.
|
||
|
||
You could argue that it’s better to avoid pre-loading the images just to get their dimensions, but I’d argue it doesn’t really matter because PhotoSwipe pre-loads **all** of the images as soon as you activate it (i.e. the first time you click on an image).
|
||
|
||
## One last shortcode to make a gallery
|
||
|
||
But what if you **do** want a bunch of thumbnails all together in a box?
|
||
|
||
Don’t worry, we can do that too. Here’s the code:
|
||
|
||
Put this file in `/layouts/shortcodes/gallery.html`:
|
||
```html
|
||
<div class="gallery" itemscope itemtype="http://schema.org/ImageGallery">
|
||
{{ .Inner }}
|
||
<div class="title">{{ .Get "title" }}</div>
|
||
</div>
|
||
<link rel="stylesheet" href="/css/pswp-gallery.css" />
|
||
```
|
||
Put this file in ```/static/css/pswp-gallery.css```:
|
||
```css
|
||
.gallery {
|
||
float: none;
|
||
border: 1px solid lightgrey;
|
||
padding: 10px;
|
||
margin: 0px 0px 10px 10px;
|
||
}
|
||
.gallery .title{
|
||
text-align: center;
|
||
clear:left;
|
||
//border-top: 1px solid lightgrey;
|
||
}
|
||
.gallery img {
|
||
width: 100%;
|
||
height: auto;
|
||
}
|
||
.gallery figure {
|
||
display: block;
|
||
float: left;
|
||
margin: 0 5px 5px 0;
|
||
}
|
||
.gallery figcaption {
|
||
display: none;
|
||
}
|
||
figcaption {
|
||
font-size: 75%;
|
||
}
|
||
```
|
||
## Demo Gallery
|
||
Hugo shortcodes:
|
||
|
||
```
|
||
{{</* gallery title="Pictures from my Arduino post" */>}}
|
||
{{</* figure link="/img/arduino/garage-opener.jpg" thumb="-thumb" size="600x800" caption="Garage remote" */>}}
|
||
{{</* figure link="/img/arduino/garage-opener-inside.jpg" thumb="-thumb" size="800x600" caption="Garage remote showing EV1527 chipset" */>}}
|
||
{{</* figure link="/img/arduino/ms-front.jpg" thumb="-thumb" size="600x800" caption="RC mains switch - front" */>}}
|
||
{{</* figure link="/img/arduino/ms-rear.jpg" thumb="-thumb" size="600x800" caption="RC mains switch - back showing PowerTran model A0342" */>}}
|
||
{{</* figure link="/img/arduino/ms-remote.jpg" thumb="-thumb" size="600x800" caption="RC mains switch remote" */>}}
|
||
{{</* figure link="/img/arduino/ms-remote-inside.jpg" thumb="-thumb" size="600x800" caption="RC mains switch remote showing LX2262A-R4 chipset" */>}}
|
||
{{</* figure link="/img/arduino/lamp-setup.jpg" thumb="-thumb" size="600x800" caption="Test setup with lamp" */>}}
|
||
{{</* /gallery */>}}
|
||
```
|
||
Result:
|
||
|
||
{{< gallery title="Pictures from my Arduino post" >}}
|
||
{{< figure link="/img/arduino/garage-opener.jpg" thumb="-thumb" size="600x800" caption="Garage remote" >}}
|
||
{{< figure link="/img/arduino/garage-opener-inside.jpg" thumb="-thumb" size="800x600" caption="Garage remote showing EV1527 chipset" >}}
|
||
{{< figure link="/img/arduino/ms-front.jpg" thumb="-thumb" size="600x800" caption="RC mains switch - front" >}}
|
||
{{< figure link="/img/arduino/ms-rear.jpg" thumb="-thumb" size="600x800" caption="RC mains switch - back showing PowerTran model A0342" >}}
|
||
{{< figure link="/img/arduino/ms-remote.jpg" thumb="-thumb" size="600x800" caption="RC mains switch remote" >}}
|
||
{{< figure link="/img/arduino/ms-remote-inside.jpg" thumb="-thumb" size="600x800" caption="RC mains switch remote showing LX2262A-R4 chipset" >}}
|
||
{{< figure link="/img/arduino/lamp-setup.jpg" thumb="-thumb" size="600x800" caption="Test setup with lamp" >}}
|
||
{{< /gallery >}}
|
||
|
||
## Don't forget
|
||
to call `{{</* pswp-init */>}}` somewhere on the page!
|
||
|
||
## Credits
|
||
Thanks to [Tom Helmer](http://www.thehome.dk/article/photoswipe-gallery-hugo/) and [Thoriq Firdaus](https://webdesign.tutsplus.com/tutorials/the-perfect-lightbox-using-photoswipe-with-jquery--cms-23587) for their blog posts which helped me with this post.
|