This is a hugo module for a shortcode template carousel.html that shows one or multiple bootstrap 5 carousels in a single page.
The images for each carousel are pulled from single subdirectories inside your page bundle. The carousels can have the lightbox2 functionality (option can be set per-carousel).
The caption for the images in a subdirectory can be fetched from the images filename or from the EXIF metadata .ImageDescription. In this last case, you will need to fill the correponding EXIF field in the jpegs (for images whitout default EXIF metadata). This option to fetch from filename or from EXIF is a per-subdirectory option, not a per-file option.
Until future development, images should be manually resized to the desired format and EXIF metadata shuld be inserted in the images in a jpeg format, if you do not want to use the filename as the carousel caption. The carousel will work even if you do not resize the images, but the result will be a carousel that will expand and contract to fit the single image original size. This is needed because in my tests, the resize function in Hugo will remove the EXIF metadata.
An example of the result can be viewd at the page: https://studio.andrebonfanti.it/intelligenza-artificiale-generazione-render-da-schizzi/
I provide this code at the best of my knowledge of Hugo module usage, but you have to know the basics of Hugo module commands and configurations. The code itself is a simple shortcode template without harmful code, but the module integration and the conversion of your site to a Hugo module is up to you. I provide some guidance to convert your site and to import the module, but check first the Hugo Docs.
This shortcode module has a standard hugo tree structure:
. # root folder
├── ...
├── layouts # Layouts folder
│ ├── shortcodes # Shortcodes folder
│ ├── carousel.html # carousel code
└── ...
The module is tested against hugo v0.111.3+extended. I do not guarantee previous hugo versions.
You must have a Hugo theme based on Bootstrap, as the template uses the bootstrap theme code.
The code is tested against Boostrap v5.2. The code could work on previous Bootstrap version, but you should test it before. For example, the "ride" option do not have the "true" attribute in Bootstrap v5.0 according to the Bootstrap v.5.0 documentation.
Until future development to merge requirements inside this module, you must add jquery and lightbox javascripts/css in your templates or pages, or in your preferred location.
In your <head> tags, add lightbox2 css:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/lightbox2/2.11.1/css/lightbox.min.css" />
In your footer scripts, add the javascript tags:
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/lightbox2/2.11.1/js/lightbox.min.js"></script>
Or you can download the minified version of the scripts and put them in your asset/js folder, and link them inside your code.
Make sure the jquery script is loaded before the lightbox2 script.
You can skip this step if you already have Go and Git installed.
Hugo modules functionality require the installation of Go and Git on your local machine (see https://gohugo.io/hugo-modules/use-modules/). Refer to the link for installation before continuing.
You can skip this step if your site is already a hugo module.
Next, your site should be initialized as a hugo module. In the root of your site local folder:
hugo mod init {project}
Usually, project is the URL of your online site repository without https://. For example:
hugo mod init github.com/GITHUB-USER/MY-SITE
If you do not have your site pushed to a remote repository like Github, project can be a unique name. For example:
hugo mod init MY-CUSTOM-PROJECT-NAME
This creates two new files, go.mod for the module definitions and go.sum which holds the checksums for module verification. The go.mod file in your site root will contain now something like this:
module PROJECT
go 1.19
Where PROJECT is the name you gave with hugo mod init PROJECT command.
After you have initialized your site as a hugo module, to install this shortcode module, edit your config.yaml file to add the module import specifications (refer to https://gohugo.io/hugo-modules/configuration/ for more options). I am using the yaml format, but you are free to convert this in toml or json format.
module:
imports:
- path: github.com/abonfo/hugo-bootstrap-carousel-lightbox-shortcode
Then, you need to pull the imports defined in the config file. In the root folder of your site run:
hugo mod get
This command will:
- run all the imports defined in your config file;
- download this module;
- add a
requirerow in yourgo.modfile with the module URL.
This is the code for the production config file. If you need to test the module on development or staging environment, refer to https://gohugo.io/getting-started/configuration/#configuration-directory for setting different environments, and to https://gohugo.io/hugo-modules/configuration/#module-configuration-top-level to use the replacements option to edit the module locally without pushing the commits to your forked repo of the module.
To update this module to the last version:
hugo mod get -u github.com/abonfo/hugo-bootstrap-carousel-lightbox-shortcode
To update this module to a certain tag version, for example to v1.2.0:
hugo mod get -u github.com/abonfo/hugo-bootstrap-carousel-lightbox-shortcode@v1.2.0
For other oprions, refer to https://gohugo.io/commands/hugo_mod_get.
To use the shortcode, read the following instructions.
In the page you want to use the shortcode, create the subfolder/s to store your images, in the format slider-XX. The format must be slider-XX, as the slider- part is hardcoded in the template. For example:
. # page folder
├── ...
├── slider-01 # Image folder
├── slider-02 # Image folder
├── ...
├── slider-NN # Image folder
├── ...
├── index.md # Content file
└── ...
Put your images in the folders. Images should be resized before, as your needs for each carousel dimensions.
The carousel and the lightbox captions can be defined separately: from EXIF metadata or from the filename.
If you want to use the images filename as the carousel/lightbox caption, give the images a useful filename and set the FILENAME shortcode attribute (see below for the shortcode usage).
If you want to use the EXIF metadata as the carousel/lightbox caption, you must populate the image ImageDescription metadata tag, and set the EXIF shortcode attribute.
Insert this shortcode in your page content where you want the carousel to appear. Each slider folder must have its own shortcode.
{{< carousel
slider_num="XX"
ride=carousel
interval=7000
wrap=true
fade=true
controls=true
indicators=true
dark=false
caption_source=EXIF
lightbox=true
touch="false"
lb_caption_source=EXIF
>}}
Where the parameters are:
- slider_num (REQUIRED): the number of the folder from which the shortcode should fetch the images. Keep the value in the quotes.
- ride (REQUIRED): use "carousel" to enable autoplay on load; use "false" to disable autoplay; use "true" to autoplay the carousel after the user manually cycles the first item.
- interval (REQUIRED): is the delay time between automatically cycling to the next item, in milliseconds. Insert your desired time in ms (ex. 5000). Can be "false" to disable, but must be a number if ride is set to "carousel" or "true".
- wrap (REQUIRED): "true" or "false", to enable or disable the carousel cycling or have an hard stop at the end.
- fade (OPTIONAL): "true" or "false", to enable or disable the fading of the images. You can also omit the whole parameter, and in this case the carousel will default to standard transition.
- controls (OPTIONAL): "true" or "false", to enable or disable the left and right arrows. If the parameter is omitted, no arrows will be shown.
- indicators (OPTIONAL): "true" or "false", to enable or disable the bottom indicators. If the parameter is omitted, no indicators will be shown.
- dark (OPTIONAL): "true" or "false", to enable or disable dark controls, indicators, and captions. If the parameter is omitted, white theme colors will be used. You can override this behaviour by setting your colors in your custom css file.
- caption_source (OPTIONAL): "EXIF" to use the image description text inside the image EXIF metadata (it fetches the .ImageDescription tag); "FILENAME" to use the file name without the extension. If the parameter is omitted, no caption will be shown and no css class for the caption will be given.
- lightbox (OPTIONAL): "true" to apply lightbox functionality to a single canvas; "false" to not apply lightbox functionality to canvas. If the parameter is omitted, no lightbox functionality will be used (same as "false").
- touch (OPTIONAL): "false" disable the support for left/right swipe interactions on touchscreen devices; "true" enable it. If the parameter is omitted, the default swipe functionality will be used (same as "true"). Value must be quoted.
- lb_caption_source (OPTIONAL): this parameter sets the lightbox caption. Use "EXIF" to fetch the .ImageDescription image EXIF tag; use "FILENAME" to fetch the file name without the extension. If the parameter is omitted, the lightbox caption will default to show the current image number and the total number of images in the set. If the lightbox parameter is set to "false", this parameter has no effect.
This module is built using the same classes from the bootstrap carousel component (refer to https://getbootstrap.com/docs/5.2/components/carousel/).
The carousel caption is wrapped with the standard bootstrap carousel-caption class. Inside this class, the module implements a custom carousel-description class that wraps the text caption. These two classes are available only if the caption_source parameter is given.
- Add touch swiping bootstrap carousel option as shortcode parameter.
- Add wrap bootstrap carousel option as shortcode parameter.
- Add dark bootstrap carousel option as shortcode parameter.
- Add resize option parameter to dynamically set the image size (this can break EXIF metadata), or use other methods for scaling the images.
- Add shortcode parameter to fetch a specific EXIF field, or fallback to image filename
for non-jpeg images, or other source for captions. - Add parameter to fetch the lightbox caption: EXIF to fetch jpeg metadata or FILENAME to fetch the file name.
- Add parameters and conditional functions to show or hide the
controlsin the carousel. - Add parameters and conditional functions to show or hide the
indicatorsin the carousel. - Add option to disable lightbox functionality and use only the carousel functions.
- Remove hardcoded "slider-" prefix from image folders and let user define custom folder names.
This project is based on hugo documentation, tutorials, blogs and external scripts. Thanks to:
- Hugo Docs
- jQuery javascript library
- Lightbox2 javascript library
- Future Web Design
- The New Synamic - Hugo Module article
Distributed under the GNU General Public License v3.0. See LICENSE.txt for more information.