๐ผ Kirby Lightbox-Gallery by @wottpal
(Disclaimer: This is a pre-release.)
A plugin for the awesome Kirby CMS which allows the editor to easily inline beautiful galleries with lightbox-support.
- Dynamic & responsive Grid-Alignment
- Works with Kirby's built-in thumbnail class, ImageSet by @fabianmichael and Focus by @flokosiol
- Powered by PhotoSwipe by @dimsemenov
- Parses
title
&caption
image-fields directly into PhotoSwipe - Configurable & Customizable to it's core
๐ค
๐คนโ Demos
- wottpal.com (my personal site)
- Submit yours
๐คธ Installation
Because of the PhotoSwipe dependency multiple steps are necessary for a proper installation of the plugin. Also PHP 5.6+ is required. If you have any questions feel free to reach out or file an issue.
1. Install the plugin itself
Recommended: Use Kirby's CLI and install the plugin via: kirby plugin:install wottpal/kirby-lightbox-gallery
Oldschool: Download this repo and move the folder to site/plugins/
.
2. Download Photoswipe
Download PhotoSwipe (tested version 4.1.2) rename the dist
directory to photoswipe
and place it under assets/vendor/
.
Note: Additionally you should minify the two .css
files of PhotoSwipe which is weirdly not done by them. I love to use Squeezer for macOS for that. In the next section I'll assume that minified versions of these files exist.
3. Link Resources
Embed necessary styles within your <head>
:
<?= css([
'assets/plugins/lightbox-gallery/gallery.min.css',
'assets/vendor/photoswipe/photoswipe.min.css',
'assets/vendor/photoswipe/default-skin/default-skin.min.css'
]) ?>
Embed necessary scripts before the end of your </body>
:
<?= js([
'assets/vendor/photoswipe/photoswipe.min.js',
'assets/vendor/photoswipe/photoswipe-ui-default.min.js',
'assets/plugins/lightbox-gallery/init-photoswipe.min.js'
]) ?>
If you use the default initialization (init-photoswipe.min.js
) and want to support older browsers you may need to add polyfills for the forEach
and Array.from
functions.
Customization
Except the PhotoSwipe Base CSS & JS you can literally replace every dependency with your own code. A good start for this is to copy & paste the original dependency (e.g. 'site/plugins/lightbox-gallery/src_assets/init-photoswipe.js'
) into your own assets folder, do your modifications and change the asset-paths accordingly. But be aware that the plugin changes over time and you may have to keep your changes compatible.
๐ Usage Examples
(gallery: all) # Includes all images of the page
(gallery: 1.png 2.png 3.png) # Includes only selected images
(gallery: all page: projects/a) # Includes all images of the page with the given uri
(gallery: all limit: 2) # Only shows thumbs of the first two images
(gallery: all order: random) # Shuffles all images
(gallery: all order: reverse) # Displays all images in reverse order
(gallery: all cols: 2 4) # Sets cols to ['min' => 2, 'max' => 4]
(gallery: all cols: 3) # Sets cols to ['min' => 3, 'max' => 3]
(gallery: all mobilecols: 1 2) # Sets mobilecols to ['min' => 1, 'max' => 2]
(gallery: all stretch: last) # Stretch trailing items instead of first
(gallery: all stretch: none) # Disable stretching
(gallery: all class: my-class id: my-id) # Applied a class & id to the gallery-wrapper
Please see the following section for further description how the particular parameters work. Options set in a Kirbytag always overwrite global options.
๐คบ Options
The following options can be set globally in your config.php
with c::set($key, $value = null)
. You can also set multiple keys with c::set([$key => $value, ..])
.
lightboxgallery.kirbytext.tagname
(default:'gallery'
)
The name of the tag to use this gallery within kirbytext. Like (gallery: ...)
.
lightboxgallery.id
(default:''
)lightboxgallery.class
(default:''
)
Specify an ID or class which is added to the gallery-wrapper element. Use it for custom styling.
lightboxgallery.combine
(default:false
)
If set to true
all galleries on one page will be virtually the same. So you can navigate between all images in the same lightbox.
lightboxgallery.limit
(default:false
)
Maximum amount of previewed thumbnails to be shown.
Note: The hidden items are only visually hidden with CSS. By appending a data-not-previewed
attribute to the <figure>
elements.
lightboxgallery.cols
(default:['min' => 3, 'max' => 4]
)lightboxgallery.mobilecols
(default:['min' => 2, 'max' => 2]
)
Defines the range of possible columns the gallery can choose of. Within this range an algorithm
Note 1: The actual implementation is located under helpers.php
.
Note 2: The mobile-breakpoint and gutter-width are currently defined in src_assets/gallery.scss
. You can overwrite it by setting a lightboxgallery.class
and adding your own styles or completely substituting the plugins CSS with your own stylesheets.
lightboxgallery.stretch
(default:'first'
)
*If there are not enough images to fill all rows with as many items as columns by default the images in the first row are stretched to fill up the whole width. You can set this option to 'last'
to stretch all trailing items instead or set it to 'none'
to disable stretching at all.
lightboxgallery.thumb.provider
(default:'thumb'
)
Choose from one of the following providers for thumb-creation:
'thumb'
(Kirby's built-in thumbnail class)'focus'
(Kirby-Focus by @flokosiol)'imageset'
(ImageSet)false
(just use the image as thumb)
Note: Because thumbnail-creation for a whole gallery may take some time and you don't want the first visitor of your site to suffer I recommend you to have a look into ImageKit.
lightboxgallery.thumb.options
(default:["width" => 800, "height" => 800, "crop" => true]
)
Define the options for the selected thumb.provider
. Works exactly the same way as you would use the options with their respective functions. If you set the thumb.provider
to something else than 'thumb'
or false
you must set this option.
Note 1: The default-value is crops 800x800 thumbnails with Kirby's built-in thumbnail class.
Note 2: If you use focus
put all values in an array. So for example if you set it to [300,300]
the plugin will call focusCrop(300,300)
.
Note 3: If you use imageset
you set this option to something like ['400x400-1000x1000, 4']
to generate responsive square images. (You should specify sizes
as well).
๐ Changelog
Have a look at the releases page.
๐๏ธ Roadmap
Contributions welcome
- Possibility to define thumb-sizes for the Non-ImageSet version
- Option to move stretched row to the end (only if
count % col != 0
) - Option to not stretch row and keep the same column-count (only if
count % col != 0
). - Allow cols/mobilecols to be set in the kirbytag
- Think more about non-square images
- Dynamic thumb-options based on column-count
- Define responsive image-sources for PhotoSwipe
- Option to disable lightbox usage
- Enable use of History-API of PhotoSwipe in init-photoswipe.js
- Maybe a new breakpoint-based API for defining min/max cols like
- Support for videos (esp.
webM
withmp4
andgif
fallbacks)
๐จโ๐ป Development
For minification and transpilation I use Gulp. Please note that all files under assets/
are only the generated ones from src_assets/
.
# Install Dependencies
npm i
# Or: Install Dependencies for Hipsters
yarn
# Build & Watch (Install 'gulp-cli' globally to omit the 'npx')
npx gulp
๐ฐโ Pricing
Just kidding. This plugin is totally free. Please consider following me on Twitter if it saved your day.
You can also check out one of my other Kirby-plugins:
- HTML5-Video Kirbytag - Adds a kirbytag for embedding HTML5-videos with a variety of features.
- Anchor-Headings - A kirby field-method which enumerates heading-elements, generates IDs for anchor-links and inserts custom markup based on your needs.