Developing a Simple Plugin for OctoberCMS

At Depth Interactive, we’ve decided to rebuild our website. Part of that decision was to build the website with the same technology we’ve started using on our client’s projects, namely Laravel. After determining our needs, we decided to use OctoberCMS for the rebuild.

Without spending too much time selling you on OctoberCMS, it’s a great platform, particularly if you would like your content to live in your filesystem (controlled by git) rather than in a database.

A downside I found to OctoberCMS is its lack of documentation outside of their own, which can be lackluster for those that are new to the platform. The biggest help I found was on YouTube, especially the Watch & Learn Tutorials. I learn best by reading, so I’m going to do my part in the coming months to contribute to OctoberCMS’s documentation here on Medium.

Developing the Plugin

One of the elements our site needs is a list of project pages that include a name, short description, an image, and the link to the project page itself (see screenshot). Nothing quite like this exists in October’s plugin library, so we decided to create a plugin of our own.

Our projects listing page

Using OctoberCMS’s plugin scaffolding tool

October’s Builder plugin has proven to be very helpful in creating a scaffold for your plugin’s custom functions and creating all the standard views in the backend for adding, editing, and removing the data you’d like to display on the front-end.

After installing the Builder plugin to your site, creating a plugin scaffold is easy. Select ‘Builder’ from the top menu, hit the arrow in the top LH corner of the builder screen, and fill out the fields.

If you take a look at your codebase after hitting ‘OK’, you’ll notice a new folder has been added with a number of files inside the plugins/ directory. It will continue to update as you make changes in the backend.

Creating the database, model, controller, and backend page

Putting together the database, model, controller and admin page is very easy using the Builder tool. Here’s a screenshot of my database for the projects menu:

Clicking ‘add timestamps’ or ‘add soft deleting support’ will automatically add the necessary columns.

In the Model, there are two options, forms and lists. The list is where you will be displaying your data for viewing in the admin, and the form is how you’ll edit the database fields in the admin. Here’s what my fields.yaml looks like:

Next, I created the backend menu item:

Then, I created the controllers for the lists and fields. I didn’t have to do any customization for my plugin, it ‘just worked’. I did get stuck for a moment until I realized I needed to go back to my backend menu item and add the URL from my list view controller.

At this point, I was able to refresh my screen and click on my new ‘Project Links’ menu item and begin adding menu items to the plugin list:

List View

Add/Edit a Link

At this point, I need to add sorting so that I can reorder the menu items, and I should probably clean up the page titles using the builder tool to make it look a little nicer. But my priority is getting the data on the front-facing website!

Creating the Component

I’m going to focus on showing you how to get the data passed into your component, since that was my main struggle for my plugin. It’s fairly simple if you’ve used the Builder scaffold, all that’s needed is a few quick functions.

You’ll first need to add a component file. In your plugin root (mine is /plugins/depth/projectsmenu) you’ll want to create the component directory, the controller, and the template.

In your component’s controller (mine is /plugins/depth/projectsmenu/components/WorkMenu.php), you need to define the component’s details, pass in the data from your model, and define the global variable that you’ll use in the template:

<?php
namespace Depth\ProjectsMenu\Components;

use Cms\Classes\ComponentBase;
use Depth\ProjectsMenu\Models\Link;

class WorkMenu extends ComponentBase {

    public function componentDetails() {
        return [
            'name' => 'Work Menu',
            'description' => 'List of clients for /work'
        ];
    }

    public function onRun() {
        $this->menu = $this->loadMenu();
    }

    protected function loadMenu() {
        return Link::all();
    }

    public $menu;
}

Inside your template, you just need to set your variable at the top of the page. Mine is {% set clients = __SELF__.menu %} then I can loop through clients later on in the template to display the projects list. This is where you’ll add any necessary markup to the component. My template looks like this (/plugins/depth/projectsmenu/components/workmenu/default.htm):

{% set clients = __SELF__.menu %}
<div class="clients">
  {% for client in clients %}
    <div class="client" onclick="javascript:location.href='{{ client.link }}'">
      <div class="client-photo-block">
        <div class="image-block">
          <img src="{{ client.image | media }}">
        </div>
        <div class="text-block-section">
          <div class="text-block">
            <h2>{{ client.name }}</h2>
            <div class="subtext">
              <i>{{ client.description }}</i>
            </div>
          </div>
        </div>
      </div>
    </div>
  {% endfor %}
</div>

After the template is setup, all that is left is registering the component with the plugin so that you can add the component to a front-facing page. To do that, go to your Plugin.php (/plugins/depth/projectsmenu/Plugin.php) file and inside the already existing registercomponents() function, return an array with the path to your component and name it:

<?php namespace Depth\ProjectsMenu;

use System\Classes\PluginBase;

class Plugin extends PluginBase
{
    public function registerComponents()
    {
        return [
            'Depth\ProjectsMenu\Components\WorkMenu' => 'WorkMenu'
        ];
    }
}

At this point, you’re ready to add your component via the codebase or the backend. Using the backend, navigate to the page you’d like the component to be displayed on, and drag and drop the component from your list of components to the area within the markup you would like it displayed:

At that point, you should be able to see your component on the page you’ve specified!

Conclusion

I hope that my simple overview of using October’s builder tool helps you understand some of the basics of plugin development. October is highly flexible and I’m looking forward to continuing my learning and using it on more projects in the future.

Feel free to reach out to me in the comments if I’ve missed any steps or you’re high-centering on anything and I’ll do my best to respond.

Depth Interactive is a software development studio located in downtown Salt Lake City, UT.