Made withOctober CMSClip

Making Websites With October CMS - Part 09 - Images And Galleries

W

Watch and Learn

Creator on the October CMS channel

Watch on YouTube ↗

40K viewsAug 10, 201614:58 runtime

Learn to manage images and build galleries in October CMS. This guide covers adding a featured poster to a movie model using the file upload widget and an `attachOne` relation. You'll see how to render and resize images on the front-end with Twig's `thumb` filter. We then…

Chapters

#octobercms#clip#cmscrm

Key Concepts for Handling Images in October CMS

This document summarizes the steps for adding single images and galleries to a model in October CMS.

Fixing URL Routing Conflicts

A common issue arises when a list page with pagination (e.g., /movies/page/2) conflicts with a detail page using a similar path (e.g., /movies/inception).
Solution: Make the URL structures distinct. For example, change the detail page URL from /movies/:slug to /movie/:slug to avoid ambiguity.

Adding a Single Image (`attachOne`)

Backend Field: In the Builder, add a file-upload field to your model's fields.yaml.
- Set the Mode to image.
- Configure imageWidth and imageHeight for the backend thumbnail preview (e.g., 100x100).
Model Relation: You must define the relationship in your model's PHP file (models/Movie.php).

Important
Without defining the relation in your model code, you will get an error when trying to access the record in the backend. October CMS needs this definition to handle the file attachment.
```
class Movie extends Model
{
    // ...
    public $attachOne = [
        'poster' => 'System\Models\File'
    ];
    // ...
}
```

Displaying and Resizing Images (`thumb` filter)

To display the image, access its path property: {{ record.poster.path }}.
Use the thumb Twig filter to create resized versions of the image on the fly.
Proportional Resizing: {{ record.poster.path | thumb(200, 'auto') }}
- This creates an image 200px wide with a proportional height.
Cropping: {{ record.poster.path | thumb(200, 200, {'mode': 'crop'}) }}
- This creates and crops the image to a 200x200 square.

Note
The thumb filter's parameters are not well-documented. The primary known usage is width, height, and an options array with a mode key.

Creating an Image Gallery (`attachMany`)

Backend Field: Add another file-upload field for the gallery (e.g., movie_gallery). Configure it the same way as the single image field.

Model Relation: In the model's PHP file, use the $attachMany property.

class Movie extends Model
{
    // ...
    public $attachMany = [
        'movie_gallery' => 'System\Models\File'
    ];
    // ...
}

Displaying an Image Gallery

The attachMany relation provides an array of image objects.
You must use a Twig for loop to iterate through the collection and display each image.

<h3>Gallery</h3>
<ul>
    {% for image in record.movie_gallery %}
        <li>
            <a href="{{ image.path }}">
                <img src="{{ image | thumb(80, 80, {'mode': 'crop'}) }}" alt="">
            </a>
        </li>
    {% endfor %}
</ul>

The image object inside the loop is the full file model, so you can pass it directly to the thumb filter or access its properties like .path.

Fixing a URL Routing Conflict

Okay. So in this episode we are going to be tackling images. So we are going to create an image field for our movies so that we can add a poster to our image and also we are going to be creating an image gallery of our movie.

One more thing we are going to do, and we are going to do that right away, is fix our pagination and movie slugs because for some reason that doesn't work anymore. I don't know what happened there. So, it just worked before. Now, it doesn't. I don't know how to fix it except for the way that I will show you in a second.

If I go to my movies page right now and click on Inception, this doesn't work for some reason. It just stays on the same page. Actually, it changes the URL, but it displays the record list. So, the list of our movies. So, I don't know what's going on. It does the same thing on my test instance of this site. So, I think it probably has something to do with this movie URL and the slug and then a movies URL and the page. So October doesn't quite know if it should display pagination or it should display our movie. So what we can do, we can just go to movie single and change movies to be movie and then a slug or you can change this movies to be a movie, whatever. So you just save this. And now our URLs are going to be a bit different. But if I click on Inception right now, it should work.

Also, what I'm going to do, I'm going to go to movies and set records per page to be 10. Okay? Because we don't need pagination with only three movies. Okay, so that's it. So if you're having the same problem as I did, this is the way you can fix it at least for now.

Creating a Single Image Field

Okay, so let's set up our images right now. So we are going to go to our builder plug-in and then we select movies, go to models, fields, and then I'm just going to add one more control right here. And I'm going to choose a widget called file upload. Okay.

So, the cool thing about October, you don't need to have a database field for this because it already has some systems to handle your images. So, I'm just going to add a field name and I'm going to call it poster. And the label will be movie poster. Okay. Um next thing we need to do, we need to set up this file upload and the mode will be image. Also you have this image width and height. So this reference is actually the size of your image that will be displayed in administration. So not the images that you get on front end but in administration. So you don't have to make this really big. I will make it 100 by 100 pixels. Okay. And that should actually be it.

Defining the `attachOne` Relation

We just save this. And now if we go to movies and click on Inception, you should get an error. You get an error and it says it doesn't have a definition for poster. So it's not as easy as you would think it would be because you have to add something to your code. So we are going to go to our code editor, go to plugins and then watch learn movies and models. So we want to update our movie model and set a relation for our images.

So I'm just going to comment relations right here. And we are going to be talking about relations even more in the next video. But in this video we have to attach our movie to our model. So to do that you use public attach one because we want to just, we want to attach just one image to our movie model, at least for the poster, and then we are going to create a gallery and in gallery we are going to attach many images to our movie model. Okay.

And now you set the field of your image. Okay. So we say public attach one poster to the system models file. So this with October CMS. And now if we save this and refresh our page, this should actually work. Okay. Now, we just go to movie poster and we can add a poster to our movie. So, I'm just going to go to my desktop. I have this Inception right here. And this is this would be the featured image for our movie. Open it up. As you can see, this is all this all looks very nice in October. So, we have this image right here. We can just save this. And now our Inception movie has a movie poster.

Displaying and Resizing a Single Image

Now how would we display those images? Actually the image that we get from poster field. So I'm going to go to my movie single.htm and below the title of the movie I can write just something like this. Save it. And now you can see that we get an array of our poster. We get array of data that is connected to that image. So you get the ID, the disk name, the file size, path and so on. So what you can do, you can just grab the path for example, save it. And now you just get the path of the image. And of course you can just use the image tag and display that image that way.

And now we get that image but it's a little bit too big. So what we can do we can use this twig function called thumb and make our image let's say 200 pixel in width and height to be relative to our width. So to be proportional to the original image and now you get this. So this is the poster for Inception. Okay, there are a few more things. So let's say you want to make that image be 200 by 200 and cropped. So you can do this. Save it. And now our image is 200 by 200 pixel and it's cropped. I'm going to leave it to be actually auto.

Now the thing with thumb function is I didn't actually find any documentation on it. I just stumbled on it on the internet and I couldn't find documentation for the parameters that the thumb function takes. So if any of you know where to find that documentation, please let me know. So for now I know it accepts 200 by auto, it accepts the mode for cropping the image but other than that I can't tell you very much.

Creating a Gallery Field

So let's go to our builder plugin right now and create our gallery. So I'm going to go to models, fields and create a new field right here. And I'm going to select file upload again. I'm going to give it a name of movie gallery. The label is going to be movie gallery. The file upload is going to be image, and image width and height. Let's set it to be 80 by 80. And that should actually be it.

Defining the `attachMany` Relation

Just save this. Of course, if we go to movies once again and go to Inception, we should get an error like we did when we did the poster field. So, I'm going to go to my movie model once again, copy this out, paste it right here, and instead attach one, I'm going to say attach many. And the field is movie gallery. And that should be it.

If we go right here, refresh it. Now we can add many images to our movie gallery. So if I click on this and by holding the shift key I can choose all of these images. Click open. And now as you can see those images are loaded right here. Also you can move them. So you can change the order of your images and that's the way that they are going to be displayed on your front end.

Displaying the Image Gallery on the Front-End

So let's display those images right now. First of all, we have to save this. I'm going to display the images below our description. Put the gallery in H3 tags. And now to display many images a situation is a bit different than displaying just one image, because you get an array of images. So if we do record.movie_gallery save it, we should get an array with images. So this is the first image, this is the second image and so on. So you have to iterate over those images to get the individual image.

So what you can do is let's just create an ul tag. And then we are going to use the Twig's for loop. So I'm going to say for image in record.movie_gallery. So this is going to be our image variable. So this is a for each loop actually and then we have the access to the image variable. So if I do something like image.path, I will get the paths of all the images. So let's just put BR tag behind this so that we can see it better. And now as you can see we get the path to those images. So the situation right now is the same as with this record poster path. So when displaying just one image.

Of course the CSS for this is already written. So I'm just going to add a class to the ul of gallery and clearfix. And then I'm going to put the image into li tag. And of course the image thumb should go into a image tag. So I'm not going to be using image.path but I'm going to be using image|thumb and I'm going to set it to be 80 by 80 and the mode is going to be crop. Okay. Okay, if we save this right now, we should get the image gallery with all of our images cropped and displayed. One more thing you can do, you can add an A tag right here around your image of course. And now if we save this, go to our page, click on any image, we should get the full version of that image.

Conclusion and Resources

Okay. So, of course, this would be much better if you use some lightbox plugin, jQuery lightbox plugin. And then you would probably just have to write something like class lightbox or something like that in here. And then when you click on this, the model would open up and display your image. So, this is the way you deal with images in October CMS.

Don't forget everything we did here will be available for you on GitHub. The link will be in the description below. Also, if you like this video, please like it. If you like the content I put out, please subscribe to the channel. You can follow me on Twitter or on Facebook and ask me questions there. So, thank you guys for watching and I will see you in the next episode.