Introduction
This is the second in the series on creating an image gallery using the Grav CMS. In this part of the tutorial I will cover creating the theme and gallery page.The gallery in this tutorial uses a central image store. I will not cover the styling or layout of the gallery. For the introduction and to understand the different types of gallery please look at part 1. The first few steps are covered in the Grav Documentation so I will not cover in detail.
The files for this tutorial are on a GitHub Gist and the theme created will be in a public GitHub repository.
Requirements
I will assume that you have an understanding web development.
Before starting this tutorial you need to have the following requirements.
- A development web server with PHP installed and configured
- Latest version Grav installed (with admin plug-in)
- Basic understanding of Grav
- Read the Grav theme documentation
- Basic understanding of Twig, PHP, YAML and Markdown
- A good text editor
Whenever developing you should have a version control system (e.g. Git) set-up.
Install DevTools Plug-in
To make creating our theme easier we will use the DevTools plug-in. It will not be required for live (production) sites that use the theme.
Open a command prompt (terminal) in the folder where you have Grav installed.
bin/gpm install devtools
If you get an error you may need to use:
php bin/gpm install devtools
Create custom theme
We are going to create a new custom theme called gallery-theme. In a terminal type following command.
bin/plugin devtools new-theme
You will now get presented with a series of questions.
Enter Theme Name: Gallery theme
Enter Theme Description: Gallery theme with central image storage
Enter Developer Name: ****
Enter GitHub ID (can be blank): ****
Enter Developer Email: *****
Please choose an option
[pure-blank ] Basic Theme using Pure.css
[inheritance] Inherit from another theme
[copy ] Copy another theme
> pure-blank
SUCCESS theme Gallery Theme -> Created Successfully
Path: ****
Now you have a usable theme structure to start making your gallery theme. In this example I have chosen to use the pure-blank option as it includes all the basic structure required and some simple styling.
Create a theme settings page
We now need to configure the theme settings form. The theme settings form allows site administrators to configure gallery folder. Grav uses a YAML file called blueprints.yaml to define this form.
The blueprints.yaml file needs to be in your new theme folder. It should have been created in the previous step. If it isn't there you can copy one from and an existing theme and edit the details.
Open the blueprints.yaml file in you chosen editor. First check the information matches the details you entered when creating the theme.
Now add the following lines to the end of the file and save.
These lines define the theme configuration form. The form: defines the form array. The form array has it's own properties e.g. validation. It also contains the fields array that contains the controls on the configuration form.
Switch to new theme
To develop the theme you will first need to enable it. Using Admin plug-in you can log into your Grav site and select the themes page. Click on the activate button under the new gallery-theme you have created. You should now see something like the image below.
Once your theme is activated you can click on it to configure the settings. You should see the new fields that you added previously. Check that the image folder field is set to /images.
Make a test page
To work on the theme we need a test page and some images to test that the gallery works.
Create a test page user/pages/03.gallery/gallery.md.
---
title: Gallery
gallery:
- image1.jpg
- image2.jpg
- image3.jpg
- image4.jpg
---
Any text you want on you gallery page above the images.
The 3 dashes define the YAML section (sometimes called front matter) of the Markdown file.
The first YAML line defines the page title.
The gallery: line defines the gallery collection. This is the collection that contains the image file names to use in your gallery.
Notice that the image file names are indented and have "- " before the file name. It is very important in YAML as it defines the items in a collection. If you are unsure of the syntax see the YAML website.
It is important to use web safe file names for all you files. You should also make sure they have the correct case as many web server file systems are case sensitive. I recommend using lowercase letters, numbers and dashes only.
Add images
Create a new folder in user/pages called images.
Now add a selection of images to the user/pages/images folder. Make sure the selection of images includes those listed in the gallery page.
When Grav loads a media file it automatically loads a metadata file from the same location. Therefore if you load images/image1.jpg Grav will also load images/image1.jpg.meta.yaml. The YAML file contains any metadata associated with the image. For this tutorial we just need a title and alt text.
Each image should have an associated metadata file with the following structure:
alt_text: Image description
title: Image title
Make the gallery template
We are finally ready to create the templates to display images in a gallery.
Make a copy the default.html.twig template file from your theme and call it gallery.html.twig.
Under the {{ page.content }} add:
{% include 'partials/gallery-block.html.twig' %}
You should now have
The first line tells Grav that this template extends the base.html.twig template. The base.html.twig template provides the basic html structure of your page.
The remaining lines override the structure content block defined in the base template.
The line {{ page.content }} shows the page contents. It will allow us to have a gallery description above the gallery.
The new {% include 'partials/gallery-block.html.twig' %} line includes (loads) a new partial template file. This new 'partial' template does the real work of displaying the images. This is done to make the system more modular. It also allows gallery blocks to be added easily to other page types e.g. a galleries page.
Create gallery-block.html.twig template
We now need to make the new partial template.
In the partials/ folder create a new file called gallery-block.html.twig. As mentioned before this new template will do the main work.
Add the following to your new file and save.
The first line sets a Twig variable to the images folder. It searches for the folder using either value set in the page header or the theme settings. We are using the header_var() and theme_var() functions to get the values. This is the method used in the supplied Quark theme. If the image_folder variable is not defined in the page header it uses the value from the theme settings.
Next we have the HTML div that is used to contain the gallery and help with the styling.
We now get to the main Twig loop that gets and displays the images. The for loop iterates through all the images listed in gallery variable in the page YAML front matter. The loop gets the file name not the image.
The {% set image=imagesfolder.media[image_name.image] %} line finds the media file with the specified name. It uses the imagesfolder variable created earlier to find the media with the selected file name. It then sets a Twig variable called image to the image file.
To display the image we are using the HTML figure element to gives us a semantic container for displaying an image with a caption.
We now need to display the image. For accessibility and search engine optimisation (SEO) you should have an image title and alt description for every image. To do this we need to access the image metadata. To access the image metadata use the image.meta object.
The
{{ image.cropResize(310,200).html( image.meta.title ,image.meta.alt_text) }} line displays the image. This uses two Grav Twig functions to handle the image and then display it. To make it easier to understand I will break it down to its components.
First it uses .cropResize(310,200) to crop /resize the image to 310px wide by 200px high. There are many other image processing functions that can be used. They can be used in combination to the the required effect. They are listed in the theme documentation.
The next part is .html( image.meta.title ,image.meta.alt_text) that is used to output the html for the cropped image.
The next section used a Twig if condition to display the image title in a figcaption if we have an image title defined.
Test the theme
You now have a theme, test page and test images. Now you need to test your site. Load your gallery test page.
The gallery page doesn't have any specific styling. You should see a page with to correct title, gallery description and only the specified images in the correct order e.g.
Summary
What you have created in this tutorial is a basic and unstyled gallery. A typical gallery page will have the pictures arranged in a grid. Many galleries use a 'lightbox' script to display a lager version of an image when clicked. All these features can be added as required.
Gallery websites sometime have a galleries page that shows a list of galleries on the site. Using the central image storage a galleries page can be easily added. It also allows you to create a slide show of featured images from all gallery pages.
As I mentioned at the start I the theme created is hosted on GitHub.
I have used a variation of this theme on the Photography on Wheels website.