Made withOctober CMSTutorial

Making Websites With October CMS - Part 34 - Backend Lists

W

Watch and Learn

Creator on the October CMS channel

Watch on YouTube ↗

12K viewsMar 25, 201715:51 runtime

Learn to customize backend lists in October CMS to create a more informative and user-friendly admin interface. This tutorial demonstrates how to use the Builder plugin to modify list columns, display related data like genres using relationships, and show image thumbnails by…

Chapters

#octobercms#tutorial#cmscrm

Customizing Backend Lists in October CMS

This document outlines key techniques for customizing backend list views in October CMS, primarily using the Builder plugin and understanding the underlying columns.yml configuration file.

Displaying Images with Partials

To show an image (e.g., a movie poster) in a list, you can't use a standard column type. Instead, you use a partial.

Add a New Column: In the Builder, add a column for your image field (e.g., poster).
Set Type to partial.
Define the Path to the partial file. The path starts from your plugin's root directory, e.g., ~/plugins/author/plugin/models/modelname/_column_poster.htm.
Create the Partial File: Create the .htm file at the specified path.
Write the Partial Code: Use the record variable (which holds the model object) to access the image and generate a thumbnail.

{% if record.poster %}
    <img src="{{ record.poster.getThumb(80, 80, {'mode': 'crop'}) }}" />
{% endif %}

Important
Always check if the image relationship (record.poster) exists before trying to access its properties like getThumb(). This prevents errors on records that don't have an image uploaded.

Displaying Relational Data

To display data from a related model (e.g., showing a movie's genres), use the relation setting.

Add a Column: Add a column and name it after the relationship defined in your model (e.g., genres).
Define Relation: In the column's advanced properties, set the Relation field to the same name (genres).
Select a Field: By default, this will show a JSON representation of the related objects. To display a specific field, use the Select property to specify the column name from the related table (e.g., genre_title).

Creating Custom Columns with SQL

You can combine multiple database fields into a single list column using a raw SQL SELECT statement.

Example: To combine an actor's name and last_name into one column.
Configure the Column: Edit the name column (or create a new one).
Use the select property: Write an SQL CONCAT statement.

# In columns.yml for the Actor model
name:
    label: Name
    type: text
    select: "concat(name, ' ', last_name)"
    searchable: true

Tip
This select property accepts any valid SQL SELECT expression, giving you powerful control over how column data is retrieved and displayed.

User-Controlled Columns

October CMS lists include a built-in feature that allows backend users to toggle the visibility of each column. This icon is located in the header of the list view and provides a simple way to customize the display without needing developer intervention.

Introduction to Backend Lists

In this episode, we are going to be covering a list for October CMS. This is one more functionality that we just skimmed over while we were creating our site, but in this episode, we are going to go into more detail about it.

So the lists are when you go to your back-end and click on movies, you just get the list of your movies. As I said, we already created our lists, but we just did the basic stuff. So maybe right here you want to have a genre of the movie displayed or maybe even you want to have a poster of the movie displayed. So we are going to be covering all of that in this tutorial.

Most of the things that we are going to be doing in this tutorial will come from the Builder plugin, but I just want to repeat something. So when you use the Builder plugin, I already said this before, but just want to repeat it so that you get a good understanding of it. When you use the Builder plugin, what October actually does is it mostly creates just configuration files that you would, without it, have to create by hand. So you have this documentation for lists on the October CMS site in the documentation, and as you can see, this is all full of some code and something like that. Most of the stuff, as I said, we will be doing through the Builder plugin.

Builder Plugin vs. Manual YAML Editing

The builder plugin just creates those files for you and just modifies those files that they would reflect the configuration that you did with the Builder plugin. So let's just test it out.

If you go to our back-end and go to Builder, we choose our plugins, so movies. And now if I go to models and check out our list for the movie, we can see that we have fields 'name' and the label is 'name'. So if I go to my code editor and go to plugins/watchlearn/movies, and if you go to models, then you will see this columns.yml file. And as you can see, that file right here, you can change the name of it if you want. But if we click to the columns one, well, you can see name, label is name, type is text, searchable is true, and so on, just like we did right here. So if I change the label to be 'Movie Name', save it, and then we should go right here... you can see that now it's called 'Movie Name'.

So what Builder actually does is just create those files for you and then modifies them when you do something right here. You can, of course, just go to this file and write everything by hand. Nothing wrong with that.

Adding an Image Column with a Partial

So in this step, I'm going to have opened this columns.yml file and in this step, I'm just going to have the movie list so that we can see what changes are happening. So let's say, for example, that you want to display a poster for the movie right in this list. So how would you do that? Well, you would go right here, you can add a column and call that column 'poster'. So that's the field name that we have for our poster. Okay.

Now you would add a label, okay, and the type would be 'partial' in this case because we don't have a type of 'image' or something like that. The type is going to be partial and what we need to do right now is set the path of that partial. So the path would be something like so. First of all, this squiggly line... I'm going to make this a bit bigger so that you can see. So the squiggly line (~) represents the root of your site. So then you would go to plugins, then you would go to watchlearn/movies/models/movie, so that's the name of our model, and then you would define a partial for it. So in our case, it can be _poster_column.htm. And that's it.

Now, if we save this and go to the movies, refresh it... so of course, get an error because that partial doesn't exist. So we called it _poster_column.htm. Now I'm just going to go to movie, so we said that that partial lives in watchlearn/movies/models/movie and right here I'm going to create that file, so _poster_column.htm. Okay, so now we have that.

Implementing the Image Partial and Thumbnails

Now if you check out the documentation for partials, you can see that you can use some of the variables in partials. So value is the default cell value, record is the model. So let's just try it out. So I'm going to go right here and do this. Let's try just to display the value of the poster. Okay. Now if you refresh this, you would get nothing because we actually do, but as you can see, we have this field right here because we don't have any images right here. So let's just click on the movie and add an image. So I'm going to add this image right here. Save and Close. Now as you can see, we get the value of that poster. So this is the poster field and you have the ID, the disk name, file name. So this is actually a model that comes with October CMS for saving images.

Now what you could do right here is get this path. So we would just go right here and do path. Save it. Refresh the page and now you would get the path to your image. So you can do something like so: image source is equal to that path. Save it, and if you go right here, you would get this very, very large image, which of course you don't want. You could maybe do something like width and height right here and make the image the size that you want, but that's not a good option because it will load that big image anyway. So the better thing for you would actually be to do something like getThumb. And now October is going to create a thumbnail for us that is going to be displayed right there. So I'm going to set my thumbnail to be 80 by 80 pixels and it's also going to be cropped. Okay, save this.

If we go right here, refresh this page right now, you would get this error. And now this error is happening because our first movie does have an image but the other movies don't. So it's going through a for each loop and then it comes to the first movie, creates the thumbnail for it, that's okay. When it comes to the second movie, it sees that there actually isn't any images right there, so you get this 'call to a member function' error. So what we need to do is create a if condition. So if the record... so that's our model... which is poster... if the record has a poster... actually not our model poster, but our movie model. So that's the record right here. So record. So if record.poster then you would do this, and that's it. So if your movie has a poster, it will display this image. If it doesn't, it won't do anything. So we just save this, refresh now, and now as you can see, we get that poster right here.

Toggling Column Visibility

One more thing I forgot to show you about lists, at least I think I did, is this icon right here. So if you click on it, you can get the fields that will be displayed in this list. So if you, for example, want to disable the year, you just do this, and now the year is gone. Also, if you want to add it, just do this, and now the year is here. Okay, so let's do something else now.

Displaying Data from a Relationship

Let's try to add some genres to our movie list. If I go right here, as you can see, we don't have any genres. So I'm just going to go here and create some: Comedy and Drama. Okay. Now we go to our movies, go to this one, and add Action and Comedy. So this is an Action-Comedy. Now we want to display those genres right here.

To do that, if we go to our database and go to movies_genres, actually not to movies_genres but just to movies, you will see that we don't have any genres in our movies, so we have to get them some roundabout way. So if we go to models and columns, we can use something called 'relation'. So we just add this, call this 'genres', the label is going to be 'Genres', and we will select this to be just text, maybe make it searchable, and then you have to define your relation. So if you go to your code editor and go to Movie.php, so models/Movie.php, you will see that movies already has a relationship with genres, and it's a belongsToMany relationship. So that's why we can just add 'relation' right here and just as the same name as we have in this file. So we will just write 'genres'.

Okay, let's try to save this and see what will happen. Now, as you can see, because we already touched this, genres don't display. So just click right here and say that you want to display the genres. And as you can see, you get the ID, the genre title, slug, pivot table and so on. So you have to have some way to actually just get this genre title. To do that, we will just go right here and in this 'select' column will write genre_title. Save it, refresh it, and now you would have this: 'genres: Action and Comedy'. So that's the way you would use the relationships for your post.

Creating a Custom Column with SQL

Let's try another thing. So let's go right here to the actress, and as you can see, we have a name and last name. So let's say that we want to display a name and last name in one column. We don't want to have two columns for name and last name, we just want to have one column. So how would you do that?

So first of all, we are going to go not to our columns.yml for movies, but to our columns.yml for actors. And now I'm going to delete this last_name column. So we just delete it. We set the type to be text, but right here in select, we can use some SQL queries to display stuff on our page. So I can use concat right here, and then we use the name of the name field, which is 'name', and then I will do this so that we have a space between name and last name, and then we do the name of the field for the last name, which is just 'last_name'. Save this and now if we go to our list, refresh it, we will see the name and last name displayed in just one field.

So as I said, if you read through the documentation, you can use any valid SQL select statement here, so you can use whatever select statements you want for this SQL query.

Conclusion and Next Steps

So this has been it for this video. I hope we covered the examples that you would actually use on your websites, like displaying images in your lists or displaying the relationships. But for this episode, this is it. Of course, we didn't cover absolutely everything you need to know about lists. For that, you have this documentation page, so you can check it out and see what else you can do with the list.

In the next episode, I'm going to be covering filters, which is tied to the list. So I'm going to show you how you can create filters for your list. If you want to ask me questions in the meantime, you can use Facebook, Twitter, GitHub, or my website for that. Remember, everything we did here will be available for you on GitHub, the link will be in the description below.

If you want to throw some money my way, you can use the Patreon page for that. The link to it will be at the end screen of this video. Also, if you liked the video, please give it a thumbs up, like it, and if you like the channel, maybe subscribe to it. Thank you guys for watching and I will see you in the next one.