Для разработчиков

/
/
/
Описание «Главной страницы» (дашборда)

Описание «Главной страницы» (дашборда)

Введение

"Главная страница" предназначена для быстрого доступа к функциям менеджера и наиболее часто требующейся информации (версия панели и ОС, доступные ресурсы и их загруженность, лимиты на ресурсы и т.п.)

Главная страница представляет из себя набор блоков различных типов. Блоки типа url и taskbar отображаются над остальными блоками. Блоки остальных типов могут отображаться в 1, 2 или 3 столбца в зависимости от ширины окна браузера и перемещаться из столбца в столбец, а также вверх/вниз в самом столбце. Блоки можно сворачивать.

Содержимое "главной страницы" описывается при помощи xml-документов, находящихся в директории /usr/local/mgr5/etc/xml. Итоговый вид главной страницы формируется из следующих источников:

  • базовый XML-файл, описывающий дашборд для данного уровня доступа с именем вида ispmgr_dashboard_[номер уровня доступа].xml, например ispmgr_dashboard_16.xml. Следует избегать редактирования таких файлов, т.к. они будут заменены на новые при обновлении ispmanager.
  • файлы плагинов, позволяющие изменять структуру и данные, отображаемые на главной странице, вида ispmgr_mod_[имя плагина].xml, например ispmgr_mod_dashboard.xml.
    Пример расширения функциональности главной страницы с помощью плагина: Добавление быстрого действия на дашборд
  • сохраненной информации о настройках главной страницы для отдельного пользователя: о свернутых и развернутых блоках, отображаемых быстрых действиях, порядке отображения блоков и частоте автоматического обновления информации на странице.

Пример главной страницы ispmanager:

Скриншот главной страницы ispmanager

Описание XML

XML-описание "главной страницы" должно содержать один или несколько элементов <block> внутри элемента <doc>, каждый из которых описывает блок на главной странице..

Ниже приведен пример XML "главной страницы" ispmanager.

Пример XML "главной страницы"

<?xml version="1.0"?>
<doc lang="ru" func="dashboard" binary="/ispmgr" host="https://localhost:4200" themename="dragon" stylesheet="dashboard" features="3a604f5c3c6d5683f90a1f63f1d171aa0" notify="0" favorite="no" pin="no">
  <block name="license.mgr.info" position="right" type="isplicense" func="license.mgr.info" display="" prev=""/>
  <block name="capacity" position="right" type="list" func="server_capacity" enable_autoupdate="yes" prev="" display=""/>
  <block name="session" position="right" type="list" func="session" rows="5" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="session" type="list"/>
    <toolbtn name="kill"/>
    <col name="name" sort="alpha" sorted="+1"/>
    <col name="level"/>
    <col name="ip"/>
    <col name="idle"/>
  </block>
  <block name="longtask" position="right" type="list" func="longtask" rows="5" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="longtask" type="list"/>
    <toolbtn name="view" default="yes"/>
    <toolbtn name="delete"/>
    <col name="realname" type="data" sort="alpha"/>
    <col name="startdate" type="data" sort="alpha" sorted="-1"/>
    <col name="enddate" type="data" sort="alpha"/>
    <col name="state" sort="prop"/>
  </block>
  <block name="authlog" position="right" type="list" func="authlog" rows="5" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="authlog" type="list"/>
    <col name="time" sort="alpha" sorted="-1"/>
    <col name="user" sort="alpha" sorted="+2"/>
    <col name="ip" sort="alpha"/>
  </block>
  <block name="taskbar" position="left" type="toolbar" display="" prev=""/>
  <block name="sysinfo" position="left" type="list" func="dashboard.sysinfo" enable_autoupdate="yes" prev="" display="">
    <toolbtn name="gotodetails" func="sysinfo" type="list"/>
  </block>
  <block name="software_info" position="left" type="software" func="dashboard.software" prev="" display="">
    <toolbtn name="gotodetails" func="feature" type="list"/>
  </block>
  <block name="changelog.changes" position="left" type="changelog" func="changelog.changes" rows="5" prev="" display="">
    <toolbtn name="gotodetails" func="changelog" type="list"/>
    <col name="desc" sorted="+1"/>
    <col name="type"/>
  </block>
  <block name="new_features" position="top" type="url" display="" prev="">
    <url>https://www.ispmanager.ru/sites/all/themes/custom/ispmanagertheme/ispmanageradv/ru6/?mgrurl=https://localhost:4200/ispmgr</url>
  </block>
  <messages name="dashboard" checked="3a604f5c3c6d5683f90a1f63f1d171aa">
    <msg name="actioncolumn">Действие</msg>
    <msg name="taskbar_admin">Администратор панели</msg>
    <msg name="taskbar_help">Помощь</msg>
    <msg name="taskbar_usrparam">Настройки пользователя</msg>
    <msg name="title">Главная</msg>
    <msg name="title_changelog.changes">Список изменений текущей версии 6.84.0</msg>
    <msg name="title_usageinfo">Использование времени</msg>
    <msg name="title_taskbar">Панель задач</msg>
    <msg name="hint_reload">Обновить данные</msg>
    <msg name="tip_dashboard_top">Вы можете создать администратора панели и перейти в него в одно нажатие (большинство задач по администрированию решается на уровне ее администратора)</msg>
    <msg name="title_new_features">Новые возможности</msg>
    <msg name="taskbar_adduser">Создать пользователя</msg>
    <msg name="taskbar_addwebdomain">Создать сайт</msg>
    <msg name="taskbar_addemail">Создать почтовый ящик</msg>
    <msg name="taskbar_adddomain">Создать домен</msg>
    <msg name="taskbar_shellclient">Запустить Shell-клиент</msg>
    <msg name="taskbar_addsorter">Настроить сортировщик</msg>
    <msg name="taskbar_responder_settings">Настроить автоответчик</msg>
    <msg name="taskbar_phpmyadmin">Открыть phpMyAdmin</msg>
    <msg name="taskbar_phppgadmin">Открыть phpPgAdmin</msg>
    <msg name="taskbar_roundcube">Открыть почтовый клиент</msg>
    <msg name="taskbar_adddatabase">Создать базу данных</msg>
    <msg name="taskbar_addemaildomain">Создать почтовый домен</msg>
    <msg name="taskbar_adddocker">Создать Docker контейнер</msg>
    <msg name="taskbar_addcron">Создать задание в Cron</msg>
    <msg name="taskbar_addbackup">Создать резервную копию</msg>
    <msg name="taskbar_addftp_user">Создать FTP-пользователя</msg>
    <msg name="taskbar_execute">Выполнить команду</msg>
    <msg name="taskbar_restart">Перезагрузить сервер</msg>
    <msg name="taskbar_update">Обновить панель</msg>
    <msg name="title_license.mgr.info">О панели Ispmanager Trial</msg>
    <msg name="title_capacity">Ресурсы сервера</msg>
    <msg name="title_session">Активные сессии</msg>
    <msg name="title_longtask">Фоновые задания</msg>
    <msg name="title_authlog">Журнал посещений</msg>
    <msg name="title_sysinfo">Информация о системе</msg>
    <msg name="title_software_info">Программное обеспечение сервера</msg>
  </messages>
  <blockOrder>{"3col":[["capacity","license.mgr.info","session"],["longtask","authlog","sysinfo"],["software_info","changelog.changes"]],"2col":[["capacity","license.mgr.info","session","longtask"],["authlog","sysinfo","software_info","changelog.changes"]]}</blockOrder>
  <tparams>
    <out>devel</out>
    <func>dashboard</func>
  </tparams>
  <saved_filters/>
</doc>

Элемент <block>

Пример XML блока

<block name="authlog" position="right" type="list" func="authlog" rows="5" enable_autoupdate="yes" prev="" display="">
  <toolbtn name="gotodetails" func="authlog" type="list"/>
  <col name="time" sort="alpha" sorted="-1"/>
  <col name="user" sort="alpha" sorted="+2"/>
  <col name="ip" sort="alpha"/>
</block>

атрибут name

Уникальное имя блока. Используется для идентификации блоков в рамках "главной страницы", а также для связки с языками.

атрибут type

Тип блока. Возможные значения:

toolbar

панель быстрых действий, всегда отображается вверху

list, report

список или график на основе списка, в данный момент оба значения обозначают один и тот же тип

url

HTML-баннер, контент для которого получается из заданного URL, всегда отображается вверху

isplicense, software, changelog

специализированные типы блоков для отображения информации о лицензии, версиях ПО и последних обновлениях, соответственно.

атрибут autoupdate

Задает таймаут обновления блока, в секундах

атрибут update

Задает обновление блока при переходе на дашборд

атрибут display

Указывает на состояние блока, принимает значения min/max - свернут/развернут

атрибут func

имя ф-ции, которую нужно позвать, чтобы получить контент блока. Актуально для типов list, report, isplicense, changelog, software

атрибут position

Не используется в теме dragon (используемой в данной момент в ispmanager), в теме orion - позиция блока, может принимать значения top, left, right

Описание блока быстрых действий (type="toolbar")

Пример XML блока

<block name="taskbar" position="top" type="toolbar">
  <toolbtn form="site.edit" img="d-site" name="addwebdomain" spritesvg="yes"/>
  <toolbtn form="wordpress.theme" img="d-wordpress" name="addwordpressdomain" spritesvg="yes"/>
  <toolbtn window="dashboard.phpmyadmin" img="d-phpmyadmin" name="phpmyadmin" spritesvg="yes"/>
</block>

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

Каждая кнопка описывается тегом <toolbtn> со следующими атрибутами:

window

если задан, то кнопка открывает новое окно (значение атрибута — имя функции)

top

наличие атрибута говорит о том, что надо позвать ф-цию из значения атрибута и обновить отображаемый UI панели (может использоваться для действий, которые добавляют новые пункты в меню и т.п.)

form

если задан, то кнопка открывает форму (значение атрибута — имя функции)

list

если задан, то кнопка открывает список (значение атрибута — имя функции)

img

имя иконки на кнопке, если атрибут spritesvg не задан, к имени в атрибуте img добавляется расширение .png и используется файл с таким именем в папке /usr/local/mgr5/skins/common/img; при spritesvg="yes" значение атрибута указывает на имя иконке в стандартном спрайте ispmanager

spritesvg

spritesvg="yes" указывает на то, что иконку нужно взять из стандартного SVG-спрайта ispmanager

customicon

путь до пользовательской svg-иконки в абсолютном или относительном виде. Относительный путь должен выглядить так: `/manimg/dragon/default/google.svg`, т.е. используется алиас `/manimg`, который ведет на папку `/skins`. Иконка может быть любых размеров и цветов, но в интерфейсе будет преобразована в одноцветную стандартного размера.

name

уникальное в рамках блока имя кнопки, предназначено для идентификации кнопки, а также для связи с языками

Локализация

См. "Описание сообщений локализации" в конце статьи

Описание блока-списка (type="list")

Пример описания блока-списка (type="list")

<block name="authlog" position="right" type="list" func="authlog" rows="5" enable_autoupdate="yes" prev="" display="">
  <toolbtn name="gotodetails" func="authlog" type="list"/>
  <col name="time" sort="alpha" sorted="-1"/>
  <col name="user" sort="alpha" sorted="+2"/>
  <col name="ip" sort="alpha"/>
</block>

Блок-список предназначен для описания списка (таблицы) данных или графика, построенного по таблице данных. Кнопки могут быть расположены в дополнительной колонке, в каждой строке.

Элемент <block type="list"> может содержать в себе 2 вида тегов: <col> (столбцы таблицы) и <toolbtn> (кнопки). 

Обратите внимание!
Обязательно должен быть один столбец (<col>) с атрибутом sorted. В противном случае не будет работать ограничение по количеству выводимых строк, заданное атрибутом rows.

Тег имеет дополнительные атрибуты:

атрибут func

имя функции (action'а), данные которого должны отобразиться в данном блоке

атрибут rows

ограничивает количество выводимых в блоке строк списка

Элемент toolbtn

Описывает кнопку.

атрибут type

Если задан type="list", кнопка будет отображаться внизу таблицы, в остальных случаях кнопка будет отображаться в каждой строке таблицы в последнем столбце.

атрибут func

Используется вместе с  type="list", задает функцию, которая должна быть вызвана при нажатии кнопки.

атрибут name

уникальное имя кнопки; должно соответствовать имени кнопки функции (action'а) — см. атрибут func у блока-списка.

Элемент col

Описывает столбец.

атрибут name

имя столбца; должно соответствовать имени столбца данных, передаваемых функцией, заданной атрибутом func элемента <block>.

Передача данных для блока-списка

Каждый блок с type="list" при отображении главной страницы (и при автообновлении, если оно включено для блока) делает отдельный HTTP-запрос вида GET MGR_URL?func=[функция блока]&dashboard=[имя блока], где функция и имя блока задаются атрибутами func и name элемента <block>. XML, возвращаемый такой функцией, соответствует общему формату XML-описаний страниц. В элементе <doc> получаемых данных должны содержаться элементы <elem> с данными для отображаемой в блоке таблицы аналогично тому, как передаются данные для страниц списков. Кроме того, в элементе <metadata> может содержаться элемент <band>, используемый для построения графика внутри блока на основе данных из элемента <reportdata> аналогично данным для страниц отчетов.

Описание блока-баннера (type="url")

Пример описания блока-баннера (type="url")

        <block name="journal" position="top" type="url">
               <url>https://ispsystem.com/journal?manager=__manager__</url>
        </block>

Блок-html предназначен для вставки произвольного html с указанного адреса. Содержит один тег: (адрес произвольного html).

Следует учитывать, что если в панель заходить по https, то браузер будет блокировать http адреса и https адреса с подозрительным сертификатом.

Описание блока с type="software"

Это список типа лейбл — значение, разделенный на группы. 

Скриншот:

Данные для отображения получаются запросом  GET MGR_URL?func=[функция блока]&dashboard=[имя блока], где функция и имя блока задаются атрибутами func и name элемента <block>.  

Пример XML для получаемых данных:

<doc lang="ru" func="dashboard.software">
  <metadata name="dashboard.software" type="infolist" mgr="ispmgr" dashboard="yes">
    <rowdata>
      <rowgroup name="soft">
        <row name="apache_version" type="data"/>
        <row name="mysql_version" type="data"/>
        <row name="php_version" type="data"/>
        <row name="kernel_version" type="data"/>
      </rowgroup>
    </rowdata>
  </metadata>
  <messages name="dashboard.software" checked="a5b30e8b989f395a98cadceb52f96ff9">
    <msg name="title">Программное обеспечение сервера</msg>
    <msg name="soft">Версии программного обеспечения</msg>
    <msg name="apache_version">Apache</msg>
    <msg name="mysql_version">MySQL</msg>
    <msg name="php_version">PHP</msg>
    <msg name="phpcgi_version">PHP (CGI)</msg>
    <msg name="perl_version">Perl</msg>
    <msg name="kernel_version">Kernel</msg>
    <msg name="short_gotodetails">Перейти в раздел</msg>
    <msg name="actioncolumn">Действие</msg>
  </messages>
  <elem>
    <apache_version>2.4.41-4ubuntu3.23</apache_version>
  </elem>
  <elem>
    <kernel_version>5.4.0-208-generic </kernel_version>
  </elem>
  <elem>
    <mysql_version>8.0.42-0ubuntu0.20.04.1</mysql_version>
  </elem>
  <elem>
    <php_version>7.4.3-4ubuntu2.29</php_version>
  </elem>
</doc>

Элемент rowgroup

Это группа элементов, объединенная какой-либо логикой

Атрибуты rowgroup

атрибут name

имя элемента, используется для локализации имени группы

Элемент row

Описывает строку.

Атрибуты row

атрибут name

имя элемента, используется для локализации подписи строки

Описание блока с type="isplicense"

Блок отображает информацию о действующей лицензии панели.  Данные для отображения получаются запросом  GET MGR_URL?func=[функция блока]&dashboard=[имя блока], где функция и имя блока задаются атрибутами func и name элемента <block>. 

Описание блока с type="changelog"

Блок отображает информацию об изменениях в последней версии панели.  Данные для отображения получаются запросом  GET MGR_URL?func=[функция блока]&dashboard=[имя блока], где функция и имя блока задаются атрибутами func и name элемента <block>.  

Описание сообщений локализации

Большинство сообщений dashboard'а подгружается автоматически по имени заданной функции при запросе к данным конкретного блока. Однако некоторые сообщения необходимо задавать в XML для функции dashboard, например в файле XML-описания плагина.

Пример описания сообщений

<messages name="dashboard">
  <msg name="title">Главная</msg>
  <msg name="title_taskbar">Панель задач</msg>
  <msg name="taskbar_usrparam">Настройки панели</msg>
  <msg name="taskbar_report">Журнал операций. Отчет</msg>
  <msg name="taskbar_brand">Настройки бренда</msg>
</messages>

msg name="title"

описывает заголовок главной страницы

msg name="title_[block]"

описывает наименование блока; [block] — имя блока (<block>)

msg name="[block]_[button]"

описывает надпись кнопки; [block] — имя блока (<block>), [button] — имя кнопки (<toolbtn>); используется для toolbar-блоков (например < msg name="taskbar_addwebdomain"> в стандартных быстрых действиях ispmanager для кнопки "Создать сайт" с name="addwebdomain" блока быстрых действий с name="taskbar"), для блоков-списков сообщения локализации для кнопок получаются в запросах по имени конкретной функции вместе с данными конкретного блока.

В этой статье