So instead of explaining what we are going to be doing in this episode, I'm just going to show you. So this is my test site and as you can see, I don't have a repeater field right here, but instead of that, I have this select box in which I have some actors: Leo DiCaprio, Robert De Niro, and Al Pacino. So let's say I want to remove Al Pacino, I'll just do this. If I want to add again, I can just start typing his name, 'Al', and I get Al Pacino, and so on. As you can see, this is a much better way of doing things than if you had that repeater field and all of the data would be stored in your movie table. We don't want to do that.
We actually want to have a separate table for actors, and in that table, you can add as many fields as you want. So you can have name, last name, biography, trivia, and so on. And then we would connect this field and movie and actor models via a pivot table, just like we did for those genres right here. But for genres, we had to use this checkbox because the checkbox comes with a builder plugin. And in this episode, I'm actually going to show you how you can create your own custom form widget just like this one.
Prerequisites and Folder Structure
So this is what we are going to be doing in this episode, and in the next episode, I'm going to show you how you can connect that form widget to your movie model and then take the data from that widget and create the relation between movie and an actor. So as I said, in this episode, we are going to be creating this right here.
Before we start creating our custom form widget, I just want to mention a few things. So there already is a widget like this for October. It comes with October and it's called tag list. Nevertheless, I wanted to create an example, a good demonstration of how easy it is in October to create your own custom form widgets. So if you want to do this very quickly without creating your widget, you could use tag list. It doesn't come with builder, but it does come with October, and you can use it in your fields.yml file. But just for the sake of demonstration, I'm going to create that same widget right here in this episode.
So before we begin, the widget is going to be using a select2 plugin for jQuery, and you can download it right here. So you just download the JS file and the CSS file and you would have to create this kind of a folder structure. I've already created it and I already downloaded these files so that we don't waste time on that, and I'm pretty confident that you can do that without me showing you exactly how.
The next thing you need to do, you need to create this type of folder structure. So you would have this, your namespace for your plugin and then the plugin name, so Movies, and then you have to create another folder called formwidgets, and we are going to call our form widget 'actorbox'. And you have this ActorBox.php file right here. And then you would have 'actorbox' inside of it. You would have 'assets', and inside of 'assets', you will have CSS and JS that we would need to display our widget. And in the 'partials' folder, you have this _widget.htm file, which is going to be a place where we will write our HTML for the widget. And then you have this ActorBox.php in which we will define our widget so that October knows what to do with it.
Of course, if you don't want to follow up or follow with this video, you can just download the latest version of this video series from GitHub. The link will be in the description below, and you will have all of that right there.
So first of all, let's define our widget. So I've already created this folder structure and I have this ActorBox.php file right here. I'm just going to copy something in it. So this is, this would be the way that you would start all of your form widgets, so all of your custom form widgets. As you can see, we just have these namespaces right here. We have to use BackendClassesFormWidgetBase, Config, and we have to use the model of Actor. Actually, I'm not going to use it right now. I'm going to use it a little bit later, but for now, we don't need it. And then we have this class ActorBox which extends the FormWidgetBase. So all of this is actually pre-made for you in October. You just have to use the right methods to tell October how you want your widget to act.
So first thing we need to do, we need to define our widget, so the widget details. To do that, we use a method called widgetDetails, so like this. And this method is going to return the name of our widget and the description of our widget. So name is going to be 'ActorBox', and the description can be something like, 'Field for adding actors'. And that should be it.
Next thing we want to do, we want to tell that plugin or form widget to create a partial, actually to read from a partial what our field will look like. So to do that, you use the method render. And what we said right here is just return $this->makePartial(). So this is another function that comes with October, and it's going to call your widget file. So our file is called widget.htm.
Okay, the next thing we want to do is we want to define what other assets do we need for our widget to work. So since we are using the select2 plugin, which is a great plugin for creating the types of widgets that you saw, so we need to define these two files. So select2.css, so CSS file, and the JS file called select2.js. And to do that, you would just use another of another function, and that function is going to be called loadAssets.
So we use this method loadAssets, and then we add a CSS. So you have a function for adding CSS, and since it is in our assets/css folder, we just define it like this. So css/select2.css and addJs('js/select2.js'). Now we have to tell our plugin, so Movies plugin, we have to tell it that this form widget actually exists so that you can load it once it's booting up.
So when we go to public/Plugin.php file, I'm just going to paste this right here and explain it what it does. So this just returns the values for your custom widget. So as you can see, this is a method called registerFormWidgets, and it returns your namespace, your plugin name, and then it sets formwidgets, so this right here, actorbox. So return that, and the label for that is going to be 'Actor Box Field', and the code for that is going to be 'actorbox'. So the code is used when you want to add this field to your fields.yml file.
So if I go to my models and then go to movie model, you will see that we have this fields.yml. So until now, all of this, the builder plugin did for us. So as you can see, we have a name field, description field, year field, slug, poster, movie gallery, genres, actors, and so on. So this is our actors field. So what I'm going to do right now is I'm going to delete it, delete everything in it, because our actors field is going to be this actor box that we created and it's going to have a different setup than the repeater field that we used in the previous episode. So I'm going to delete that and then define that field in our fields.yml file.
First of all, let's define a label for our field. Next, I want to define where that field is going to be positioned on our form. Okay. And after that, we just have to define what field type or form widget we are going to be using. So just like we did right here, we said the code for that is going to be actorbox. So I'm just going to set a type of field to be actorbox. Okay, and that should actually be it. Let me just save this.
Okay, and yeah, we defined that, but if we go to our movies right now, and go to, let's say Inception, as you can see, I have a syntax error on actor box on line 14. Let me just deal with that. So line 14, maybe this should help. Okay, and now you have actors right here, but you don't see anything. We don't have a field right here. So let me just show you how that works. So if I go to widget.htm, so as I said, this file is used to display the actual field, and let's just put a typical input field in it. So the type is going to be text and let's set it a value. Okay, save it and let's see what we get. As you can see, we have Actors, and then we have this 'hey' right here. So this is the field that is displaying via the widgets. What we want to do now actually is not display this typical input field, but we want to display our select box field.
Building the HTML Select Box
So to do that, we are first going to create a typical normal select box. So let's create a select box. So you have this select box right here. The name of the box, actually, we are not going to add anything to it right now. So what I'm going to be doing, I'm just going to hard-code some options in it. So I have three options, and that's about it. So we have Leonardo DiCaprio, Al Pacino, and Robert De Niro. They have values of 1, 2, 3. So this is actually what we want to get when we make this dynamic. So this is all hard-coded right now, but we want to get this in the next episode, but to be dynamic. So to read from our actors table, read all of those names and assign those values to it so that we can select them and then save it to our database. But let's just save this for now and see what we get.
Okay, so right now we have this select box right here, and we can choose any of the actors. Of course, we want that field to be multiple so that you can choose multiple things from it, not just one. So if I refresh it, now we get this right here, and using a command key, I can select however many actors I want. Okay.
Initializing the Select2 jQuery Plugin
Next thing we need to do is we need to say in some way that this select field is actually going to be using the select2 jQuery plugin so that it looks like what I showed you at the beginning of this episode. So to do that, we are just going to write a few lines of JavaScript. Remember, we are already with this ActorBox calling these assets, so CSS file and the select2.js file. So to do that, we will do this.
So we open up a script tag and then we say on document render, make this a select2 field. Okay. And now if you read the documentation for the Select2, you have to give it a class or ID of the field that you want to apply the select2 jQuery plugin on. So what I'm going to do, I'm going to call that class s2. So every element with the s2 class is going to be a select2 box. And that select2 can have some options. So first option I'm going to add is going to be a placeholder, and that placeholder is just going to say 'Add actors'. And there is one more option that we need to enable, and that's tags because usually select2 box looks something like this. So let me just show you an example. Where are the examples? Right here. So it looks something like this, right? You can have that, or you can have something like this, right? So we don't want that. We actually want to for our select box to look like those tags that we were adding at the beginning of the episode. That's why we are going to enable this option: tags: true. Okay.
Now, this will not work because this select box doesn't have a class of s2, so let's add a class to it, save it, and check it out in our administration.
Final Styling and Next Steps
Okay. Now this looks a bit like what we want. As you can see, I can choose Al Pacino, Robert De Niro, Leonardo DiCaprio. I can remove them, and so on. So this CSS isn't very good, so I'm just going to write a few lines of CSS so that this field is actually below the 'Actors' and that its width is 100%.
Okay, so what I've written here is this select2-container. If we check it out with the developer tools. So we are targeting... let me just find it. Come on, I can't find it right now, but it's here. So this is the select2-container. It is targeting that, and I'm just saying to it that it needs to be 100% and to display as a block, so that that input field will go under 'Actors'. If I save it and refresh it, now this looks much better. So we have 'Actors', we can add Al Pacino, Leo, and so on, remove them, and so on.
Remember, all of these values are actually hard-coded in. Also, we don't have the actors table, so we can't actually save this and expect it to work. But in the next episode, I'm going to show you how you can do just that. So how you can display all of these values dynamically and then save them to your database. Okay, so this is it for this video. In the next video, we are going to make that select box actually work. So thank you guys for watching. Please follow me on Twitter or on Facebook if you like. If you liked this video, please give it a thumbs up. And if you like the channel, maybe subscribe to it. I don't know. Also, remember, everything we did here will be available for you on GitHub, and the description, of course, is down below. So you can download all the code that we did today. Thank you guys for watching once again, and I will see you in the next episode.
