An algorithm for a perfectly balanced Gallery for Kirby CMS
See it live:
https://sitemarina.github.io/guggenheim/
Screenshot:
Guggenheim is a plugin for Kirby CMS which generates beautiful galleries through an algorithm for a perfectly balanced layout, which you might know from the awesome image grids at medium.com
Read more into the math and science behind the algorithm here: The algorithm for a perfectly balanced photo gallery
In my search for the perfect gallery, which could do this linear partition against the images, I really wasen't getting excited about all the countless client-side javascript solutions to the problem. As I care deeply about mobile, i simply didn't wanted to make the devices responsible for this task and wanted a PHP solution for the linear partition.
Buy a Single Domain License here https://sitemarina.github.io/guggenheim/ - I am currently struggling pretty bad 😥
Pre-launch Option
- I'll send you the plugin as a regular ol' .zip file to the email provided at purchase.
- If you for some reason don't like it, send me an email me for an refund.
- I'm working on an easier way to ship updates through Git - I'll send you an email when it's ready.
Grab yourself a copy of Kirby - an awesome performant CMS
- Copy the guggenheim folder into site/plugins
As Guggenheim now ships with PhotoSwipe, there’s two ways to get up and running with Guggenheim and PhotoSwipe.
If you’re using the Kirby Cachebuster Plugin or your sever policy doesn’t allow loading assets from the plugin folder, you might want to fallback using the next and more preferred setup method and link up the sources in your own main assets/ folder.
The easy ‘out of the box’ way: If you’re in a hurry, prototyping or just quickly want to test out Guggenheim with PhotoSwipe, the easiest way is to just put this in your head
<?= css('assets/plugins/guggenheim/css/guggenheim-photoswipe.min.css') ?>and this in your footer
<?= photoswipe() ?>
<?= js('assets/plugins/guggenheim/js/guggenheim-photoswipe.min.js', true) ?>off you go, you’re now all setup to use Guggenheim with PhotoSwipe.
The best way: To preserve your total hackable and artistic freedom, the preferred and best way is still that you manually implement the stuff from guggenheim/src into your specific design or fronted framework in your assets/ folder. And maybe only outputs the PhotoSwipe DOM in your footer, like so
<?= photoswipe() ?>Dependency order
- PhotoSwipe DOM found in guggenheim/snippets/photoswipe-dom.php and documented here
photoswipe.cssdefault-skin.css(and its image dependencies)photoswipe.min.jsphotoswipe-ui-default.min.js
Guggenheim
guggenheim.cssguggenheim-photoswipe.min.js(you can leave PhotoSwipe and this binding out entirely, if you just want to use Guggenheim on its own)
in your site/config/config.php
// Add aditional classes to the guggenheim gallery element
c::set('guggenheim.classes', 'gallery zoom margin-center');
// Guggenheim is meant to be used with PhotoSwipe
// But if you for some reason don't want to use it, you can remove it additionals with
c::set('guggenheim.photoswipe', false);
// Guggenheim uses some basic srcset and sizes for basic responsiveness and highres support
// if you want to disable it, and make your own
c::set('guggenheim.srcset', false);
// Guggenheim adds a kirbytext tag, the default is 'gallery', but you can change it with
c::set('guggenheim.kirbytext.tagname', 'guggenheim');Super simplistic -Generate a Guggenheim gallery with all the page images
(gallery:) or (gallery: all)More generally, you want to pick out the pictures to make the gallery from, you do it like this
Comma separated:
(gallery: image-1.jpg, image-2.jpg, image-3.jpg)
Pipe separated:
(gallery: image-1.jpg | image-2.jpg | image-3.jpg)
..heck even both:
(gallery: image-1.jpg | image-2.jpg, image-3.jpg)Options
Guggenheim lets you set some options for each gallery.
- width (Default is 800px) Which is the width of the gallery, all image will be resized through a linear partition to fit this width, and it will also be the max-width of the gallery (to prevent upscaling).
- height (Default is floor(width/3.5)) This is a ideal hight for images to fit too, it'll only be used as a guideline for the linear partition to maximum fit into, it's there for you to play around with for each specifik gallery
- border (Default is 4px) Sets the space between images in pixels
- max-width (Default is width) With this you can overwrite the max-width of the gallary a regular number is in pixels, but you can also do
max-width: 100%- but do note that the images will still be resized according to the width option, so here you have the power to really screw things up for bigger screensizes if you aren't aware and doesn't overwrites the default srcset and sizes guggenheim ships with - class With this you can add additional classes on a per gallery level
(gallery: image-1.jpg, image-2.jpg, image-3.jpg width: 800 height: 350 border: 10 class: mycustomclass)Use the Guggenheim gallery in your templates
$images = $page->images()->sortBy('sort', 'asc');
echo guggenheim($images, array('width' => 800, 'height' => 350, 'border' => 10));- Perfectly Balanced Gallery generated by a linear partition algorithm server-side, to preventing the usual overhead that JavaScript brings in terms of browser paint, reflows, grid calculations and DOM manipulations.
- If a 'caption' field is present for the image, it'll be added as a visually hidden figcaption, visible when opened in PhotoSwipe.
- Fixes an important issue when PHP locale was set to a locale which uses comma as a decimal separator - floats that was outputted in the inline styles got screwed, as decimal separators in CSS has to be periods.
- Ships with PhotoSwipe 4.0.1 and especially the PhotoSwipe DOM which you now easily can either manually copy from the guggenheim/snippets/photoswipe-dom.php or simply include it in your footer with
<?= photoswipe() ?>
- Only output figcaptions if a ‘caption' field is present and filled for the image
- Add a option for setting the max-width of the gallery like (gallery: all width: 1200 max-width: 100%)
- Add the option for adding per gallery classes like (gallery: all class: customclass anotherclass)