Building A Simple Image Gallery In Statamic

Creating The Fieldset

Depending on how you are going to set your gallery up will depend on the best way to set your fieldset up. This post will take you through setting up a one page gallery. In a follow up post I'll cover how to create a gallery listing where you could have multiple galleries set up.

One Page Gallery Fieldset

In your fieldsets folder which is located in the _config folder create a gallery.yaml file, you can call the fieldset file whatever you like but I would always try to have the name describe what the fields do. In this file you will create the gallery fields which will display in your control panel using the Grid Fieldtype. One thing to note when creating your fields in the YAML file is that spacing is very important you will notice that the fields are indented using 2 spaces and this is what you should stick to. So here is my gallery.yaml file:

fields:
  gallery:
    display: Image Gallery
    type: grid
    starting_rows: 1
    min_rows: 1
    fields:
      title:
        display: Image Title
        type: text
        width: 50%
      img:
        display: Image
        type: file
        allowed: [png, gif, jpg, jpeg]
        destination: assets/img/gallery # make sure your folder is writeable

First you create the top level key fields: under this you then create the fields you require with their settings. I have created a gallery: field which you will note is indented using 2 spaces below fields:, again you can use whatever name you wish, the field name will be used later to render the gallery in your template. Next you will see the settings for the gallery field again indented by 2 spaces:

You now have the first part of the grid set up but before you can enter any entries you need to give the grid some fields. To do this you nest a fields: key under the grid and again using the 2 space indentation you add your field options under it:

You will need to repeat this set up (using the example above to help) for the img field, again taking care to use 2 space indentation.

Create The Image Upload Directory

If you have followed my example above you will notice that I gave the destination: a path of assets/img/gallery you will need to create this folder and make it writable (777). Navigate to your assets folder and in the img folder create a gallery folder. Again you can choose any name but just make sure the destination file path matches in your gallery.yaml file. So that we don't forget we should also make the cache directory writable (777) as this is where Statamic will save a cached version of our image. You set your image cache directory in your settings file.

Create The Content Page

In your _content folder create a folder called gallery and in there create a page.md file. What you name this folder is again up to you. Inside your page.md file, between the YAML Front Matter (a set of three dashes in the head of your document), add the following:

title: Image Gallery Basic
_template: gallery
_fieldset: gallery

This gives the page a title, tells the page to use the gallery template to render the content, and assigns the gallery fieldset that we just created.

The Gallery Template

In your templates folder located in your _themes folder create a gallery.html file. In here is where you will create the html markup for the gallery and add the Statamic tags which will render your images. I have kept this super simple for the purposes of this example but you could create any kind of gallery you wish. My code looks like this:

<h2>Gallery Using Image Plugin</h2>
<div>
  <ul class="gallery">
    {{ gallery }}
    <li>
      <a href="{{ img }}">
        <img src="{{ transform src="{{ img }}" width="600" height="300" }}">
        <div>{{ title }}</div>
      </a>
    </li>
    {{ /gallery }}
  </ul>
</div>

First I have created an unordered list to mark the content up, I then wrap the li tags in a Statamic tag pair {{ gallery }}{{ /gallery }}. If you remember back to when we created the fields this is the name that we gave to the fields in the gallery.yaml fieldset file. The anchor tag uses the {{ img }} variable to output the file path to the image (again the same name we gave to the field in the gallery.yaml file). Finally we use the transform tag to render our images at a size of our choosing. There are a few different parameters that you can set for the transform tag, you can read about them in the docs. For now here's what I have used:

You should now have everything set up and ready to go. If you login to your control panel and navigate to the gallery page you will see a title, slug field, with the gallery grid below that ready for adding your images. One point to note is that there is still a content field below this. If you do not want to have this content field display you can add the following code to your gallery.yaml fieldset file:

content:
type: hidden

Again spacing is very important, the complete file should look like this:

fields:
gallery:
display: Image Gallery
type: grid
starting_rows: 1
min_rows: 1
fields:
title:
display: Image Title
type: text
width: 50%
img:
display: Image
type: file
allowed: [png, gif, jpg, jpeg]
destination: assets/img/gallery # make sure your folder is writeable

content:
type: hidden

Conclusion

Upload some images, give them a title and save your gallery page. Navigate to you gallery on the front end of the site and you should see your images with titles rendered to the page. Setting up an image gallery in Statamic is really that simple.

Once you have this one page gallery set up you can then take what you have learned and create an entries listing which would hold multiple galleries, I will show you how to do that in my next post.