How To Create Plugin In OctoberCMS

Plugin in OctoberCMS

As a name suggest “Plugin” is a software add-on (i.e. Set of code to achieve some specific functionality) that is installed onto a program, enabling it to perform additional features.
 
In OctoberCMS Plugins are the foundation for adding new features to the CMS by extending it.
 
Purpose:

  1. To enable third-party developers to create abilities which extend an application
  2. To support easily adding new features
  3. To reduce the size of an application
  4. To separate source code from an application 

To create new plugin for OctoberCMS you must have to follow below steps:

  • Registration
  • Directory Structure
  • Registration file
  • Supported methods
  • Basic plugin information
  • Routing and initialization
  • Navigation menus
  • Version History
  • Plugin version file
  • Extending with events

Registration:

The registration process allows plugins to declare their features such as components or back-end menus and pages. Some examples of what a plugin can do:

  • Define components.
  • Define user permissions.
  • Add settings pages, menu items, lists and forms.
  • Create database table structures and seed data.
  • Alter functionality of the core or other plugins.
  • Provide classes, backend controllers, views, assets, and other files.

 
Directory structure: Plugins reside in the /plugins subdirectory of the application directory. An example of a plugin directory structure:

plugins/
acme/ <=== Author name
blog/ <=== Plugin name
classes/
components/
controllers/
models/
updates/
...
Plugin.php <=== Plugin registration file

 

Registration file: The Plugin.php file, called the Plugin registration file, is an initialization script that declares a plugin's core functions and information. Registration files can provide the following:

  • Information about the plugin, its name, and author.
  • Registration methods for extending the CMS.

 
Registration scripts should use the plugin namespace. The registration script should define a class with the name Plugin that extends the \System\Classes\PluginBase class. The only required method of the plugin registration class is pluginDetails. An example Plugin registration file:

namespace Acme\Blog;
 
class Plugin extends \System\Classes\PluginBase
{
public function pluginDetails()
{
return [
'name' => 'Blog Plugin',
'description' => 'Provides some really cool blog features.',
'author' => 'ACME Corporation',
'icon' => 'icon-leaf'
];
}
 
public function registerComponents()
{
return [
'Acme\Blog\Components\Post' => 'blogPost'
];
}
}

 

Supported methods: OctoberCMS provides list of available methods which you can define/use in your plugin

Method Name Description
pluginDetails() Returns information about the plugin.
register() Register method, called when the plugin is first registered.
boot() boot method, called right before the request route.
registerMarkupTags() Registers additional markup tags that can be used in the CMS.
registerComponents() Registers any front-end components used by this plugin.
registerNavigation() Registers back-end navigation menu items for this plugin.
registerPermissions() Registers any back-end permissions used by this plugin.
registerSettings() Registers any back-end configuration links used by this plugin.
registerFormWidgets() Registers any back-end form widgets supplied by this plugin.
 
registerReportWidgets() Registers any back-end report widgets, including the dashboard widgets.
registerListColumnTypes() Registers any custom list column types supplied by this plugin.
registerMailTemplates() Registers any mail view templates supplied by this plugin.
registerSchedule() registers scheduled tasks that are executed on a regular basis.

Basic plugin information: The pluginDetails is a required method of the plugin registration class. It should return an array containing the following keys:
 

Key Description
name

the plugin name, required.

description

the plugin description, required.

author

 

the plugin author name, required.

icon

A name of the plugin icon. The full list of available icons can be found in the UI documentation. Any icon names provided by this font are valid, for example icon-glass, icon-music.

iconSvg

An SVG icon to be used in place of the standard icon, optional. The SVG icon should be a rectangle and can support colors.

homepage

A link to the author's website address, optional.


Routing and initialization: Plugin registration files can contain two methods boot and register. With these methods you can do anything you like, like register routes or attach handlers to events.

  • register: It is called immediately when the plugin is registered. 
  • boot: It is called right before a request is routed. 

So if your actions rely on another plugin, you should use the boot method. For example, inside the boot method you can extend models:

public function boot()
{
User::extend(function($model) {
$model->hasOne['author'] = ['Acme\Blog\Models\Author'];
});
}

 

Plugins can also supply a file named routes.php that contain custom routing logic, as defined in the router service. For example:

Route::group(['prefix' => 'api_acme_blog'], function() {
 
Route::get('cleanup_posts', function(){ return Posts::cleanUp(); });
 
});

 

Navigation menus: Plugins can extend the back-end navigation menus by overriding the registerNavigation method of the Plugin registration class. This section shows you how to add menu items to the back-end navigation area. 

An example of registering a top-level navigation menu item with two sub-menu items:

public function registerNavigation()
{
return [
'blog' => [
'label' => 'Blog',
'url' => Backend::url('acme/blog/posts'),
'icon' => 'icon-pencil',
'permissions' => ['acme.blog.*'],
'order' => 500,
 
'sideMenu' => [
'posts' => [
'label' => 'Posts',
'icon' => 'icon-copy',
'url' => Backend::url('acme/blog/posts'),
'permissions' => ['acme.blog.access_posts']
],
'categories' => [
'label' => 'Categories',
'icon' => 'icon-copy',
'url' => Backend::url('acme/blog/categories'),
'permissions' => ['acme.blog.access_categories']
]
]
]
];
}

 

When you register the back-end navigation you can use localization strings for the label values. Back-end navigation can also be controlled by the permissions values and correspond to defined back-end user permissions.
 
Version History: It is good practice for plugins to maintain a change log that documents any changes or improvements in the code. In addition to writing notes about changes, this process has the useful ability to execute migration and seed files in their correct order.
 
The change log is stored in a YAML file called version.yaml inside the /updates directory of a plugin, which co-exists with migration and seed files. 
 
This example displays a typical plugin updates directory structure :

plugins/
author/
myplugin/
updates/ <=== Updates directory
version.yaml <=== Plugin version file
create_tables.php <=== Database scripts
seed_the_database.php <=== Migration file
create_another_table.php <=== Migration file

 

Plugin version file:

1.0.1: First version
1.0.2: Second version
1.0.3: Third version
1.1.0: !!! Important update
1.1.1:

  • Update with a migration and seed
  • Create_tables.php
  • seed_the_database.php

As you can see above, there should be a key that represents the version number followed by the update message, which is either a string or an array containing the update message.
 
Extending with events: Plugins are primarily extended using the Event service to inject or modify the functionality of core classes and other plugins.
 
The most common place to subscribe to an event is the boot method of a Plugin registration file. For example, when a user is first registered you might want to add them to a third party mailing list, this could be achieved by subscribing to a rainlab.user.register global event.

public function boot()
{
Event::listen('rainlab.user.register', function($user) {
// Code to register $user->email to mailing list
});
}

 

The same can be achieved by extending the model's constructor and using a local event.

User::extend(function($model) {
$model->bindEvent('user.register', function() use ($model) {
// Code to register $model->email to mailing list
});
});

 

You can declare events globally or locally, below is an example of declaring a global event: 

Event::fire('acme.blog.beforePost', ['first parameter', 'second parameter']);

 

The local equivalent requires the code be in context of the calling object.

$this->fireEvent('blog.beforePost', ['first parameter', 'second parameter']);

 


 Hope this blog helped you for creating OctoberCMS plugin and feel free to share your reviews or need assistance  for Hire OctoberCMS Developers then get in touch with us. Pick the best answer for your requirements.