Developing A Custom Plugin For October CMS

By Andriy Haydash

Developing A Custom Plugin For October CMSDeveloping A Custom Plugin For October CMS

Andriy Haydash

2019-10-08T12:30:59+02:002019-10-17T05:07:26+00:00Last year, I did some research about new CMS systems in PHP in order to find a good alternative to WordPress. Ideally, it had to be an open-source solution with a clean and modern codebase.

One of them caught my interest: October CMS. I tried it and almost instantly liked it. The code structure was really nice and it was easy to write custom plugins.

This article aims to give you an overview of what to expect from the platform and give you a taste of it before you decide to commit to using it.

Why Choose October As Your CMS Platform?

There are a few main reasons why I have personally decided to use it for my projects.

Powered By Laravel

October is built on top of the most powerful PHP framework for creating modern web apps: Laravel. I can say with great confidence that it’s the best. It is very easy to use and understand, and has all the features that a modern framework needs, from routing, object-relational mapping (ORM), authorization, caching, and many others that provide a nice and clear MVC structure. As it is powered by Laravel, October has inherited all those features from its big brother.

Clean Code And Documentation

Unlike many other CMS solutions, October has a very clean and well-documented codebase. It’s written in using an objectoriented paradigm. Instead of plain old PHP, October uses Twig as its templating engine, which simplifies things for developers. Technical documentation is also well written, and helps you quickly find answers to most of your questions.

Great Community

Even though October’s community is not yet that big, it’s very helpful and responsive. There is a public Slack channel you can join, where you’ll find developers happy to assist you in fixing your issue.

Big Marketplace

Like WordPress and other CMSes, October has a marketplace for themes and plugins. Even though there aren’t that many good themes to choose from, there are over 700 plugins right now, so it’s very likely you’ll be able to add functionality by simply searching for and installing one of them. A great feature of plugins is that they can be easily synchronized between all your projects if you just add your project ID in the admin dashboard.

PlugIns And Components

Plugins are a foundation of adding new functionality to October. A plugin can consist of multiple files and directories that are responsible for registering custom components, models, updating database structure, or adding translations.

A plugin is usually created in the plugins/ directory of the project. Since many plugins are submitted to the marketplace for others to use, each plugin should have a custom namespace, which usually starts with the name of the company or developer that created the plug-in. So, for instance, if your name is Acme and you’ve created an awesome plugin called Blog, your plugin will live under the namespace of AcmeBlog.

Let me show you how a plugin directory structure might look like:

Sample plugin directory structure (Large preview)
As you can see, there is also a file called plugin.php that is responsible for registering a plugin and all of its components in October CMS.

Another important thing to mention is that not all directories listed above are necessary for a plugin to run. Your plugin could have the following structure and still work perfectly well:

Simple plugin directory structure (Large preview)
Most often, one plugin is built to add only one piece of functionality. For example, the ‘Translate’ plugin is designed to help you translate content on your website into different languages, and provide the multi-language support for the users.

October CMS has a great marketplace where you can find for your needs.

October marketplace (Large preview)
Unlike WordPress and other popular CMSes, October plugins can also have components. According to October’s documentation, components are “configurable building elements that can be attached to any page, partial or layout.” Examples might include: a contact form, navigation, a list of FAQs and their answers; basically anything that it makes sense to bundle together as one building block that can be reused on multiple pages.

Components are created as a part of a plugin and they exist in the components/ subdirectory:

Component directory structure (Large preview)
Each component has a PHP file like componentName.php that defines the component, as well as an optional subdirectory for component partials. A component partials folder must have the same name in lowercase as the component itself.

To demonstrate how a component functions, let’s assume that our component is responsible for showing blog posts.

namespace AcmeBlogComponents;

class BlogPosts extends CmsClassesComponentBase
{
public function componentDetails()
{
return [
‚name’ => ‚Blog Posts’,
‚description’ => ‚Displays a collection of blog posts.’
];
}

// This array becomes available on the page as {{ component.posts }}
public function posts()
{
return [‚First Post’, ‚Second Post’, ‚Third Post’];
}
}

As we can see, the component has two main functions. The first one, componentDetails(), provides information about the component to the administrator who will add and use components on their web pages.

The second function, posts(), returns dummy posts that can then be used inside a component partial (blogposts/default.htm file) like this:

url = „/blog”

[blogPosts]
==
{% for post in blogPosts.posts %}
{{ post }}
{% endfor %}

For October CMS to know our component exists, we must register it using our main plugin file inside a function named registerComponents():

public function registerComponents()
{
return [
‚OctoberDemoComponentsTodo’ => ‚demoTodo’
];
}

Creating A Custom Contact Form plugin

We’re going to create a custom contact form plug-in. Here are the assumptions about how the plugin should work:

The form will have the following fields: First Name, Last Name, Email, Message.
Data will be submitted to the server using Ajax.
After data is submitted, the admin will receive an email with the message sent by the user.
For the purpose of this tutorial we will use a fresh installation of October CMS:

Default view after fresh installation (Large preview)
Let’s start creating our plugin by running a command in a terminal that will generate the plugin structure: php artisan create:plugin progmatiq.contactform

Creating a new plugin from terminal (Large preview)
The progmatiq.contactform argument contains the name of the author (progmatiq) and the name of the plugin (contactform).

New plugin folder structure (Large preview)
Now we need to open our plugin.php file and modify the plugin details in the following method:

public function pluginDetails()
{
return [
‚name’ => ‚Contact Form’,
‚description’ => ‚A simple contact form plug-in’,
‚author’ => ‚progmatiq’,
‚icon’ => ‚icon-leaf’
];
}

Here are a few other methods that you should take a look at:

registerComponents()Here you can define an array of components that your plugin provides.

registerPermissions()You can register custom permissions that you can then use later in other areas of the application.

registerNavigation()You can add a custom menu item with a URL to your admin dashboard menu.

Now let’s create our ContactForm component:

Make a new folder named components/ inside your plug-in’s root directory.
Create a file named contactForm.php inside the components/ folder.

Creating a new component (Large preview)
Paste the following code that will tell October what our component does. We can do it by creating a method inside our component called componentDetails().

From:: Smashing Magazine

      

Posted in Wiadomości.