🖼 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&captionimage-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-wrapperPlease 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.
webMwithmp4andgiffallbacks)
👨💻 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent