Lightbox Gallery Documentation

How to use Lightbox Gallery on your site

Found an issue or a problem that you can't find an answer for? Create an issue in our Premium Issue Tracker.

Before you start

Before you can install a Premium Plugin, you are required to have the License Manager plugin installed. It is a free plugin available in GPM and can be installed like any other through the Plugin section of the admin plugin, or via command line.

$ bin/gpm install license-manager

Installation

First ensure you are running the latest version of Grav 1.6 or Grav 1.7 (-f forces a refresh of the GPM index).

$ bin/gpm selfupgrade -f

The Lightbox Gallery requires the shortcode-core plugin as a dependency, even though the shortcode syntax is optional. These are available via GPM, and because the plugin has dependencies you just need to proceed and install the Lightbox Gallery plugin, and confirm when prompted to install the others:

$ bin/gpm install lightbox-gallery

You can also install the plugin via the Plugins section in the admin plugin.

Configuration

The simplest way to configure the plugin is via the Admin by navigating to Plugins then clicking on the Lightbox Gallery plugin entry. The available options are:

General Configuration

General Configuration

  • Plugin status → Will enable or disable the entire plugin.

  • Always Active → When disabled, you can decide when to enable Lightbox Gallery per Page. To enable in a page, set lightbox: active: true in the frontmatter.

  • Always Include Assets → When disabled, you will be responsible for including the CSS and JS files from the twig templates. By default this happens from the plugin class.

Appearance & Effects

Appearance & Effects

  • Selector → Name of the CSS selector for Lightbox Gallery to search for in the page. It can be comma separated and supports any valid CSS selector. By default this is [rel="lightbox"], .glightbox.

  • Skin → Name of the skin, it will add a class to the lightbox so you can style it with css. By default there is only one skin available named clean.

  • Open Effect → Type of effect when opening Lightbox Gallery. Can be Zoom (default), Fade or None.

  • Close Effect → Type of effect when closing Lightbox Gallery. Can be Zoom (default), Fade or None.

  • Slide Effect → Type of effect when sliding between slides. Can be Slide (default), Fade, Zoom or None.

  • More Text → Text to display on mobile for lengthy descriptions.

  • More Length → Number of characters to display on the description before adding the More Text link (only for mobiles). If set to 0 it will display the entire description.

Actions

Actions

  • Close Button → Will show or hide the close button.

  • Touch Navigation → Will enable or disable the touch navigation (swipe).

  • Touch Follow Axis → Image follows the axis when dragging on mobile.

  • Keyboard Navigation → Will enable or disable the keyboard navigation.

  • Close with Outside Click → Closes Lightbox Gallery when clicking outside of an active slide.

  • Start At → Starts Lightbox Gallery at the defined index. Note that the numbering is zero based (Slide 1 is 0, Slide 2 is 1, etc).

Styling

Styling

  • Width → Default width for inline elements and iframes, you can define a specific size for each slide. You can also use any valid unit (90%, 100vw for full width).

  • Height → Default height for inline elements and iframes, you can define a specific size for each slide. You can also use any valid unit for (90%, 100vh for full height).

    For inline elements you can set the height to auto.

  • Videos Width → Default width for videos. The width can be in any valid unit (ie, 500px, 90%, 100vw for full width videos).

    Videos are responsive which makes having a height setting unnecessary.

  • Description Position → Global position of the slides' description. You can also specify a different position for each slide. Available positions are Bottom (default), Top, Left, Right.

Behaviors

Behaviors

  • Loop → Will enable or disable Infinite sliding. Reaching the last slide will make it start over.

  • Zoomable → Will enable or disable the zoom behavior on images.

  • Draggable → Will enable or disable the mouse drag-n-drop behavior for moving between slides. Only images and inline content are supported.

  • Drag Tolerance X → When *Draggable is enabled, it defines the number of pixels the user has to drag before moving to the previous or next slide.

  • Drag Tolerance Y → When *Draggable is enabled, it defines the number of pixels the user has to drag up or down before the Lightbox Gallery closes.

    Set to 0 for disabling the vertical drag behavior.

  • Drag Auto-Snap → Enable or disable automatically changing slides to previous and next, or close Lightbox Gallery, when Drag Tolerance X or Drag Tolerance Y have been reached. When disabled, it will wait until the mouse click has been released.

  • Preload → When enabled it will preload the previous and next slides.

  • Autoplay Videos → Will enable or disable autoplaying videos when the slide containing them becomes active.

  • Autofocus Videos → When enabled, the videos will be on focused to allow for the keyboard shortcuts of the player to function.

    This setting enabled will disable the keyboard shortcuts behavior for the previous and next arrows. You will still be able to click the arrows to change slide.

Usage

Standard Lightbox Mode

Grav Media handling supports a simple way of providing a lightbox with a pure markdown solution. This does not provide a lot of options, rather it's just a quick way to show a thumbnail and popup a lightbox on clicking the thumbnail.

![Sample Image](blue-superleggera.jpg?lightbox=1024,768&resize=200,200)

Basic Lightbox with Shortcode

If you need more powerful flexibility you can make use of the [lightbox] shortcode (shorcode-core plugin required). This exposes all the options at runtime and specific to this lightbox instance.

Shortcode attributes supported are:

  • image → target image
  • class → classes that will be applied to the lightbox link (already includes .lightbox-gallery)
  • gallery → a gallery name
  • title → title of the image
  • desc → either a textual description or a class reference to an HTML element with the same class
  • descPosition → position of description (top, bottom, left, right)
  • type → media type, either image or video
  • effect → opening/close effect
  • width → thumbnail width
  • height → thumbnail height
  • zoomable → true or false
  • draggable → true or false
[lightbox image="white-vantage-v12.jpg" zoomable="false" draggable="false"]
![White V12 Vantage](white-vantage-v12.jpg?cropZoom=200,200)
[/lightbox-gallery]

Gallery Lightbox with Shortcodes

A more advanced use of this plugin involves using several [lightbox] shortcode entries with a common gallery="" attribute to link them together. This example even uses a custom class in the desc="" attribute. These classes are defined in [div] shortcodes below to temporarily provide a location for complex rich-text descriptions. The plugin will then extract these descriptions from the page, and make them available alongside the image in the ligthbox. Alternatively, you can put a simple text description in the desc="" attribute.

[lightbox image="red-dbs-1.jpg" gallery="gallery1" class="inline-block" desc=".dbs-1"]
    ![Red DBS - 1](red-dbs-1.jpg?cropZoom=200,200)
[/lightbox-gallery]

[lightbox image="red-dbs-2.jpg" gallery="gallery1" class="inline-block" desc=".dbs-2"]
    ![Red DBS - 2](red-dbs-2.jpg?cropZoom=200,200)
[/lightbox-gallery]

[lightbox image="red-dbs-3.jpg" gallery="gallery1" class="inline-block" desc=".dbs-3"]
    ![Red DBS - 3](red-dbs-3.jpg?cropZoom=200,200)
[/lightbox-gallery]

[lightbox image="red-dbs-4.jpg" gallery="gallery1" class="inline-block" desc=".dbs-4"]
    ![Red DBS - 4](red-dbs-2.jpg?cropZoom=200,200)
[/lightbox-gallery]

[div class="glightbox-desc dbs-1"]
    [div class="prose"]
        ### Aston Martin DBS 1

        [div class="text-lg"]
            Morbi ac interdum velit. Ut sed purus in **erat feugiat mollis**. In porta ligula quis vulputate ullamcorper. 
        [/div]

        Aenean eu condimentum odio. Aliquam ac justo eget libero ullamcorper vehicula. Ut aliquet massa at sapien pellentesqu, in bibendum ligula vulputate. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum vestibulum sollicitudin. Sed vitae sodales neque. Donec placerat massa non suscipit accumsan.
    [/div]
[/div]

[div class="glightbox-desc dbs-2"]
    [div class="prose"]
        ### Aston Martin DBS 2

        [div class="text-lg"]
            Morbi ac interdum velit. Ut sed purus in **erat feugiat mollis**. In porta ligula quis vulputate ullamcorper. 
        [/div]

        Aenean eu condimentum odio. Aliquam ac justo eget libero ullamcorper vehicula. Ut aliquet massa at sapien pellentesque, in bibendum ligula vulputate. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum vestibulum sollicitudin. Sed vitae sodales neque. Donec placerat massa non suscipit accumsan.
    [/div]
[/div]

[div class="glightbox-desc dbs-3"]
    [div class="prose"]
        ### Aston Martin DBS 3

        [div class="text-lg"]
            Morbi ac interdum velit. Ut sed purus in **erat feugiat mollis**. In porta ligula quis vulputate ullamcorper. 
        [/div]

        Aenean eu condimentum odio. Aliquam ac justo eget libero ullamcorper vehicula. Ut aliquet massa at sapien pellentesque, in bibendum ligula vulputate. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum vestibulum sollicitudin. Sed vitae sodales neque. Donec placerat massa non suscipit accumsan.
    [/div]
[/div]

[div class="glightbox-desc dbs-4"]
    [div class="prose"]
        ### Aston Martin DBS 4

        [div class="text-lg"]
            Morbi ac interdum velit. Ut sed purus in **erat feugiat mollis**. In porta ligula quis vulputate ullamcorper. 
        [/div]

        Aenean eu condimentum odio. Aliquam ac justo eget libero ullamcorper vehicula. Ut aliquet massa at sapien pellentesque, in bibendum ligula vulputate. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum vestibulum sollicitudin. Sed vitae sodales neque. Donec placerat massa non suscipit accumsan.
    [/div]
[/div]

Twig Template

You can use the provided partials/lightbox-gallery.html.twig template in your existing Twig templates. This template can accept the same twig variables as the shortcodes.

The [div class="prose"] ... [/div] shortcode is to provide automatic CSS styling via Twig's .prose class.

Including your own assets

If you disable the auto-inclusion of assets (Always Include Assets), then you should include the assets via Twig on the pages where you need it with the following command.

{% do lightbox_gallery.addAssets() %}

Credits

This plugin is built on top of the amazing GLightbox library by biati digital