Пишем плагин для October CMS

На Хабре уже была публикация о выходе бета-версии OctoberCMS, на этом все закончилось. Русскоязычных материалов по этой CMS мало, поэтому я решил внести свой вклад.

Сегодня мы с вами напишем плагин каталога для сайта.

Подробнее о том, что эта CMS из себя представляет можно прочитать на официальном сайте. Скажу лишь, что CMS основана на фреймворке Laravel, поэтому у нас есть инструменты для командной строки artisan, Eloquent ORM, миграции, что значительно упрощает разработку.

Установка October CMS


Склонируйте репозиторий, перейдите в папку с проектом и выполните:

$ composer update

Затем в папке app/config/database.php измените настройки подключения к базе данных и выполните команду:

$ php artisan october:up #это запустит миграции

Теперь можем запустить встроенный сервер:

$ php artisan serve


Сайт будет доступен по адресу: http://localhost:8000

Создаем плагин


Создать плагин можно с помощью командной строки, запустив:

$ php artisan create:plugin iillexial.catalog #где iillexial.catalog - имя автора и имя плагина

Итак, вот мы создали плагин. Давайте теперь найдем его. Для этого перейдите в админку http://localhost:8000/backend и укажите стандартный логин и пароль admin:admin.

Перейдем в раздел Settings -> Updates и увидим там наш плагин:



Базовая структура

Базовая структура плагина следующая:

plugins
   iillexial
      catalog
         updates
         Plugin.php



Теперь по порядку:

Plugin.php — базовый файл нашего плагина, в котором будет хранится в информация о нем, имя автора, описание. В нем мы будем создавать навигацию для плагина в админке, определять компоненты. Поддерживаемые методы описаны здесь, на всех я останавливаться не буду, лишь на некоторых, которые мы будем использовать.

    public function pluginDetails()
    {
        return [
            'name'        => 'catalog', //имя плагина
            'description' => 'No description provided yet...', //описание
            'author'      => 'iillexial', //автор
            'icon'        => 'icon-leaf' //иконка плагина
        ];
    }

Список иконок доступен здесь, они используются во всем бэкэнде.

Создаем навигацию плагина:

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'),
                ],           
            ]

        ]
    ];
}


Добавьте этот метод в Plugin.php. Затем, зайдя в админку, мы увидим следующее:



Появился пункт меню нашего плагина, но ничего работать не будет, потому что у нас нет ни контроллеров, ни моделей. Создадим их:

Контроллеры и модели

Чтобы создать контроллер, нужно выполнить следующую команду:

$ php artisan create:controller iillexial.catalog Products  #iillexial.catalog Products "путь"  к плагину и имя контроллера

Внимание!
October зачем-то обрезает последнюю 's' в имени контроллера и в конфигах контроллера прописывает имя модели без 's'. Т.е если у нас контроллер Products, то модель будет Product.

Модель:

$ php artisan create:model iillexial.catalog Product #iillexial.catalog Product "путь"  к плагину и имя модели

Мы увидим, что появились две новых папки: controllers и models. Так же появился файл миграции в updates/create_products_table.php.

Чтобы миграции работали, добавить их запуск в updates/version.yml:

1.0.1:
  - Run table migrations
  - create_products_table.php

А затем запустить команду:

$ php artisan plugin:refresh iillexial.catalog


Она запустит наши миграции из файла verison.yaml. На миграциях я останавливаться не буду, так как они точно такие же, как и в Laravel. Единственное, что рекомендую сделать — это добавить в метод up функцию для удаления таблицы, т.е мы приведем метод к такому виду:

public function up()
{
    Schema::create('iillexial_catalog_products', function($table)
    {
        Schema::dropIfExists('iillexial_catalog_products');
        $table->engine = 'InnoDB';
        $table->increments('id');
        $table->timestamps();
    });
}

Это чтобы не удалять каждый раз таблицы вручную, после того как мы внесли изменения в структуру БД.

После того, как мы установили нашу миграцию, создали контроллер и модель, наше меню в админке будет работать и мы увидем такую страницу:



Думаю, здесь все понятно, панель слева — это наше sideMenu, которое мы определили в Plugin.php.
При нажатии на New Product мы увидим страницу с созданием продукта для вставки его в БД, но там будет единственное поле — id. Сейчас расскажу, как это исправить и откуда оно берется.

Для каждой модели создается так же папка, в которой есть два файла:

models
   product
      fields.yaml
      columns.yaml

fields.yaml — настройки полей, которые мы будем видить при создании, редактировании записи.
columns.yaml — настройки колонок, которые мы будем видеть в админке, в списке наших записей.

Добавим в нашу миграцию пару полей:

    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();
        });
    }


И снова её запустим:

$ php artisan plugin:refresh iillexial.catalog

Далее перейдем в models/product/fields.yaml и изменим его:

fields:
    title:
        label: Заголовок
    description:
        label: Описание
        type: richeditor #стандартный wysiwyg редактор


Как видите, каждый блок — это новое поле, его имя совпадает с колонкой в базе данных. Параметр type — тип нашего поля. Про них можно прочитать здесь.

Теперь зайдем в админку в наш плагин, нажмем «New product» и увидим совсем иную страницу:



Но что за каталог товаров без картинок? Здесь тоже все просто, у OctoberCMS есть встроенный загрузчик файлов, о котором я сейчас и расскажу.

Для того, чтобы использовать вложения в нашем плагине, нам нужно сделать связь в модели. Откроем models/Product.php и найдем массивы, в которых делаются различные связи. Но подробнее о всех них в следующей статье. Нам же нужна всего одна связь:

public $attachOne = [];

Или если мы хотим прикреплять много файлов, то:

public $attachMany = [];

Возьмем вторую и сделаем в ней связь с системной моделью System\Models\File:

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

Всё, структуру таблицы менять не надо. Но надо добавить возможность прикреплять файлы в fields.yaml:

fields:
    title:
        label: Заголовок
    description:
        label: Описание
        type: richeditor
    attachments:
        label: Файлы
        type: fileupload


Сохраним файл и обновим страницу создания продукта в админке, увидим следующее:



Вот и появилось наша форма с загрузкой файлов.

Вот и всё. На этом закончим с админкой, разве что изменим немного columns.yaml, чтобы привести в порядок страницу со списком наших колонок. Мудрить там нечего, просто добавим:

columns:
    id:
        label: ID
        searchable: true
    title:
        label: Заголовок
    created_at:
        label: Дата создания


Создайте тестовую запись, попробуйте её отредкатировать, посмотрите как это выглядит.

Компоненты

Теперь нам нужно научится выводить все это в шаблон на страницах сайта. Для этого и существуют компоненты.

Чтобы создать компонент, нужно выполнить:

$ php artisan create:component iillexial.catalog Products

В папке с нашим плагином появится новая папка:

plugins/
  iillexial/
    catalog/
      components/
        products/      <=== Component partials directory
          default.htm       <=== Component default markup (optional)
        Products.php   <=== Component class file

Перейдем в components/Products.php и увидим структуру, слегка схожую с Plugin.php. Сделаем метод для получения наших записей из БД. Для начала определим пространство имен для нашей модели:

use Iillexial\Catalog\Models\Product;

Затем напишем сам метод:

public function getProducts()
{
    return Product::orderBy('id', 'desc')->get();
}

Здесь всё понятно, с помощью нашей модели мы получаем список записей, отсортированных по id.

Всё, на этом создание компонента закончилось, теперь его нужно зарегистрировать в Plugin.php.

Для этого создадим метод и сделаем в нем алиас для нашего компонента:

public function registerComponents()
{
    return ['Iillexial\Catalog\Components\Products' => 'catalog'];
}

На этом закончим разработку бэкэнда для нашего плагина и научимся выводить все это дело на страницах сайта.

Использование компонентов

Для начала создадим новую страницу сайта в папке /pages/catalog.htm. И вставим туда следующий код:

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 %}

Далее перейдем на страницу с каталогом — http://localhost:8000/catalog — и увидим там наши записи.

На этом я хотел бы закончить, так как статья получилась объемная. Продолжение будет в следующей статье, в ней расскажу подробнее про контроллеры, связи в моделях, и, возможно, дополнение по загрузке файлов.

Задавайте вопросы, предлагайте о чем рассказать в следующей статье

Ссылки


Ссылка на репозиторий с плагином
Группа OctoberCMS ВКонтакте
Сайт OctoberCMS
Русскоязычный сайт OctoberCMS
Поделиться публикацией

Похожие публикации

Комментарии 11

    +1
    Спасибо за статью, напомнили про эту чудесную CMS. Радостный ушел читать документацию :)
      +1
      Так же недавно начали собирать сайт рускоязчного сообщества octobercms.ru — пока еще работы много, но думаю к релизу CMS как раз успеем.
        +1
        Спасибо, добавил в статью
        0
        В OctoberCMS сильно не хватает возможности отключения визуального редактора для какой-нибудь записи. Если кто знает как это решается — подскажите.
          0
          Если вы о плагине — то поставить тип поля textarea. А так, можете плагин поставить:
          octobercms.com/plugin/anandpatel-wysiwygeditors
          Там в настройках включить где нужно, правда это будет Wysiwyg, а не просто textarea.
            0
            Это не то. Тут мы либо отключаем визуальный редактор полностью для модуля, либо наоборот его включаем. А мне нужно чтобы только для определенной записи в модуле можно было отключить/включить.
              0
              Так нельзя, насколько я знаю
                0
                Я бы сказал что не нельзя а просто не реализовано еще:)
              0
              Я так понимаю, требовалось отключить плагин в конкретной записи а не разделе, в теории конечно можно прописать исключение на конкретную запись, но это очевидный «костыль», думаю оптимальным решением будет создать плагин с тумблером (редактор / код) — кстати, а чем именно вам режим кода в редакторе не подошел?
            0
            Спасибо! Очень жду продолжения!
              0
              Кстати, искал сообщества (в телеграме разумеется), нашел вот чатик в телеге только.

              Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

              Самое читаемое