Made withOctober CMSClip

Making Websites With October CMS - Part 12 - Repeater field

W

Watch and Learn

Creator on the October CMS channel

Watch on YouTube ↗

24K viewsSep 26, 20169:27 runtime

Learn how to effectively use the repeater field in October CMS to manage complex, repeatable data structures like a list of actors for a movie. This tutorial walks you through adding a repeater field to your model using the Builder plugin, defining its sub-fields, and…

Chapters

#octobercms#clip#cmscrm

This video provides a complete guide to implementing and using the Repeater field type in October CMS.

What is a Repeater Field?

A repeater field is a widget that allows you to have a set of fields that can be repeated multiple times for a single model record. It's useful for storing structured lists of data.

Example: Storing multiple actors (each with a name and age) for a single movie record.

Implementation Steps

1. Database Setup

First, you need a database column to store the repeater's data.

In the Builder plugin, go to the Database section for your plugin.
Add a new column to your model's table (e.g., actors).
A Text type is sufficient. The data will be stored as a JSON string.
Make the column nullable so it's not required.

2. Model Configuration (Builder)

Next, add the repeater widget to your model's backend form.

In the Builder, go to Models and select the Fields for your model.
Add a new field and choose the Repeater widget from the dropdown.
Inside the repeater configuration, add the child fields that will be repeated (e.g., a text field for actor_name and another for actor_age).

3. Making the Attribute `JSONable`

Important
When you first try to save data in a repeater, October CMS will throw an "array to string conversion" error. You must tell the model to serialize this field's data as JSON.

Open your model's PHP file (e.g., plugins/author/pluginname/models/Movie.php).
Add your repeater field's name to the $jsonable protected property:
```
protected $jsonable = ['actors'];
```

Displaying Repeater Data on the Frontend (Twig)

Because the repeater data is stored as a JSON array, you cannot render it directly. You must loop through it.

Tip
Use a Twig for loop to iterate through the array and access each item's properties.

<h3>Actors</h3>
<ul>
  {% for actor in record.actors %}
    <li>{{ actor.actor_name }} ({{ actor.actor_age }})</li>
  {% endfor %}
</ul>

Limitations and Better Alternatives

Note
While useful, a repeater isn't always the best solution. For data like "actors," which could exist independently and be linked to multiple movies, a better approach is to create a separate Actor model and establish a many-to-many relationship.

Introduction to Repeater Fields

So first of all, I just wanna apologize for not making any videos for the last few weeks, but I've been pretty busy on my job. There was a project that demanded a lot of my time, so I wasn't able to record these tutorials. But that project is currently winding down and I have a bit more time, so expect at least one video a week for the next few weeks and then I get back to my usual schedule of three or four videos a week.

In this video we are going to be talking about repeater fields for October CMS.

Configuring a Repeater Field in the Builder

The repeater field is actually a set of fields that you can repeat throughout your model. So the obvious way that we could use them in our case, since we were dealing with movies, is actors. So the movie would have many actors and those actors would have a name, last name, age, date of birth and so on. So let's create that.

We are going to go to our builder plugin, go to your movie or whatever plugin you're working on. And first of all all we are going to go to our database and create a new field. And I'm going to add a new column and call it actors. Okay. It's going to be type of, let's say text, but it doesn't matter. And it's going to be nullable, so you don't have to fill it out. And let's just save this. Okay, save and apply. And we got a new column in our database.

Next thing, we go to Models, go to fields for our movies, and then we add a new field and use a widget called repeater. Click on it. And I'm going to call that field actors. Of course the label is also going to be actors. Okay. And as you can see, you can add more fields to the repeater field. So I'm going to add one more field. It's going to be text and it's going to be called actor name. And let's add one more field, and I'm going to call this one actor age. Okay, now that we have this...

Solving the 'JSONable' Attribute Error

we just save it. Then we will go to movies, go to Inception, and right here you have this actors field. And if you click Add new item, you will get two more fields, so actor name and actor age. And let's add just one more. Okay. And now if you go to Save and Close, we will get this exception. So it says unaccepted type of array. Should attribute actors be jsonable? So, this is actually the solution to our problem. We have to make the actors field jsonable.

So to do that, you would go to your code editor. You go to plugins/watchlearn/models and then you open up Movie.php or movie model. And now right here, you have to make actors field jsonable. So to do that, you just write protected $jsonable = ['actors']; like this. Okay? So right now our actors field is JSONable, and I will show you what jsonable actually means in the database.

How Repeater Data is Stored in the Database

So if I go right here, click OK and click Save and Close. Now our Inception movie is saved and the actors are also saved. Okay, so let's see in the database how that JSONable field looks. Since we are using SQLite for this, I'm using SQLite browser to check out my database.

So as you can see, these are all the fields, actually all the tables that we are have in our database. And right here is watch_learn_movies table. So if we go to browse the data and choose watch_learn_movies, you can see right here: Inception, the slug is Inception, and then you can see this actors field. And as you can see, it looks like this. So this is kind of an object with an object inside it. And you have actor name Leonardo DiCaprio, actor age, and so on. And you have number two, you have actor name Ellen Page, and actor age 33. So this is how this repeater field looks in the database.

Displaying Repeater Data with Twig

So now let's display that data on our website on our movie_single.htm file. I'm going to try to display the actors below the description. So we have description right here, and now we create actors title. Okay. So you of course can't display those actors just like this. If I try to do that, so record.actors and save it, go to my page and try to refresh it, I would get an exception. So you can't do that because array to string conversion.

So let's look at our actors. So to look at them you can just do dump and see what that field actually looks like. So as you can see our fields are actually an array with two fields in it, so actor name and actor age. So to display them, you would just have to iterate them through a for each loop. So to do that we just do: for actor in record.actors. And then we can display all the data that we need. So to display the actor's name we can just do actor.actor_name. Save this, check it out. And as you can see, Leonardo DiCaprio and Ellen Page. Also you can do the same thing for actor's age. And now you have Leonardo DiCaprio 40 and Ellen Page 33.

Of course you can put that in some <ul> tag with <li> tags in it and then display them one below the other if you want. Okay.

Conclusion & Alternative Approaches

So this is the way that you would use repeater fields in October CMS. Of course, this is not the best way to approach the actors issue. What would be better if we had, let's say, a database of actors that we can attach to our movie. I hope that we are going to be getting to that in the next few episodes. So creating actors as a separate entity or separate model and then attaching them to our movie kind of like genres, but with a different type of widget. So for genres we had, I'm sorry, checkboxes and for actors I would have... I would rather have something like, I don't know, auto-completing input field that I can just start typing the actor's name and then add a few actors in that field. So I hope that we are going to be able to do that during this series.

Okay, so this is it for this episode. Thank you for watching. Please follow me on Facebook or Twitter if you want. If you like this video, please like it. If you like the content I put out, please subscribe to the channel and I'll see you in the next episode.