Writing a plugin for October CMS
- From the sandbox
- Tutorial
On Habré there was already a publication about the release of the beta version of OctoberCMS, this was all over. There are few Russian-language materials on this CMS, so I decided to contribute.
Today we will write a directory plugin for the site.
You can read more about what this CMS is on the official website . I can only say that the CMS is based on the Laravel framework, so we have tools for the artisan command line , Eloquent ORM, and migration, which greatly simplifies development.
Clone the repository , go to the project folder and do:
Then, in the app / config / database.php folder, change the database connection settings and run the command:
Now we can start the embedded server:
The site will be available at: http: // localhost: 8000
You can create a plugin using the command line by running:
So, here we have created the plugin. Let's find him now. To do this, go to the admin panel http: // localhost: 8000 / backend and specify the standard username and password admin: admin .
Let's go to the Settings -> Updates section and see our plugin there:
The basic structure of the plugin is as follows:
Now, in order:
Plugin.php - the base file of our plugin, which will be stored in the information about it, author name, description. In it, we will create navigation for the plugin in the admin panel, define components. Supported methods are described here , I will not dwell on all, only on some that we will use.
The list of icons is available here , they are used throughout the backend.
Add this method to Plugin.php. Then, going to the admin panel, we will see the following: The
menu item of our plugin has appeared, but nothing will work, because we do not have controllers or models. Create them:
To create a controller, you need to run the following command:
Attention!
October, for some reason, truncates the last 's' in the controller name and in the controller configs it writes the model name without 's'. That is, if we have a Products controller, then the model will be Product.
Model:
We will see that two new folders appeared: controllers and models . The migration file also appeared in updates / create_products_table.php .
To make the migrations work, add their launch in updates / version.yml :
And then run the command:
She will launch our migrations from the verison.yaml file . I will not dwell on migrations, since they are exactly the same as in Laravel. The only thing I recommend to do - is to add to method up function to remove the table, ie we present a method to this form:
This is so as not to delete tables manually each time after we have made changes to the database structure.
After we set up our migration, created the controller and model, our admin menu will work and we will see such a page:
I think everything is clear here, the panel on the left is our sideMenu , which we defined in Plugin.php .
When you click on New Product, we will see a page with the creation of the product to insert it into the database, but there will be a single field - id . Now I’ll tell you how to fix it and where it comes from.
For each model, a folder is also created in which there are two files:
fields.yaml - field settings that we will see when creating, editing records.
columns.yaml - column settings, which we will see in the admin panel, in the list of our records.
Add a couple of fields to our migration:
And run it again:
Next, go to models / product / fields.yaml and change it:
As you can see, each block is a new field, its name matches the column in the database. The type parameter is the type of our field. You can read about them here .
Now let's go to the admin panel in our plugin, click “New product” and see a completely different page:
But what kind of product catalog without pictures? Everything here is also simple, OctoberCMS has a built-in file loader, which I will talk about now.
In order to use attachments in our plugin, we need to make a connection in the model. Let's open models / Product.php and find arrays in which various communications are made. But more about all of them in the next article. We need only one connection:
Or if we want to attach a lot of files, then:
Take the second one and make a connection with the system model System \ Models \ File :
Everything, the table structure does not need to be changed. But you need to add the ability to attach files to fields.yaml :
We will save the file and refresh the product creation page in the admin panel, we will see the following:
So our form with file uploads has appeared.
That's all. We’ll end with the admin panel, unless we change a few columns.yaml to tidy up the page with a list of our columns. There is nothing to be wise, just add:
Create a test record, try to replicate it, see how it looks.
Now we need to learn how to display all this in a template on the pages of the site. For this, there are components.
To create a component, you need to do:
A new folder will appear in the folder with our plugin:
Go to components / Products.php and see a structure slightly similar to Plugin.php . Let's make a method for getting our records from the database. First, let's define a namespace for our model:
Then we write the method itself:
Everything is clear here, with the help of our model we get a list of records sorted by id.
That's it, the creation of the component is over, now you need to register it in Plugin.php .
To do this, create a method and make an alias in it for our component:
This completes the development of the backend for our plugin and learn how to display this whole thing on the pages of the site.
First, create a new page in the folder /pages/catalog.htm . And insert the following code there:
Next, go to the page with the directory - http: // localhost: 8000 / catalog - and see our entries there.
I would like to end here, as the article turned out to be voluminous. To be continued in the next article, in it I will tell in more detail about the controllers, the connections in the models, and, possibly, the addition of downloading files.
Ask questions, suggest something to tell in the next article
Link to the repository with the plugin
OctoberCMS Group VKontakte
OctoberCMS
website Russian-language OctoberCMS website
Today we will write a directory plugin for the site.
You can read more about what this CMS is on the official website . I can only say that the CMS is based on the Laravel framework, so we have tools for the artisan command line , Eloquent ORM, and migration, which greatly simplifies development.
Install October CMS
Clone the repository , go to the project folder and do:
$ composer update
Then, in the app / config / database.php folder, change the database connection settings and run the command:
$ php artisan october:up #это запустит миграции
Now we can start the embedded server:
$ php artisan serve
The site will be available at: http: // localhost: 8000
Create a plugin
You can create a plugin using the command line by running:
$ php artisan create:plugin iillexial.catalog #где iillexial.catalog - имя автора и имя плагина
So, here we have created the plugin. Let's find him now. To do this, go to the admin panel http: // localhost: 8000 / backend and specify the standard username and password admin: admin .
Let's go to the Settings -> Updates section and see our plugin there:
Base structure
The basic structure of the plugin is as follows:
plugins
iillexial
catalog
updates
Plugin.php
Now, in order:
Plugin.php - the base file of our plugin, which will be stored in the information about it, author name, description. In it, we will create navigation for the plugin in the admin panel, define components. Supported methods are described here , I will not dwell on all, only on some that we will use.
public function pluginDetails()
{
return [
'name' => 'catalog', //имя плагина
'description' => 'No description provided yet...', //описание
'author' => 'iillexial', //автор
'icon' => 'icon-leaf' //иконка плагина
];
}
The list of icons is available here , they are used throughout the backend.
Create a plugin navigation:
public function registerNavigation()
{
return [
'catalog' => [
'label' => 'Каталог',
'url' => \Backend::url('iillexial/catalog/products'),
'icon' => 'icon-list-alt',
'order' => 500,
'sideMenu' => [
'products' => [
'label' => 'Товары',
'icon' => 'icon-list-alt',
'url' => \Backend::url('iillexial/catalog/products'),
],
]
]
];
}
Add this method to Plugin.php. Then, going to the admin panel, we will see the following: The
menu item of our plugin has appeared, but nothing will work, because we do not have controllers or models. Create them:
Controllers and models
To create a controller, you need to run the following command:
$ php artisan create:controller iillexial.catalog Products #iillexial.catalog Products "путь" к плагину и имя контроллера
Attention!
October, for some reason, truncates the last 's' in the controller name and in the controller configs it writes the model name without 's'. That is, if we have a Products controller, then the model will be Product.
Model:
$ php artisan create:model iillexial.catalog Product #iillexial.catalog Product "путь" к плагину и имя модели
We will see that two new folders appeared: controllers and models . The migration file also appeared in updates / create_products_table.php .
To make the migrations work, add their launch in updates / version.yml :
1.0.1:
- Run table migrations
- create_products_table.php
And then run the command:
$ php artisan plugin:refresh iillexial.catalog
She will launch our migrations from the verison.yaml file . I will not dwell on migrations, since they are exactly the same as in Laravel. The only thing I recommend to do - is to add to method up function to remove the table, ie we present a method to this form:
public function up()
{
Schema::create('iillexial_catalog_products', function($table)
{
Schema::dropIfExists('iillexial_catalog_products');
$table->engine = 'InnoDB';
$table->increments('id');
$table->timestamps();
});
}
This is so as not to delete tables manually each time after we have made changes to the database structure.
After we set up our migration, created the controller and model, our admin menu will work and we will see such a page:
I think everything is clear here, the panel on the left is our sideMenu , which we defined in Plugin.php .
When you click on New Product, we will see a page with the creation of the product to insert it into the database, but there will be a single field - id . Now I’ll tell you how to fix it and where it comes from.
For each model, a folder is also created in which there are two files:
models
product
fields.yaml
columns.yaml
fields.yaml - field settings that we will see when creating, editing records.
columns.yaml - column settings, which we will see in the admin panel, in the list of our records.
Add a couple of fields to our migration:
public function up()
{
Schema::create('iillexial_catalog_products', function($table)
{
Schema::dropIfExists('iillexial_catalog_products');
$table->engine = 'InnoDB';
$table->increments('id');
$table->string('title');
$table->text('description');
$table->timestamps();
});
}
And run it again:
$ php artisan plugin:refresh iillexial.catalog
Next, go to models / product / fields.yaml and change it:
fields:
title:
label: Заголовок
description:
label: Описание
type: richeditor #стандартный wysiwyg редактор
As you can see, each block is a new field, its name matches the column in the database. The type parameter is the type of our field. You can read about them here .
Now let's go to the admin panel in our plugin, click “New product” and see a completely different page:
But what kind of product catalog without pictures? Everything here is also simple, OctoberCMS has a built-in file loader, which I will talk about now.
In order to use attachments in our plugin, we need to make a connection in the model. Let's open models / Product.php and find arrays in which various communications are made. But more about all of them in the next article. We need only one connection:
public $attachOne = [];
Or if we want to attach a lot of files, then:
public $attachMany = [];
Take the second one and make a connection with the system model System \ Models \ File :
public $attachMany = ['attachments' => ['System\Models\File']];
Everything, the table structure does not need to be changed. But you need to add the ability to attach files to fields.yaml :
fields:
title:
label: Заголовок
description:
label: Описание
type: richeditor
attachments:
label: Файлы
type: fileupload
We will save the file and refresh the product creation page in the admin panel, we will see the following:
So our form with file uploads has appeared.
That's all. We’ll end with the admin panel, unless we change a few columns.yaml to tidy up the page with a list of our columns. There is nothing to be wise, just add:
columns:
id:
label: ID
searchable: true
title:
label: Заголовок
created_at:
label: Дата создания
Create a test record, try to replicate it, see how it looks.
Components
Now we need to learn how to display all this in a template on the pages of the site. For this, there are components.
To create a component, you need to do:
$ php artisan create:component iillexial.catalog Products
A new folder will appear in the folder with our plugin:
plugins/
iillexial/
catalog/
components/
products/ <=== Component partials directory
default.htm <=== Component default markup (optional)
Products.php <=== Component class file
Go to components / Products.php and see a structure slightly similar to Plugin.php . Let's make a method for getting our records from the database. First, let's define a namespace for our model:
use Iillexial\Catalog\Models\Product;
Then we write the method itself:
public function getProducts()
{
return Product::orderBy('id', 'desc')->get();
}
Everything is clear here, with the help of our model we get a list of records sorted by id.
That's it, the creation of the component is over, now you need to register it in Plugin.php .
To do this, create a method and make an alias in it for our component:
public function registerComponents()
{
return ['Iillexial\Catalog\Components\Products' => 'catalog'];
}
This completes the development of the backend for our plugin and learn how to display this whole thing on the pages of the site.
Use of components
First, create a new page in the folder /pages/catalog.htm . And insert the following code there:
url = "/catalog" #url по которому будет доступна наша страница
[catalog] #говорим что нужно использовать наш компонент
==
{% for product in catalog.getProducts %}
{{ product.title }}
{{ product.description|raw }}
{% endfor %}
Next, go to the page with the directory - http: // localhost: 8000 / catalog - and see our entries there.
I would like to end here, as the article turned out to be voluminous. To be continued in the next article, in it I will tell in more detail about the controllers, the connections in the models, and, possibly, the addition of downloading files.
Ask questions, suggest something to tell in the next article
References
Link to the repository with the plugin
OctoberCMS Group VKontakte
OctoberCMS
website Russian-language OctoberCMS website