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

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

Введение

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

Содержимое "главной страницы" описывается при помощи xml-документа, который должен быть размещен в директории etc/xml. Формат имени файла имеет следующий вид: "имя менеджера" + "dashboard" + "уровень пользователя" + ".xml" (например, "core_dashboard_30.xml"). При первом доступе к "главной странице" в директории var/userconf/ создается файл конфигурации под именем следующего формата: "имя менеджера" + "." + "имя пользователя" + "." + "dashboard.xml" (например, "core.root.dashboard.xml"). Таким образом, каждый пользователь может иметь собственные настройки "главной страницы". При внесении изменений в xml "главной страницы" они автоматически учитываются в файлах конфигурации.

Если файл в etc/xml отсутствует, считается, что главная страница неактивна и, соответственно, в главном меню не отображается ссылка "Главная".

Обратите внимание!
Для блоков-списков обязательно должен присутствовать один столбец с атрибутом sorted. В противном случае не будет работать ограничение по количеству выводимых строк.

Описание XML

XML "главной страницы" должна содержать один или несколько элементов . Каждый блок описывает либо панель задач (toolbar), либо список.

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

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

<?xml version="1.0"?>
<doc>
        <block name="taskbar" position="top" type="toolbar">
                <toolbtn form="usrparam" img="mb-set" name="usrparam"/>
                <toolbtn list="journal.stat" img="t-credit" name="report"/>
                <toolbtn form="brand" img="t-credit" name="brand"/>
        </block>
        <block name="session" position="top" type="list" func="session" rows="5">
                <toolbtn name="kill"/>
                <col name="id"/>
                <col name="name" sort="alpha" sorted="+1"/>
                <col name="level"/>
                <col name="ip"/>
                <col name="idle"/>
        </block>
        <block name="journal" position="top" type="list" func="journal" rows="7">
                <toolbtn name="edit" type="edit"/>
                <col name="time" sort="alpha" sorted="-1"/>
                <col name="user"/>
                <col name="ip"/>
                <col name="funcname"/>
        </block>
        <block name="longtask" position="top" type="list" func="longtask" rows="5">
                <toolbtn name="view" default="yes"/>
                <toolbtn name="delete"/>
                <col name="name"/>
                <col name="queue"/>
                <col name="id"/>
                <col name="startdate"/>
                <col name="enddate"sort="alpha" sorted="-1"/>
                <col name="pidfile"/>
                <col name="status"/>
        </block>
</doc>

Общее описание блока "главной страницы"

Пример блока

        <block name="taskbar" position="top" type="list" func="journal" rows="7">
                <toolbtn name="edit" type="edit"/>
                <col name="time" sort="alpha" sorted="-1"/>
                <col name="user"/>
                <col name="ip"/>
                <col name="funcname"/>
        </block>

атрибут name

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

атрибут position

Описывает положение блока относительно других блоков.

Возможные значения:

top

сверху (блок растянут на две колонки)

left

в левой колонке

right

в правой колонке

На позицию блока также влияет расположение тега внутри xml-файла — чем выше блок, тем выше он будет отображен.

атрибут type

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

toolbar

панель управления

list

список

report

график

url

произвольный html

атрибут autoupdate

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

атрибут update

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

Описание блока панели управления (toolbar)

Пример блока панели управления (type="toolbar")

        <block name="taskbar" position="top" type="toolbar">
                <toolbtn form="usrparam" img="mb-set" name="usrparam"/>
                <toolbtn list="journal.stat" img="t-credit" name="report"/>
                <toolbtn form="brand" img="t-credit" name="brand"/>
        </block>

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

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

window

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

link

если задан, то кнопка переходит по url указанном в атрибуте

target

стандартный атрибут ссылки, используется совместно с link

top

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

form

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

list

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

img

имя "иконки"

name

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

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

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

        <block name="journal" position="top" type="list" func="journal" rows="7">
                <toolbtn name="edit"/>
                <col name="time" sort="alpha" sorted="-1"/>
                <col name="user"/>
                <col name="ip"/>
                <col name="funcname"/>
        </block>

Блок-список предназначен для описания списка (таблицы) данных. Содержит 2 вида тегов: (кнопки) и (столбцы таблицы).

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

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

атрибут func

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

атрибут rows

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

Элемент toolbtn

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

атрибут name

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

Элемент col

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

атрибут name

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

Описание блока-html (url)

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

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

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

В адресе можно использовать следующие макросы:

__manager__

Короткое имя панели (Например: core, ispmgr)

__version__

Версия панели

__os__

Операционная система (Например: Debian, FreeBSD, CentOS)

__arch__

Архитектура операционной системы

__os_version__

Версия операционной системы

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

Описание блока типа infolist

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

Скриншот:

XML:

<metadata name="dashboard.info" type="infolist" mgr="billmgr" dashboard="yes">
  <rowdata>
    <rowgroup name="acc_info">
      <row name="id" type="data"/>
      <row name="regdate" type="data"/>
      <row name="phone" type="data"/>
    </rowgroup>
    <rowgroup name="personal_account">
      <row name="provider" type="data"/>
      <row name="balance" type="link"/>
      <row name="annual_turnover" type="data"/>
    </rowgroup>
    <rowgroup name="service">
     <row name="services" type="indicator" view="brackets"/>
    </rowgroup>
  </rowdata>
</metadata>

<elem>
  <id>XXX</id>
  <regdate>2013-05-08</regdate>
  <phone/>
  <provider>FirstDEDIC</provider>
  <balance func="payment.add">0.0000 RUB</balance>
  <annual_turnover>0.0000 RUB</annual_turnover>
  <services_total>80</services_total>
  <services_used color="red">10</services_used>
</elem>

Элемент rowgroup

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

Атрибуты rowgroup

атрибут name

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

Элемент row

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

Атрибуты row

атрибут name

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

атрибут type

задает тип данных, может быть data, link, indicator

описание типов:

  • data — просто текст
  • link — ссылка на форму (имя ф-ции и elid задаются в атрибутами func и elid в элементе со значением для строки) или на внешний ресурс (ссылка задается в атрибуте url в элементе со значением для строки)
  • indicator — отображение вида 80 (10), первое число берется из ИМЯСТРОКИ_total, второе из ИМЯСТРОКИ_used, так же может иметь цвет задаваемый атрибутом color

атрибут view

только для типа indicator, если равно brackets отображать индикатор как 80 (10)

Описание сообщений

Большинство сообщений dashboard'а подгружается автоматически по имени заданной функции. Однако, для корректного отображения необходимо задать некоторые сообщения "вручную" в файле описания сообщений (например, mgr_msg_ru.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"

описывает заголовок dashboard'а

msg name="title_[block]"

описывает наименование блока; [block] — имя блока (); используется для toolbar-блоков, для блоков-списков сообщение подгружается автоматически по имени функции; если необходимо изменить заголовок блока-списка, его можно прописать здесь — такой заголовок имеет более высокий приоритет и именно он отобразится на "главной странице"

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

описывает надпись кнопки; [block] — имя блока, [button] — имя кнопки (); используется для toolbar-блоков, для блоков-списков сообщение подгружается автоматически по имени функции.

Общие рекомендации

COREmanager позволяет входить в систему, используя имя и пароль администратора сервера (суперпользователя). Но зачастую, большинство функций панели упревления доступно только пользователям с правами администратора. Поэтому, мы рекомендуем делать кнопку быстрого перехода в панель управления с правами администратора с главной страницы суперпользователя.