XML-описание интерфейсов

Введение

Описания форм, таблиц, меню и сообщения платформы хранятся в XML-файлах в каталоге /usr/local/mgr5/etc/xml и используют кодировку UTF-8. Платформа возвращает результат любой операции в формате XML.

Не рекомендуется изменять стандартные XML-файлы. Однако, вы можете:

создавать собственные формы и таблицы;
добавлять или убирать поля существующих форм с помощью механизма плагинов и событий.

Атрибуты позиционирования и доступа

Общие атрибуты элементов

Следующие атрибуты применимы к большинству элементов интерфейса:

if — определяет условие (Feature), при котором доступен элемент;
before — определяет, перед каким элементом должен быть размещён элемент. Платформа ищет элемент с совпадающим значением ключевого атрибута (обычно name) в текущем контексте;
after — определяет, после какого элемента должен быть размещён элемент. Аналогичен before;
first — размещает объект первым в списке. Допустимое значение — yes;
last — размещает объект последним в списке. Допустимое значение — yes;
level — уровень доступа для отображения элемента и связанных данных. Применяется внутри metadata и mainmenu. Скрытие элемента приводит к удалению связанных данных:
- для столбца таблицы (col) — удаляются данные в строках;
- для элементов данных (input, select, slider, textarea, text, htmldata) — удаляются соответствующие элементы верхнего уровня.
  Формат значения:
  - число от 0 до 31 — уровень доступа;
  - строка — имя уровня доступа или маски;
  - символ + после числа или строки означает, что доступ должен быть не ниже указанного. Строка должна быть именем уровня, а не маской.

В COREmanager существует ряд зарегистрированных имён с разным уровнем доступа:

nobody — уровень 0;
super — уровень 30;
admin — уровень 29;
reseller — уровень 24;
user — уровень 16;
all — маска "любой пользователь";
registered — маска "пользователь с доступом выше 0" (прошедший авторизацию).

Пример значений:

nobody+;
all;
0+.

Для элементов metadata и mainmenu алгоритм обработки атрибута level отличается:

для metadata атрибут level задаётся псевдонимом. Например, admin+ или registered;
для mainmenu атрибут level задаётся числом. Например, 29, 16, 8 и т.д.

Ключевые атрибуты

При загрузке данных из XML-файлов платформа объединяет одинаковые элементы. В этот момент объединяется содержимое элементов и их атрибуты. Одинаковыми считаются элементы:

находящиеся в одном контексте;
имеющие одинаковое имя;
имеющие одинаковое значение ключевого атрибута (если он есть). Для большинства элементов ключевым является атрибут name.

Исключения, которые никогда не объединяются:

toolsep;
jscript;
if;
else.

При загрузке XML-файлов платформа не меняет содержимое следующих элементов (анализ вложенных элементов не производится):

jscript;
func;
event;
query;
msg.

Метаданные (metadata)

Метаданные служат для описания элементов интерфейса платформы. Каждый элемент metadata описывает один элемент интерфейса. Атрибуты:

type –- тип элемента интерфейса. Может принимать значения:
- form — форма ввода;
- list — список данных;
- report — отчёт.
name — задаёт имя функции, которую описывает данный элемент;
helpurl — задаёт значение URL для ссылки "Помощь". Относится к тегу form внутри metadata ;
level — указывает, для каких пользователей доступен элемент интерфейса (функция, имя которой указано в атрибуте name). Формат значения атрибута описан в разделе Атрибуты позиционирования и доступа ;
secured — при значении yes данные скрываются в ответах при авторизации по cookie с неверным HTTP-заголовком Referer. Относится к любым элементам внутри metadata, чаще всего используется для поля ввода input внутри field:
Пример использования secured
```
<field name="password">
	<input name="password" type="password" required="yes" secured="yes"/>
</field>
```
readonly — относится к элементам внутри field. Применяется к элементам формы метаданных (например, input, select, textarea), а не к хранимым данным. Управляет редактированием поля в интерфейсе. Не влияет на запись значений в базу данных.

Подробнее об атрибутах формы см. статью Формы.

Чтобы установить атрибут, модифицируйте структуру формы в XML-файле одним из способов:

в XML-шаблоне:
Пример XML-шаблона
```
<input name="type" type="text" readonly="yes"/>
```
в коде:
Пример установки атрибута через объект ses.xml
```
ses.xml.GetNode("/doc/metadata/form//field/*[@name='type']").SetProp("readonly", "yes");
```

Элемент include

Дочерний элемент, который добавляет содержимое другого элемента metadata. Имя включаемого элемента должно быть указано в атрибуте name.

Правила обработки условий include при загрузке metadata:

элементы без префикса label_:
- условия (if, after, before, first, last) обрабатываются до объединения документов. Подробнее об условиях см. раздел Атрибуты позиционирования и доступа;
- порядок узлов изменяется перед объединением;
элементы с префиксом label_:
- условия обрабатываются после объединения документов.

Главное меню (mainmenu)

Главное меню COREmanager (mainmenu) использует двухуровневую структуру:

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

Пример структуры главного меню

<mainmenu level="30" startpage="session">
  <node name="srvset">
    <node name="product" action="product" type="list"/>
  </node>
  <node name="stat">
    <node name="session" action="session" type="list"/>
    <node name="journal" action="journal" type="list"/>
    <node name="longtask" action="longtask" type="list"/>
  </node>
  <node name="set">
    <node name="brand" action="brand" type="form"/>
    <node name="usermenu" action="usermenu" type="list"/>
    <node name="usrparam" action="usrparam" type="form"/>
  </node>
  <node name="mgrhelp">
    <node name="changelog" action="changelog" type="list"/>
    <node name="handbook" function="http://ru.example.com/index.php/core-handbook-30"/>
  </node>
</mainmenu>

Атрибуты mainmenu:

level — уровень доступа для меню;
startpage — имя страницы по умолчанию (функция из меню). Если не указан, используется первый доступный пункт.

Для меню атрибут level является ключевым. При формировании меню для уровня доступа объединяются все элементы mainmenu с этим уровнем.

Чтобы добавить элемент меню для всех уровней доступа, выполните команду:

Пример добавления пункта меню:

  <mainmenu level="registered">
    <node name="stat">
      <node name="mystat" first="yes"/>
    </node>
  </mainmenu>

Этот XML-код:

создаёт раздел stat, если его нет;
добавляет пункт mystat в раздел stat для пользователей всех уровней (level="registered");
делает mystat первым пунктом в разделе stat (first="yes").

Элемент `node`

Элемент node описывает:

пункт меню (без дочерних элементов);
раздел меню (с дочерними элементами node).

Атрибуты:

name — имя функции. Используется для вызова и локализации;
type — тип функции (list или form). Подставляется автоматически;
action — имя вызываемой функции. Копирует name. Подставляется автоматически;
function — URL для перехода. Подставляется автоматически для внешних функций.

Элемент меню handb ook обрабатывается особым образом. При наличии элемента handbook:

Вызывается функция help с параметрами:
- topic=handbook
- level=<текущий уровень доступа>
Возвращённый URL подставляется в атрибут function.

Описание языков и переводы (lang)

Элемент lang описывает переводы для языка. Например, описание сообщений COREmanager на английском языке в файле core_msg_en.xml будет выглядеть следующим образом:

Пример описания надписей COREmanager

  <lang name="en">
    <messages name="label_langs">
      <msg name="bg">Български</msg>
      <msg name="cn">汉语</msg>
      <msg name="cs">Český</msg>
      <msg name="de">Deutsch</msg>
      <msg name="en">English</msg>
      <msg name="es">Español</msg>
      <msg name="fi">Suomi</msg>
      <msg name="fr">Français</msg>
      <msg name="hu">Magyar</msg>
      <msg name="jp">日本語</msg>
      <msg name="ku">کوردی</msg>
      <msg name="nl">Nederlands</msg>
      <msg name="pl">Polski</msg>
      <msg name="pt">Português</msg>
      <msg name="ru">Русский</msg>
      <msg name="th">ภาษาไทย</msg>
      <msg name="ua">Українська</msg>
      <msg name="xx">Developer</msg>
      <msg name="zh">中文</msg>
    </messages>
    <messages name="usrparam">
      <include name="label_langs"/>
      <msg name="addr">Allowed IP-addresses</msg>
      <msg name="atallow">allow for listed IP-addresses</msg>
      <msg name="atany">allow for any IP-address</msg>
      <msg name="atype">Access to the control panel</msg>
      <msg name="button">Icons</msg>
      <msg name="buttontext">Icons and captions </msg>
      <msg name="buttonview">Toolbar view</msg>
      <msg name="confirm">Re-enter password</msg>
      <msg name="email">E-mail for notifications </msg>
      <msg name="hint_rows">Enter the number of rows per page that will be displayed by default</msg>
      <msg name="hint_startpage">Select a page that will be displayed once you log in to the control panel</msg>
      <msg name="hint_theme">Select the theme that will be used to display the control panel</msg>
      <msg name="hint_timezone">Select the time zone for your region </msg>
      <msg name="lang">Language</msg>
      <msg name="msg_error_notuniqueemail">The selected e-mail is already used </msg>
      <msg name="msg_passwd">Password do not match!</msg>
      <msg name="name">Username</msg>
      <msg name="password">Password</msg>
      <msg name="recordlimit">Number of records </msg>
      <msg name="rows">Rows per page</msg>
      <msg name="startpage">Start page</msg>
      <msg name="text">Text</msg>
      <msg name="theme">Theme</msg>
      <msg name="timezone">Time zone</msg>
      <msg name="title">General settings</msg>
      <msg name="title_new">General settings</msg>
    </messages>
  </lang>

Атрибут name содержит код описываемого языка. Например: en, fr, ru, es.

Элемент `messages`

Описывает сообщения для определённой функции. Атрибут name содержит имя функции.

Элемент msg

Содержит текст сообщения. Не имеет дочерних узлов. Атрибут name задаёт имя сообщения.

Элемент include

Импортирует сообщения из другой секции. Атрибут name указывает имя секции.
В COREmanager существует ряд специальных секций messages. Они используются несмотря на то, что значению их атрибута name не соответствует ни одной функции:

alert — сообщения для баннеров;
common — общие сообщения;
msgerror — описания ошибок;
form — сообщения для форм и отчётов;
list — сообщения для списков и отчётов;
report — сообщения для отчётов.

Подсказки (hint)

Всплывающие подсказки для элементов интерфейса определяются в локализованных сообщениях. Имена таких сообщений начинаются с префикса hint_.

Особенности подсказок:

поддерживают HTML-разметку;
теги должны быть валидными XML-элементами.

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

Ссылка в подсказке

<msg name="hint_multiselect">Можно выбрать более одного <a href="http://ru.5.ispdoc.com/" target="_blank">элемента</a></msg>

Чтобы выделить важный текст цветом, используйте команду:

Пример текста

<msg name="hint_multiselect">Можно выбрать <span style="color:red;">более</span> одного элемента</msg>

Чтобы записать HTML-теги, используйте следующие варианты:

с использованием CDATA:

Пример записи тегов

<msg name="hint_color">Я <![CDATA[<font color="yellow">желтого</font>]]> цвета</msg>

с экранированием спецсимволов. Чтобы использовать этот вариант, замените:
- < на <
- > на >
Пример записи тегов
```
<msg name="hint_link">Я &lt;a href="https://ya.ru"&gt;ссылка&lt;/a&gt;</msg>
```

Внешние обработчики (handler/library)

COREmanager предоставляет механизм для изменений в поведении системы. Платформа позволяет интегрировать пользовательскую логику через:

внешние обработчики (любой язык программирования);
библиотеки на C++ (shared libraries).

Элемент handler

Для описания внешних обработчиков используется элемент handler:

Пример использования внешнего обработчика

<mgrdata>
  <handler name="lastlogin" type="cgi" ignore_errors="yes">
      <event name="auth" after="yes"/>
  </handler>
</mgrdata>

Атрибуты handler:

name — имя исполняемого файла в каталоге addon;
type — тип взаимодействия обработчиком. Возможные значения:
- cgi — обработчик вызывается с использованием интерфейса CGI. Он получает данные через переменные окружения и POST. Результат объединяется с ответом платформы;
- xml — обработчик получает данные через переменные окружения и POST, дополнительно получает текущий XML-ответ. Результат полностью заменяет ответ платформы;
ignore_errors — при значении "yes" ошибки обработчика не влияют на работу платформы. Необязательный параметр. Применяется только к тем обработчикам, для которых указан.

Элемент event указывает существующую функцию, при вызове которой срабатывает обработчик.

Элемент func создаёт новую функцию платформы. Логика полностью реализуется обработчиком.

Элемент library

Загружает пользовательскую библиотеку из каталога lib:

Пример вызова библиотеки

<mgrdata>
  <library name="test"/>
</mgrdata>

Обработчики событий (элемент event)

COREmanager позволяет не только добавлять собственные обработчики для событий, но и определять порядок их вызова. Для этого у элемента event существует ряд атрибутов:

priority — определяет порядок вызова обработчика. Может принимать значения:
- before — обработчик будет вызван до базового;
- after — обработчик будет вызван после базового (см. атрибут base);
base — задаёт имя базового обработчика, относительного которого определён порядок атрибутом priority. Если базовый обработчик не задан, то при @priority=before обработчик будет добавлен в начало очереди, а при @priority=after — в конец.

Даже если вы указали, что ваш обработчик необходимо вызывать первым/последним или до/после какого-то другого обработчика, это не гарантирует того, что он действительно будет занимать в очереди указанную позицию. Например, если есть несколько обработчиков с priority="before", они будут выполнены до всех остальных, в порядке, обратном порядку их создания (последний созданный будет первым). Если порядок отличается от ожидаемого, нужно явно указать, после или перед каким обработчиком необходимо выполнить желаемый.

Если обработчика, указанного в атрибуте base, не существует, значение атрибута игнорируется.

Кеширование

Платформа не работает с исходными XML-файлами напрямую. Она использует двухуровневую систему кеширования для оптимизации обработки метаданных.

Уровень 1. Предварительное кеширование

Первый этап состоит из следующих шагов:

Объединение всех XML-документов согласно правилам.
Разделение на отдельные файлы (по одному metadata или messages в файле)
Сохранение полученных файлов в каталогах:
- var/.xmlcache/<manager>.0
- var/.xmlcache/<manager>.1
Создание символической ссылки var/.xmlcache/<manager>, которая указывает на активный каталог. Второй каталог используется для предварительного кеширования. Операция выполняется следующими командами:
Пример команды
```
# кеширование метаданных
sbin/xmlinstall --manager <manager> --meta-cache [--apply]
# кеширование сообщений
sbin/xmlinstall --manager <manager> --lang-cache ru --base en [--apply]
```

Параметр --apply активирует изменения в каталоге, с которым в данный момент работает платформа, без перезапуска.

Уровень 2: Финализация кеша

Второй этап состоит из следующих шагов:

Обработка директив include.
Реорганизация узлов.
Добавление недостающих сообщений из других модулей.
Результат сохраняется в каталоге var/.xmlcache/<manager>.X/checked

Результат перестраивается:

в случае изменения набора возможностей (feature) платформы;
при полной перестройке кеша.

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

Предварительное кеширование

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

Пример команды

sbin/xmlinstall --manager <manager> --recache [--apply]

Где — имя используемого продукта. Например, billmgr

В этом случае:

рядом с текущим создаётся новый каталог кеша. Если используется каталог <manager>.0, будет создан каталог <manager>.1 и наоборот;
платформа при запуске проверяет оба каталога, и, если один из них содержит актуальные данные, делает его активным;
параметр --apply активирует изменения в каталоге, с которым в данный момент работает платформа, без перезапуска;
часть данных (например, информация об уровне доступа) платформа читает из XML-файлов только на старте;
чтобы применить все изменения, требуется перезапуск платформы.

Может быть полезно

Связанные статьи:

Дата последнего обновления статьи: 18.08.2025. Статья подготовлена техническими писателями ISPsystem

XML-описание интерфейсов

Введение

Атрибуты позиционирования и доступа

Общие атрибуты элементов

Ключевые атрибуты

Метаданные (metadata)

Элемент include

Главное меню (mainmenu)

Элемент node

Описание языков и переводы (lang)

Элемент messages

Элемент msg

Элемент include

Подсказки (hint)

Внешние обработчики (handler/library)

Элемент handler

Элемент library

Обработчики событий (элемент event)

Кеширование

Уровень 1. Предварительное кеширование

Уровень 2: Финализация кеша

Предварительное кеширование

Элемент `node`

Элемент `messages`