Writing a plugin for October CMS

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.

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

Also popular now: