Download

Introducing Publii's New Gallery Plugins: A Better Way to Manage Image Galleries

Bob Mitro Bob Mitro
Published in: Releases

We are pleased to announce the release of the Core Lightbox Gallery and Simple Lightbox Gallery plugins, which introduce a new and improved way to manage and display image galleries in Publii. Below, we explain why gallery functionality is separated from themes and how this change benefits our users.

Please note: This change is optional and not obligatory. Your theme's built-in gallery functionality will continue to work as it has in the past. However, if you want to use the new gallery plugins, you must update your theme or apply the changes described later in this article to your custom theme.

The Need for Change: Moving Beyond Built-in Galleries

Until now, galleries were built-in and managed directly within themes using PhotoSwipe v4. While this solution served its purpose for a long time, it had begun to show its age. Though reliable, PhotoSwipe v4 lacked many modern features, performance improvements, and customization options that newer libraries provide. As a result, many users expressed interest in upgrading to the latest version of PhotoSwipe or integrating alternative gallery libraries to meet their needs better.

Another significant limitation was the built-in gallery's lack of flexibility. Each theme was restricted to the same gallery implementation, leaving no room for switching to alternatives or introducing customizations beyond the default settings. This was a frustrating constraint for users who wanted more control or unique site functionality.

Maintaining the built-in gallery also became increasingly challenging. Updating the gallery code required simultaneous updates to all themes, a process that was not only time-consuming but also inefficient. This approach tied gallery improvements to theme updates, often leading to delays in delivering new features and optimizations to users.

To address these challenges, we decided to move the gallery functionality out of themes and into plugins. By decoupling galleries from themes, we can now provide users with multiple options for gallery libraries, each tailored to specific needs and preferences. This shift eliminates the reliance on theme updates for gallery improvements and ensures that new features and fixes can be delivered more quickly and efficiently.

Introducing Gallery Plugins

To kick off this new approach, we’ve introduced two plugins:

  • Core Lightbox Gallery: Powered by the latest version of PhotoSwipe (v5), this plugin offers modern features, including dynamic zoom controls, smooth animations, and advanced customization options. It's designed to deliver a sleek and high-performance gallery experience. A detailed description of its capabilities can be found on its marketplace page.

  • Simple Lightbox Gallery: Based on VenoBox 2, this plugin is perfect for users who value simplicity and elegance. It includes essential features like touch swipe navigation, keyboard accessibility, and customizable preloader animations, all in a lightweight package. Visit its marketplace page for more details and features.

The Benefits of Plugin-Based Galleries

By transitioning to a plugin-based model, we’ve created a more versatile and efficient solution for managing image galleries. Users now have the freedom to choose the gallery experience that best suits their site, whether they prefer the modern capabilities of Core Lightbox Gallery or the streamlined simplicity of Simple Lightbox Gallery.

With this approach, gallery plugins can deliver cutting-edge features without being tied to theme updates. This means faster feature releases, reduced maintenance overhead, and a cleaner, more efficient setup for both themes and plugins. It’s a win-win for users: improved performance, greater flexibility, and access to the best tools for managing and displaying image galleries.

This modular approach also opens the door for introducing additional gallery plugins in the future, offering users even more options to suit their needs.

Summing Up:

  • Improved Performance: Both plugins load assets dynamically, reducing unnecessary resource usage on pages without galleries.
  • Futureproofing: The plugins can be independently updated with the latest features, ensuring your galleries stay modern.
  • Customization: By separating galleries into plugins, you gain greater control over their appearance and behavior.
  • Cleaner Themes: Themes no longer include gallery-related assets or code, making them more lightweight and focused.
  • More Options in the Future: This modular approach paves the way for introducing additional gallery plugins, offering users even more variety and innovative features over time.

Upgrading to Gallery Plugins

To fully take advantage of the new gallery plugins, updating your themes to the latest versions is essential, released on December 10, 2024. These updates ensure seamless integration with the plugins.

In most cases, these will be versions 2.1.0.0 or 3.1.0.0.

Please note: If you prefer not to update your theme, its built-in gallery functionality will continue to work as it has in the past. However, if you want to use the new plugins but choose not to update your theme or are using a custom theme, you must make the manual adjustments described below.

Steps to Enable Gallery Plugins for Custom or Old Themes

Locate and remove the code responsible for loading the built-in gallery in the following theme files: /partials/head.hbs and /partials/footer.hbs This includes the main gallery initialization code and any conditional logic tied to gallery styles or assets.

Locate the head.hbs file (/Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME/ ) in your theme or its override and remove blocks of code like the examples below: 

{{#is "post"}}
   {{#post}}
      {{#if hasGallery}}
         <link rel="stylesheet" href="{{css "photoswipe.css" }}">
      {{/if}}
   {{/post}}
{{/is}}
{{#checkIf @config.custom.frontSource '==' "post"}}
   {{#checkIf @config.custom.frontGallery '==' true}}
      {{#is "index"}}
         <link rel="stylesheet" href="{{css "photoswipe.css" }}">
      {{/is}}
   {{/checkIf}}
{{/checkIf}}

In older theme versions, also remove code related to inline styles for PhotoSwipe icons: 

{{#is "post"}}
   {{#post}}
      {{#if hasGallery}}
         <style>
            {{#checkIf @config.custom.galleryLightboxStyle '==' "pswp--dark"}}
               .pswp--svg .pswp__button,
               .pswp--svg .pswp__button--arrow--left:before,
               .pswp--svg .pswp__button--arrow--right:before {
                  background-image: url({{@website.assetsUrl}}/svg/gallery-icons-light.svg);
               }
            {{else}}
               .pswp--svg .pswp__button,
               .pswp--svg .pswp__button--arrow--left:before,
               .pswp--svg .pswp__button--arrow--right:before {
                  background-image: url({{@website.assetsUrl}}/svg/gallery-icons-dark.svg);
               }
            {{/checkIf}}
         </style>
      {{/if}}
   {{/post}}
{{/is}}
{{#checkIf @config.custom.frontSource '==' "post"}}
   {{#checkIf @config.custom.frontGallery '==' true}}
      {{#is "index"}}
         <style>
            {{#checkIf @config.custom.galleryLightboxStyle '==' "pswp--dark"}}
               .pswp--svg .pswp__button,
               .pswp--svg .pswp__button--arrow--left:before,
               .pswp--svg .pswp__button--arrow--right:before {
                  background-image: url({{@website.assetsUrl}}/svg/gallery-icons-light.svg);
               }
            {{else}}
               .pswp--svg .pswp__button,
               .pswp--svg .pswp__button--arrow--left:before,
               .pswp--svg .pswp__button--arrow--right:before {
                  background-image: url({{@website.assetsUrl}}/svg/gallery-icons-dark.svg);
               }
            {{/checkIf}}
         </style>
      {{/is}}
   {{/checkIf}}
{{/checkIf}}

Next, locate the footer.hbs file and remove the following pieces of code:

{{#checkIfAny post.hasGallery page.hasGallery}}
    {{> photoswipe}}
{{/checkIfAny}}

{{#checkIf @config.custom.frontSource '==' "post"}}
   {{#checkIf @config.custom.frontGallery '==' true}}
      {{#is "index"}}
          {{> photoswipe}}
      {{/is}}
   {{/checkIf}}
{{/checkIf}}

For older implementations: 

{{#is "post"}}
   {{#post}}
      {{#if hasGallery}}
          {{> photoswipe}}
      {{/if}}
   {{/post}}
{{/is}}

{{#checkIf @config.custom.frontSource '==' "post"}}
   {{#checkIf @config.custom.frontGallery '==' true}}
      {{#is "index"}}
          {{> photoswipe}}
      {{/is}}
   {{/checkIf}}
{{/checkIf}}

You can also remove unused assets, such as CSS, JS, or SVG icons related to the built-in gallery and the /partials/photoswipe.hbs file.

That's it.

Final Thoughts

The shift to plugin-based galleries represents a significant milestone for Publii. Whether you opt for the advanced Core Lightbox Gallery or the elegant Simple Lightbox Gallery, you can look forward to a modern, customizable, and seamless gallery experience.

If you have any questions or need help transitioning your galleries, please don’t hesitate to contact our support team via the community forum.

What are you waiting for?

Start building your site today.

  1. 1 Download Publii
  2. 2 Write your content
  3. 3 Publish your site
Create website