Первые шаги: плагин «Hello, world!»
В этой статье описан процесс создания плагина в ispmanager с обработчиком на bash-скрипте. В результате будет создан новый пункт в меню со страницей «Hello, world!».
Что потребуется
- Редактировать и загружать файлы. Для этого используйте менеджер файлов или подключитесь к серверу по SSH или FTP.
- Выполнять действия с правами суперадминистратора (root).
XML-описание плагина
Код любого плагина ispmanager обязательно включает XML-файл, описывающий добавляемые плагином изменения.
Чтобы ispmanager увидел этот плагин, файл с его XML-описанием должен:
- находиться в папке /usr/local/mgr5/etc/xml;
- имя файла должно быть в формате ispmgr_mod_*.xml.
Для создания плагина:
1. Перейдите в папку /usr/local/mgr5/etc/xml.
2. Создайте в ней файл ispmgr_mod_helloworld.xml.
3. Скопируйте XML-код ниже и вставьте его в созданный файл:
<?xml version="1.0" encoding="UTF-8"?>
<!-- тэг mgrdata всегда должен быть на верхнем уровне любого плагина -->
<mgrdata>
<!-- секция, добавляющая группы и пункты в меню -->
<mainmenu level="30">
<!-- в современных версиях ispmanager главное меню описывается
в тэге modernmenu внутри тэга mainmenu -->
<modernmenu>
<!-- в ispmanager двухуровневое меню - группы, внутри которых
пункты - ссылки на страницы, и для тех, и для других
используется тэг node; если мы хотим создать
пункт меню без группы, нужно на уровне группы добавить
атрибут type="noname" -->
<node name="helloworld_group" type="noname">
<!-- тэг node второго уровня задает конкретный пункт меню,
атрибут name используется как func для страницы при
задании обработчика, а также для задания строки
локализации в тэге msg ниже -->
<node name="helloworld" />
</node>
</modernmenu>
</mainmenu>
<!-- тэг handler задает обработчик, имя файла обработчика -
в атрибуте name -->
<handler name="helloworld.sh" type="xml">
<!-- тэг func внутри тэга handler определяет, какие вызовы
(например, страницы) будут обрабатываться данным обработчиком -->
<func name="helloworld" />
</handler>
<!-- тэг lang задает секцию сообщений локализации для одного языка,
внутри него могут содержаться сообщения локализации для многих страниц -->
<lang name="ru">
<!-- тэг messages задает секцию сообщений локализации для одного func
или, в данном случае - для навигационных элементов, общих для всех
страниц (name="desktop") -->
<messages name="desktop">
<!-- тэг msg задает строку локализации с единственным
атрибутом-идентификатором name. В данном случае префикс
modernmenu_ указывает, что мы задаем локализацию для
пункта меню с именем, указанным после префикса -->
<msg name="modernmenu_helloworld">Плагин Hello, World</msg>
</messages>
</lang>
</mgrdata>В XML-коде выше приводится объяснение того, что происходит на каждой строчке.
Дополнительные понятия, с которыми предстоит постоянно сталкиваться в процессе разработки плагинов:
- func, «функция» — идентификатор какой-то части функциональности ispmanager (встроенной или добавленной в плагинах), использующийся в API ispmanager. К каждой странице ispmanager обязательно привязана какая-то функция, предоставляющая данные для отображения страницы. В некоторых случаях функция может обслуживать несколько страниц или, наоборот, функционал одной страницы может задействовать несколько разных функций. Идентификатор функции связывает воедино разные части функционала. В приведенном XML-описании плагина он указывается для пункта меню (<node name="helloworld" />) и связывает пункт меню и обработчик, который должен вернуть данные для отображения страницы при выборе пункта меню;
- строки локализации — текст для элементов UI задается отдельно от самих элементов (в случае выше — текст пункта меню задается отдельно от самого пункта меню). Чтобы задать язык, используется тэг <lang>, внутри него может быть один или несколько тэгов <messages>, а каждая отдельная строка задается тэгом <msg>.
В приведенном XML-описании плагина есть ссылка на файл обработчика, это будет второй файл, который нужно создать для вашего плагина.
Обработчик
Файлы обработчиков плагинов должны удовлетворять следующим требованиям:
- находиться в папке /usr/local/mgr5/addon;
- имя файла может быть любым, но файл должен быть исполняемым для пользователя и группы root.
Для создания обработчика:
1. Перейдите в папку /usr/local/mgr5/addon.
2. Создайте в ней файл helloworld.sh (имя файла, которое вы задали в атрибуте name тэга <handler> в XML-описании плагина).
3. Присвойте файлу права 750 с помощью кнопки Атрибуты в менеджере файлов или с помощью команды в консоли:
chmod 750 /usr/local/mgr5/addon/helloworld.sh4. Скопируйте код Bash-скрипта обработчика ниже и вставьте его в созданный файл:
#!/bin/bash
cat << EOM
<?xml version="1.0" encoding="UTF-8"?>
<doc lang="ru" func="helloworld">
<metadata type="form">
<form>
<field name="helloworld_field">
<textdata name="helloworld_message" type="msg" />
</field>
</form>
</metadata>
<messages>
<msg name="title">Плагин Hello, world!</msg>
<msg name="helloworld_message">Hello, world!</msg>
</messages>
</doc>
EOMАктивация плагина
1. Перезагрузите панель ispmanager, выполнив из терминала команду (можно воспользоваться Администрирование → Shell-клиент в ispmanager):
pkill core2. Обновите страницу с панелью ispmanager.
Результат
Снизу меню появился новый пункт «Плагин Hello, World!».
Если перейти по этой ссылке, откроется страница вашего плагина:
Заключение
Созданный обработчик выводит статичный XML-код, который помещен между EOM на второй строке и EOM на последней. Значение func из XML-описания плагина используется здесь в атрибуте func тэга <doc>.
Также здесь присутствуют знакомые по XML-описанию плагина тэги <messages> и <msg>, задающие строки локализации. В целом этот XML описывает страницу с типом «форма», в которой есть заголовок и единственное поле (<field>) со статичным текстом (<textdata>).
- XML-описание;
- обработчик;
- функции (func);
- строки локализации.
Более подробно устройство и возможности плагинов разбираются в разделе Структура и возможности плагинов.