Руководство для разработчиков

/
/
/
Пример плагина отчета

Пример плагина отчета

Ниже приводится пример плагина отчета с графиком, таблицей и формой выбора данных. В отличие от примера, приведенного в конце статьи Описание отчетов, где данные для отчета генерировались самой панелью по запросу в элементе <query>, здесь мы будем передавать данные из кода обработчика плагина. 

XML-описание плагина

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

Создадим файл /usr/local/mgr5/etc/xml/ispmgr_mod_report_example.xml со следующим содержимым:

/usr/local/mgr5/etc/xml/ispmgr_mod_report_example.xml
<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
    <mainmenu level="admin+">
        <modernmenu>
            <node name="my_group" icon="m-plugin">
                <node name="report.example" icon="m-plugin"/>
            </node>
        </modernmenu>
    </mainmenu>
    <handler name="report_example.sh" type="xml">
        <func name="report.example" />
    </handler>
    <lang name="ru">
        <messages name="desktop">
            <msg name="modernmenu_my_group">Плагины</msg>
            <msg name="modernmenu_report.example">Пример отчета</msg>
        </messages>
    </lang>
</mgrdata>

Так добавляется новый раздел панели Плагины — Пример отчета, который указывает на функцию report.example и регистрирует обработчик report_example.sh для этой функции.

Обработчик плагина

Создадим файл обработчика /usr/local/mgr5/addon/report_example.sh и дадим ему права 750 (пользователь и группа root). Содержимое файла:

/usr/local/mgr5/addon/report_example.sh
#!/bin/bash

# смотрим на значение, пришедшее из формы от <select name="period" /> и если там была
# выбрана опция "Предыдущий месяц", записываем в переменную reportdata один набор строк,
# в остальных случаях (в т.ч. по умолчанию до выбора в форме) - другой
period=$PARAM_period
if [[ "$period" == "previousmonth" ]]
then
read -r -d '' reportdata <<-EOM
    <elem><value1>7.0</value1><value2>13.0</value2><date>2024-10-29</date></elem>
    <elem><value1>10.0</value1><value2>26.0</value2><date>2024-10-30</date></elem>
    <elem><value1>12.0</value1><value2>11.0</value2><date>2024-10-31</date></elem>
EOM
else
read -r -d '' reportdata <<-EOM
    <elem><value1>10.0</value1><value2>24.0</value2><date>2024-11-01</date></elem>
    <elem><value1>12.0</value1><value2>18.0</value2><date>2024-11-02</date></elem>
    <elem><value1>8.0</value1><value2>20.0</value2><date>2024-11-03</date></elem>
EOM
fi

# выводим XML для страницы, в который вставляем полученный выше набор строк
cat << EOM
<?xml version="1.0" encoding="UTF-8"?>
<doc lang="ru" func="report.example">
    <metadata type="report">
        
        <!-- метаданные формы для выбора периода вверху отчета -->
        <form>
            <field name="period">
                <select name="period" />
            </field>
            <buttons>
                <button type="ok" action="report.example" name="ok"/>
            </buttons>
        </form>
        
        <!-- Заголовок страницы -->
        <text name="title" />
        
        <!-- описание отчета: одна таблица с тремя столбцами и один график по этой таблице -->
        <band name="values" psort="date">
            <col name="date" type="data" sort="alpha" />
            <col name="value1" type="data" sort="digit" />
            <col name="value2" type="data" sort="digit" />
            <diagram name="values" label="date" type="line" >
                <line data="value1" />
                <line data="value2" />
            </diagram>
        </band>
    </metadata>
    
    <!-- данные отчета, сюда вставляем сформированный выше набор строк <elem> -->
    <reportdata>
        <values>
            ${reportdata}
        </values>
    </reportdata>
    
    <!-- Сообщения локализации -->
    <messages>
        <msg name="title">Пример отчета</msg>
        <msg name="values">Серия значений</msg>
        <msg name="value1">Параметр 1</msg>
        <msg name="value2">Параметр 2</msg>
        <msg name="date">Дата</msg>
        <msg name="period">Период</msg>
        <msg name="msg_ok">Показать отчет</msg>
        <msg name="msg_hidedata">Скрыть данные</msg>
        <msg name="msg_nodata">Нет данных</msg>
        <msg name="msg_showdata">Показать данные</msg>
    </messages>
    
    <!-- значения для селекта выбора периода -->
    <slist name="period">
        <val msg="yes" key="currentmonth">Текущий месяц</val>
        <val msg="yes" key="previousmonth">Предыдущий месяц</val>
    </slist>
    
    <!-- значение выбранного периода для отображения в селекте после отправки данных формы -->
    <period>${period}</period>
</doc>
EOM

Теперь, чтобы ispmanager применил добавленное XML-описание плагина, нужно выполнить в командной строке сервера команду:

pkill core

Результат

Перезагрузив страницу в браузере, в панели должна появится новая группа Плагины в разделе Все разделы (в самом конце списка), а в ней пункт Пример отчета, при клике по которому откроется страница отчета:

Подробности

В созданном файле /usr/local/mgr5/addon/report_example.sh добавлены комментарии, объясняющие, как работает код. Дополнительно отметим:

  • Приведен код для простого отчета с одной таблицей и графиком по данным из нее. Ispmanager позволяет формировать более сложные отчеты с дочерними таблицами и графиками, см. пример передачи данных для таких отчетов в статье Описание отчетов.
  • Передача и получение данных формы с параметрами отчета происходит так же, как продемонстрировано в статье Пример использования значений формы. Для создания форм вверху отчетов доступны те же возможности, что в обычных формах.

В этой статье