OctoberCMS Plugin tutorial part 1

Plugin tutorial part 1 — Testimonials

1. Plugin setup
   1.1. First thing that we must do is create folder structure in plugins folder as described in detail on official OctoberCMS docs right here https://octobercms.com/docs/plugin/registration. Open up plugins folder inside october cms project and create new folder. Name of the folder inside plugins is your author name in our example it is named „ideaverum“. Next step in setup is to create folder for your plugin. Name of that folder has to be lowercase and it’s the name of your plugin. In our example it is „testimonials“. After you created folders now we can create Plugin.php file to register our plugin inside OctoberCMS ecosystem. Inside Plugin.php we will provide general informations about plugin, set up menu items for our controllers, register plugin components. All php files have to use namespace which is combined of your author name and plugin name. Remember when we said your plugin folder name has to be lowercase? Well in namespace it is slightly different. Our namespace is IdeaVerum\Testimonials and it will be used in whole plugin as that. Inside Plugin.php file we will use 3 methods provided by October when we extend PluginBase. Which are pluginDetails, registerComponents and registerNavigation. pluginDetails method is a required method and that’s where we define stuff like name, description, author, icon, homepage url of the plugin. In our example it looks like this:

1. If you are interested which icons you can use visit https://octobercms.com/docs/ui/icon registerComponents method is currently empty but later it will be used to display testimonials on homepage of your web through use of component.

1. registerNavigation is where we build our menu layout. It is used for backend menu system. In our example we are using side menu which will have items Home and Create. There are several things you should pay attention to when creating your menu structure.

1. As you can see we have root item indexed as home. Every item has label, url, icon, order but first item also has sideMenu item in which we then define items in side menu. From image you can see that home is duplicated, that’s because we wanted home item in side menu as well because otherwise we would have to click plugin item in top menu to get home of our plugin and we don’t want to do that. Another item is new_testimonial with it’s data. Important things are indexes in sideMenu array items and their code and url attributes. We will have to use that data in our controllers to properly connect menu with controller. For any additional data on plugin setup and registration look up the link we provided at the start.
2. Project details
   2.1. After quick dip into plugin setup and registration we should probably describe what this plugin will be about. We want to create plugin that will allow us to create client testimonial in administration area and then display them on homepage. Single testimonial will have client name, client web address if existing, client’s comment and image. We will show you how to create simple CRUD of testimonials. On the home page of plugin we will have list of already created testimonials from where you can delete and edit testimonials and will have button for creating new testimonial. After we wrap up administration area we will head over to components and get to know what are they, how to register and use them to display list of testimonials. To developers that have experience working with Laravel most of the stuff should be familiar and all you need to pay attention, is how october works and it’s methods.
   That’s it for the project details let’s move to project structure.
3. Project structure
   3.1.Great now you know basics how to setup plugin project and what are we going to create in this tutorial. Take a look at image of folder structure and we will go over every folder.

1. We have our root folder named same as your plugin. Inside root we can see other folders and Plugin.php which we covered briefly in first part and you should know by now what we will be doing in Plugin.php but as for other folders let’s go over them and explain each one. Components folder will hold all your components which are registered in Plugin.php and each component will have it’s own folder with htm template file and php class file for that component. Controllers folder will hold all your controllers which are used to create administration part of the plugin. Same as components you have subfolder for each view with its .htm and .php class file. Models folder is not required by october but we like to keep things organized and that’s where we usually store all our model files same as you do in Laravel. For this tutorial we will only use one model because we don’t want to complicate already familiar things and focus more on plugin development. Updates folder is a neat feature of october and we love it. Inside you can have install.php, version.yaml and seed.php files. Inside install.php file we define all database migrations which are called from version.yaml. In addition to migration you can use laravel seeder which is also called by version.yaml. So we see that version.yaml is really important file and yes it is because inside we define versions of plugins as you do more and more work you release upgrades for your plugin and your users should know what’s changed, any new features and for you as developer you must somehow scale your project without user even noticing changes under the hood. That’s why this file is so important. For example let’s say we are creating 1.0.0. release version of the plugin and we want to describe this and sometimes call install.php and seed.php or any other php file you want from there. There are some syntax requirements since it’s .yaml file and we will look more into it later.
2. Project setup
   4.1. Looking back at image in project structure section let’s dive into controllers. Look at this image and see the structure of controllers plugin we have.

1. For each view inside administration we have subfolder and inside we have .htm file and then each subfolder(view) has it’s .php class file. Pay attention to naming of folders, .htm and .php that is really important. Inside .htm files we define layout of the page so nothing complicated there. Home.php file contains class that extends Controller class and namespace for controller files should be like this IdeaVerum\Testimonials\Controllers. Notice home subfolder and index.htm file naming because subfolder name should be same as controller name and inside controller we display index.htm by method index() inside controller. Same goes for Testimonial class except that we don’t have index.htm there but create.htm so we should create method named create() that will return create.htm page when we hit backend/ideaverum/testimonials/testimonial/create inside backend.
   To sum this section you need to pay attention on folder structure, template files and class files. Remember that subfolder name should be same as class and template file inside subfolder is returned by method that is named exactly same as template file name.
2. Menu registration
   5.1. Okay let’s register menu on our two controllers. Registering menu requires BackendMenu class and it’s method setContext. In that method you should pass three parameters , first one is AuthorName.Plugin name, second one is menu code and the third one is submenu code which we use because we have sidemenu which behaves as submenu. Inside Plugin.php registerNavigation method you have array and the outer indexes are the menu codes, inside each menu code you have attributes and there is the sideMenu attribute which has it’s own submenu codes and their own attributes. Inside sidemenu array every outer index is your submenu code and that is important when you want to connect controller class with menu. Let’s see registerNavigation image again

1. And now let’s see controllers Home and Testimonial images
2. Home

1. Testimonial

1. Now you can clearly understand the parameters required for setting BackendMenu. First parameter is obvious, second one is first index inside array that you are returning from registerNavigation, and lastly the third parameter are the codes inside sideMenu array. Ofcourse there are other ways you can structure your menu this one isn’t the best example how to create menu but it’s very simple to demonstrate how everything works. Moving on to the next section.
2. Models and controllers
   6.1. We already covered few things for controllers and we believe you should understand what is the purpose of controller by now. We will go over controllers deeper in part 2 where you will see whole controller logic. Models are exactly the same as models in Laravel. In case you haven’t worked with Laravel models are code representations of your database tables so you don’t need to write pesky SQL but use nice methods provided by Eloquent ORM. To keep this plugin tutorial simple we will have only one model which will represent our testimonial object. Inside plugin directory simply create folder models if you haven’t already because that’s where we will store all our models to keep things organized. Check the image below

Thank you for reading! So far we covered the basic building blocks how to create plugin and in next part we will actually see some code and logic in action. Stay tuned for next part.