Writing a plugin for October CMS

On Habré was already a publication about the release of the OctoberCMS beta, that's all over. There are few Russian-language materials on this CMS, so I decided to contribute.

Today we will write a plugin directory for the site.

More information about what this CMS is of itself can be found on the official website . Let me just say that CMS is based on the Laravel framework, so we have tools for artisan , Eloquent ORM command line migration, which greatly simplifies development.

October CMS installation

Clone the repository , go to the project folder and execute:
')

$ composer update 

Then in the app / config / database.php folder, change the settings for connecting to the database and run the command:

 $ php artisan october:up #   

Now we can run 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 a plugin. Let's find it now. To do this, go to the admin panel http: // localhost: 8000 / backend and specify the standard username and password admin: admin .

Go to the Settings -> Updates section and see our plugin there:

Basic 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 store information about it, the name of the author, a 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 at all, only on some that we will use.

  public function pluginDetails() { return [ 'name' => 'catalog', //  'description' => 'No description provided yet...', // 'author' => 'iillexial', // 'icon' => 'icon-leaf' //  ]; } 

A 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 into the admin area, we will see the following:



The menu item of our plugin has appeared, but nothing will work, because we have neither controllers nor models. Create them:

Controllers and models

To create a controller, run the following command:

 $ php artisan create:controller iillexial.catalog Products #iillexial.catalog Products ""      

Attention!
October for some reason cuts the last 's' in the name of the controller and in the controller's configs it writes the name of the model without 's'. Ie 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 there are two new folders: controllers and models . Also there was a migration file in updates / create_products_table.php .

For migrations to work, add their launch to updates / version.yml :

 1.0.1: - Run table migrations - create_products_table.php 

And then run the command:

 $ php artisan plugin:refresh iillexial.catalog 

It will start our migrations from the verison.yaml file. I will not dwell on migrations, as they are exactly the same as in Laravel. The only thing I recommend to do is to add a function to the up method for deleting the table, that is, we will bring the 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 the tables each time manually, after we have made changes to the database structure.

After we set up our migration, created the controller and model, our menu in the admin panel will work and we will see the following 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 a product for inserting it into the database, but there will be a single field - id . Now I will tell how to fix it and where it comes from.

For each model, a folder is created in which there are two files:

 models product fields.yaml columns.yaml 

fields.yaml - field settings that we will see when creating, editing a record.
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 coincides with a 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 on “New product” and see a completely different page:



But what kind of product catalog without pictures? Here, too, everything is simple, OctoberCMS has a built-in file uploader, which I will now discuss.

In order to use attachments in our plugin, we need to make a link in the model. Open the models / Product.php and find the arrays in which various connections 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 = []; 

Let's take the second one and make a connection in it with the System \ Models \ File system model:

 public $attachMany = ['attachments' => ['System\Models\File']]; 

Everything, structure of the table is not necessary to change. But you need to add the ability to attach files in fields.yaml :

 fields: title: label:  description: label:  type: richeditor attachments: label:  type: fileupload 

Save the file and refresh the product creation page in the admin panel, we’ll see the following:



So our form appeared with the download files.

That's all. At this point , we’ll finish with the admin panel, except we ’ll change some of the columns.yaml to put in order a page with a list of our columns. There is nothing to wise, just add:

 columns: id: label: ID searchable: true title: label:  created_at: label:   

Create a test record, try to edit 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 and there are components.

To create a component, you need to run:

 $ 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 to get our records from the database. First, let's define the 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 our model we get a list of records sorted by id.

Everything, on it creation of a component ended, now it needs to be registered 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']; } 

We’ll finish the development of the backend for our plugin and learn how to display the whole thing on the site pages.

Use of components

To begin with, we will create a new website page in the /pages/catalog.htm folder. And insert the following code there:

 url = "/catalog" #url       [catalog] #      == {% for product in catalog.getProducts %} <!--  getPosts         !--> <h4>{{ product.title }}</h4> <!-- !--> <p>{{ product.description|raw }}</p> <!-- !--> <img src="{{ product.attachments.0.path }}"> <!--     !--> {% endfor %} 

Next, go to the page with the directory - http: // localhost: 8000 / catalog - and see our records there.

At this point I would like to finish, since the article turned out to be voluminous. Continuation will be in the next article, in it I will tell in more detail about controllers, communications in models, and, perhaps, addition on loading of files.

Ask questions, suggest what to talk about in the next article.

Links

Link to the repository with the plugin
OctoberCMS group VKontakte
OctoberCMS website
Russian site OctoberCMS