Регистрация плагина

# Введение

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

1. Определить компоненты.
2. Определить права пользователя.
3. Добавить страницу с настройками, меню, списки и формы.
4. Создать структуру базы данных и внести в нее данные.
5. Изменить функциональность ядра или других плагинов.
6. Описать классы, контроллеры, представления и другие файлы.

# Структура плагина

Все плагины находятся в подпапке /plugins. Структура плагина выглядит следующим образом:

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

Но не все плагины обязаны иметь такую структуру. Например, если Ваш плагин предусматривает только один компонент, то его содержимое может выглядеть так:

plugins/
  acme/              <=== Author name
    blog/            <=== Plugin name
      components/
      Plugin.php     <=== Plugin registration file

Примечание: если Вы являетесь разработчиком плагина для Marketplace, то наличие файла updates/version.yaml обязательно.

# Пространство имен

Пространства имен плагинов очень важны, особенно если планируется, что Ваш плагин будет опубликован в Маркетплейсе (opens new window). При регистрации в Маркетплейсе, Вам будет предложено ввести авторский код, который будет использован в качестве корневого имени директории для всех Ваших плагинов. Вы можете ввести этот код только один раз, когда проходите регистрацию. По умолчанию Вам будет предложен авторский код от Marketplace, состоящий из Вашего имени и фамилии. Например: VasyaPupkin. Помните, что данный код невозможно будет поменять после регистрации. Все файлы плагина должны быть определены в корневой папке Вашего плагина. Например: \VasyaPupkin\Blog.

# Файл регистрации

Файл Plugin.php, называемый как Регистрационный файл плагина или Файл регистрации плагина, является скриптом инициализации, который объявляет основные функции и содержит в себе информацию о плагине. Он может содержать следующее:

• Информацию о плагине, его названии и авторе.
• Регистрацию методов для расширения CMS.

Скрипт регистрации должен содержать класс с именем Plugin, который расширяет \System\Classes\PluginBase класс. Единственным обязательным методом класса регистрации плагина является pluginDetails(). Пример:

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'
        ];
    }
}

# Поддерживаемые методы

Следующие методы могут содержаться в регистрационном файле плагина:

# Основная информация о плагине

Метод pluginDetails() является обязательным методом класса регистрации плагина. Он должен возвращать массив, состоящий из 4 ключей:

# Роутинг и инициализация

Файлы регистрации плагина могут содержать два метода: boot() и register(). С этими методами Вы можете делать всё, что только пожелаете: зарегистрировать маршруты или привязать обработчики к событиям.

Метод register() вызывается непосредственно в тот момент, когда плагин регистрируется. Метод boot() вызывается прямо перед маршрутизацией запроса. Таким образом, если Ваши действия зависят от другого плагина, Вы должны использовать метод загрузки. Например, внутри метода boot() Вы можете расширить модели:

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

Примечание: методы boot() и register() не вызываются в процессе обновления плагина, чтобы избежать критических ошибок.

Плагины могут содержать файл routes.php, в котором может находиться произвольная логика маршрутизации. Например:

Route::group(['prefix' => 'api_acme_blog'], function() {

    Route::get('cleanup_posts', function(){ return Posts::cleanUp(); });

});

# Определения зависимостей

Работа Вашего плагина может зависеть от других плагинов. Для этого укажите их в свойстве $require в Файле регистрации плагина. Пример:

namespace Acme\Blog;

class Plugin extends \System\Classes\PluginBase
{
    /**
     * @var array Plugin dependencies
     */
    public $require = ['Acme.User'];

    [...]
}

# Twig

Пользовательские Twig фильтры и функции могут быть зарегистрированы в CMS при помощи метода registerMarkupTags() в Файле регистрации плагина. Пример:

public function registerMarkupTags()
{
    return [
        'filters' => [
            // A global function, i.e str_plural()
            'plural' => 'str_plural',

            // A local method, i.e $this->makeTextAllCaps()
            'uppercase' => [$this, 'makeTextAllCaps']
        ],
        'functions' => [
            // A static method call, i.e Form::open()
            'form_open' => ['October\Rain\Html\Form', 'open'],

            // Using an inline closure
            'helloWorld' => function() { return 'Hello World!'; }
        ]
    ];
}

public function makeTextAllCaps($text)
{
    return strtoupper($text);
}

# Меню

Плагины могут расширять меню в административной части сайта, переопределяя методregisterNavigation() в Файле регистрации плагина. Пример:

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']
                ]
            ]
        ]
    ];
}

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

Настройте контекст, чтобы отобразить подменю в административной части сайта.