Разработка плагина

Разработка плагина происходит следующим образом:

1. Проектирование плагина
2. Создание и установка первичного дистрибутива
3. Разработка кода плагина
4. Создание дистрибутива

Проектирование плагина

Проектирование плагина с точки зрения представления в системе включает:

1. Определение режимов работы плагина («Модуль управления», «Спецблок»), что определяет в свою очередь, наличие файлов модуля управления и спецблока.
2. Выбор уникального идентификатора плагина. Далее по тексту на него будем ссылаться, как на PLUGIN_ID

Создание первичного дистрибутива

Первичный дистрибутив нужен для первичной установки плагина, чтобы система сделала все необходимые операции для добавления и регистрации плагина.

Первичный дистрибутив можно создать, скопировав пример плагина «sample», доступной в дистрибутиве системы:

1. Скопировать папку _local/plugins_distr/sample/ со всем ее содержимым в _local/plugins/PLUGIN_ID, где PLUGIN_ID – директория, имя которой совпадает с PLUGIN_ID 
2. Переименовать используемые файлы плагина и удалить неиспользуемые
3. Изменить файл описания для установки плагина, указав все требуемые значения. Подробнее о файле описания – в разделе «Файл описания плагина»
4. Произвести установку первичного дистрибутива
5. Добавление специального блока в Менеджере сайта на тестовую страницу если будет идти разработка спецблока. Указание небольшого времени жизни кэша спецблока.

Файл описания плагина

Файл описания – это INI-файл, содержащий следующие настройки:

Пример файла описания:

;
; unique plugin ID (alphanumeric in lower case and undescore)
id = sample
; current plugin version in format XX.YY
version = 1.00
; specblock and admin file name (at least one of them should be specified)
specblock = my_specblock.php
admin = my_admin.php
; configuration file name
config = my_config.php
; other files
other = my_functions.php, my_class.php
; sql_install_file
; sql_install = install.sql
; sql_uninstall_file
; sql_uninstall = uninstall.sql
; icon that will be displayed on start page (optional)
icon = icon_sample.gif
; list of allowed modules where plugin will be installed to (it is required for now, later it will be optional)
; install_as module will be a real module later - system just checks for such module existence
; module links are considered as NOT installed for now
install_as = modules::news::sample, modules::sample
; manual specifying where plugin has to be installed as (reserved)
;specify_install_as =
; required versions on existing plugins (reserved)
;requirements =
; if the code copying allowed (reserved)
;copy_allowed =

Разработка кода плагина

После установки первичного дистрибутива в зависимости от режима работы плагина, можно приступать к созданию кода плагина.

Код плагина должен удовлетворять следующим требованиям:

1. Работа в локальном контексте, т.е. внутри метода класса
2. Не использовать глобальные переменные. Если используются глобальные переменные, то они должны иметь префикс _plg_, например, _plg_config.
3. Не осуществлять отображение стандартными методами (echo, print, …)
4. Не выводить HTTP-заголовки (header).

Вывод результатов

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

Параметры, передаваемые плагином

В подключаемые файлы модуля управления и специального блока передается ряд параметров системы управления. Они передаются в массиве $pluginParams.

Общие параметры модуля управления и специального блока:

Также в подключаемые файлы модуля управления и специального блока в переменной $api передается объект класса AMI_PluginState, предоставляющий разработчику следующую функциональность по управлению параметрами плагина:

1. Создание дополнительных параметров спецблока плагина;
2. Задание правил для отображения этих параметров в всплывающем окне при настройке спецблока.

Особые параметры специального блока:

API (Application Programming Interface)

С версии 5.10.0 для разработчиков в системе представлен расширенный API.

Документация по Amiro.CMS API представляет собой ряд руководств, предназначенных для программистов, знакомых с PHP и JavaScript. Уровень требуемых знаний зависит от сложности поставленных перед разработчиком задач.

Создание дистрибутива

Для создания дистрибутива необходимо:

1. Скопировать код установленного плагина в дистрибутив
2. Удалить плагин через панель управления, модуль «Мастер плагинов»
3. Произвести установку плагинов в модуле «Мастер плагинов»

Типичные ошибки и рекомендации при разработке

1. При изменении файла конфигурации, для того чтобы изменения вступили в силу, необходимо:
   1. Увеличить версию плагина
   2. Произвести синхронизацию плагина с дистрибутивом
2. В связи с тем, что конфигурация чаще всего меняется при начальной работе с плагином, рекомендуется начинать указание версии с 0, например, 00.01. Это позволит сделать выпуск первой версии со значением 01.00
3. В зависимости от настроек хостинга, в случае синтаксической ошибки PHP, ошибка может быть или отображена на экран, или показывается пустой экран. Поэтому если отображается пустой экран, то необходимо проверить код на наличие PHP ошибок.
4. Так как разработка идет уже на предустановленном плагине, то при сборке дистрибутива необходимо помнить, что удаление плагина, удаляет и все рабочие файлы. Поэтому рекомендуется:
   1. Перед сборкой дистрибутива делать резервную копию существующего кода или фиксировать изменения в системе контроля версий
   2. Использовать плагин, который предназначен только для сбора дистрибутивов. Например, создается плагин distr_test и делается установка/удаление только этого плагина
      
5. Рекомендуется разрабатывать код плагина таким образом, чтобы он мог работать на любом хостинге.

Версия для печати