Элемент интерфейса типа list используется в платформе для табличного вывода объектов с возможностью массовой и поэлементной обработки. Данные и визуальная структура задаются через XML-элементы coldata и toolbar, а поведение списка управляется атрибутами metadata. В статье приведена полная спецификация атрибутов, форматов ячеек и логики отображения под учётной записью клиента.
Элемент metadata
Атрибуты metadata задают ключевое поле и поле с сообщением для подтверждения групповых операций.
<xml>
<metadata type="list" key="mgr" keyname="name">
...
</metadata>
</xml>Атрибуты metadata
Примечание: поля с ключевыми элементами могут быть недоступны для пользователя (может отсутствовать в coldata ).
Элемент coldata
Элемент coldata содержит элементы col, описывающие колонки таблицы.
<xml>
<coldata>
<col name="name" type="data" sort="alpha"/>
<col name="intname" type="data" sort="alpha"/>
<col name="orderpriority" type="data" sort="digit" edit="itemtype.edit"/>
</coldata>
</xml>Элемент col
Элемент col описывает колонку таблицы: тип данных, сортировку, ширину и т. д.

Атрибуты элемента col
Локализация
Заголовок колонки берётся из локализованных сообщений по имени колонки.
Подробное описание (подсказка) берётся из локализованных сообщений по имени колонки с префиксом hint_.
Типы данных колонки
Данные в колонке могут быть нескольких видов. Определяются явно атрибутом @type, неявно — наличием элементов prop, xprop или @sort=prop.
Тип данных data или msg
Тип data задаётся атрибутом @type со значением data или msg. Различия между ними — в источниках данных (локализованные сообщения или нет), но это обрабатывает платформа. Разработчику всегда нужно брать данные из элемента elem.
Каждой строке таблицы соответствует элемент elem .В нём содержатся значения для каждой колонки. Для типа data значения берутся из элементов с названием, совпадающим с названием колонки.
Элемент elem может иметь дополнительные данные:
@color— цвет строки.
<xml>
<doc ...>
...
<elem>
<mgrname>core</mgrname>
<name>COREmanager</name>
<version>5.8.0-30.07.13_14:10_IRKT</version>
<installed>on</installed>
<avail_version>alpha (5.7.1-24.07.13_15:36_IRKT)</avail_version>
<descr>Ядро программного комплекса</descr>
</elem>
<elem>
<mgrname>dnsmgr</mgrname>
<name>DNSmanager</name>
<installed>off</installed>
<avail_version>beta (5.880.1), alpha (5.0.11-23.07.13_10:42_IRKT)</avail_version>
<descr>Панель управления сервером DNS</descr>
</elem>
...
</doc>
</xml>Тип данных indicator
Тип данных задаётся атрибутом @type. Отображает:
- лимит;
- текущее значение;
- полоску с процентным соотношением текущего значения к лимиту.
Также может быть представлен в виде двух чисел, одно из которых заключено в скобки. В этом случае у элемента есть атрибут @view=brackets.
@view=brackets поддерживается только на дашборде.

Значение лимита берётся из элемента, который находится в elem с именем, соответствующим имени колонки с постфиксом _total; текущее значение — с постфиксом _used.
<xml>
<doc ...>
...
<elem>
<indicator_total>255</indicator_total>
<indicator_used>101</indicator_used>
...
</elem>
<elem>
<indicator_total>255</indicator_total>
<indicator_used>82</indicator_used>
...
</elem>
...
</doc>
</xml>Тип данных prop
ТТип данных prop содержит в себе свойстваип данных и задаётся через атрибут @sort=prop или элементы prop или xprop в элементе col. Представляет собой строку с иконками.

prop
Иконка свойства отображается в строке, если в elem присутствует элемент, совпадающий с именем свойства.
xprop
Расширенный prop, отображение которого зависит от значения в элементе. Иконка свойства отображается в строке, если в elem присутствует элемент, совпадающий с именем свойства, а значение элемента совпадает со значением атрибута @value. Если атрибут @value отсутствует, xprop отображается по умолчанию, когда значение поля не совпадает с @value других элементов xprop с тем же именем. То есть тип работает как prop, кроме случая, когда xprop с таким же именем уже показан.
Атрибуты элемента prop/xprop
Локализация prop
Подробное описание (подсказка) берётся из локализованных сообщений по имени свойства с префиксом hint_p_. Если в сообщении есть макрос __value__, нужно заменить его на значение из элемента.
Локализация xprop
Подробное описание (подсказка) при наличии локализованного сообщения с именем hint_p_<@name>_<@value> берётся из него. Иначе — из hint_p_<@name>. Если в сообщении есть макрос __value__, нужно заменить его на значение из элемента.
Смешанный тип prop + data
При наличии у col типа data и элементов prop или xprop свойства нужно показать перед текстом. Всё остальное аналогично типам data и prop или xprop.

Тип данных card
Тип card задаётся атрибутом @type со значением card. Ячейка становится ссылкой с кнопкой свёртывания. При нажатии раскрывается карточка списка с определённым контентом.
Тип отображаемого контента задаётся в атрибуте @card_content_type на колонке. Данные для карточки могут быть загружены как синхронно, так и асинхронно. Параметры для асинхронной загрузки данных задаются атрибутом @card_parameters на колонке.

Атрибуты элемента колонки card
Карточки внутри списка
Внутри таблицы есть возможность отобразить карточки между строками. Условием для открытия карточки служит ячейка в колонке с типом card. Задание типа карточки происходит в колонке.
Данные для карточки можно задать двумя способами:
- в случае синхронного предоставления данных они располагаются внутри данных ячейки в теге
card_data; - в случае асинхронной загрузки данных параметры задаются в
@card_parameters, и данные приходят в корневом элементе документа (<doc>).
На данный момент существует только один тип карточки — service-stat.
Тип карточки service-stat
Данный тип предназначен для отображения информации о потреблении ресурсов услуг.
Пример отображения карточки service-stat в dragon.
Данные для такой карточки содержатся в корневом элементе документа в тегах elem. Внутри elem содержатся следующие теги:
Также имеется возможность добавить prop для внутренних ячеек. Для этого prop указывается в корне документа с дополнительным атрибутом @col, в котором указывается название колонки, в которой должен показываться проп. Значение prop приходит внутри elem по его названию. Атрибуты prop совпадают с обычными props.
Текстовым ячейкам (name, stat, overspend) можно задать подсказку с помощью атрибута @hint. Значение атрибута соответствует ключу в локализованных сообщениях.
<xml>
<doc ...>
<prop col="overspend" name="overspending" func="service-stat" type="groupform" img="arrow-up-right-circle" sprite="yes" spritesvg="yes"></prop>
<elem>
<elid>3</elid>
<name>Название ресурса</name>
<stat>150 из 100 МБ</stat>
<progress color="red">150%</progress>
<overspend>
<link internal="yes" href="func=service-stat&clid=3&elid=10">50 МБ | 1 234 Р</link>
</overspend>
<overspending>Перерасход за (месяц) (год): 1 234 Р</overspending>
</elem>
...
</doc>
</xml>Редактирование в списке
Наличие у колонки атрибута @edit означает, что значение ячейки можно отредактировать без открытия формы редактирования элемента.

В атрибуте передаётся имя функции формы, которую нужно вызвать, чтобы получить элемент управления для этого значения, а затем сохранить его.
Для получения формы на сервер отправляется запрос с параметрами:
func— имя функции из атрибута@edit;colname— имя колонки, в которой расположена ячейка;tablename— функция списка;elid— идентификатор редактируемого элемента;plid— идентификатор родительского списка (при наличии);stylesheet— укажите значениеeditinlist.
В ответ придёт полная форма редактирования элемента, к которой применён шаблон editinlist.xsl. Для отображения формы используется поле, название которого совпадает с названием колонки ячейки. При редактировании значения ячейки могут использоваться только следующие элементы управления:
input[type=text][zoom, unlimit, date];select;select[type=radio];slider;textarea.
При формировании запроса на сохранение включите все поля формы, в том числе скрытые поля input[type=hidden]. В ответе могут быть возвращены новые значения elid и elname (текстовое значение при подтверждении), если новое значение elid не совпадает со старым. В таком случае необходимо заменить elid для дальнейшего редактирования элемента.
Ошибки отображаются в виде уведомлений. Например, можно показать уведомление с текстом ошибки — элемент error в ответе на редактирование.
Сортировка колонок
Атрибут @sort у элемента col включает возможность сортировки по колонке. Атрибут @sorted показывает направление сортировки и порядок колонки в сортировке. Например:
- +1 — первая колонка в сортировке, отсортирована по возрастанию;
- -2 — вторая колонка в сортировке, отсортирована по убыванию.
Сортировка происходит на стороне сервера. Сортировка может быть по нескольким колонкам. Колонки в сортировку добавляются при клике по колонке с зажатым CTRL.
Параметры, добавляемые к запросу для управления сортировкой:
p_current— текущее состояние сортировки: имя отсортированных колонок с направлением сортировки в порядке сортировки (значение атрибута@sorted), через запятую. Например:-time,+user;p_col— колонка, по которой кликнули: имя колонки и текущая сортировка из атрибута@sorted. Например:+time— колонка была отсортирована по возрастанию;-time— колонка была отсортирована по убыванию;time— колонка не была отсортирована.
При клике без CTRL отправляется пустой p_current и p_col — колонка, по которой кликнули.
При клике с CTRL отправляется текущее состояние сортировки p_current и p_col — колонка, по которой кликнули.
Сортировка типа alpha
Сортировка по алфавиту.
Сортировка типа calpha
Регистронезависимая сортировка по алфавиту.
Сортировка типа digit
Сортировка в порядке числового возрастания. Числа могут быть как целыми, так и дробными, как положительными, так и отрицательными. Поле может принимать не только числа, поэтому перед сортировкой нужно убрать всё лишнее и сортировать только по числам.
Сортировка типа indicator
Сортировка для колонок с индикаторами. Как числовая, только по текущему значению _used.
Сортировка типа ip
Сортировка IP-адресов. Могут быть как ipv4, так и ipv6.
Сортировка типа prop
Сортирует prop или xprop по их наличию. То есть для каждой строки строится число вида 010101, и потом происходит сравнение. Если у свойства есть атрибут @sort=no, то это свойство не участвует в сортировке. Если колонка имеет смешанный тип (prop + data), то при одинаковых свойствах также происходит сортировка текста по алфавиту.
Сортировка типа version
Сортировка по версиям, разделённым символами ., _, -.
Сортировка типа natural
Сортировка, учитывающая числовые последовательности в строках. В отличие от алфавитной сортировки (alpha), числа сравниваются по значению, а не посимвольно. Например, последовательность файл1, файл2, файл10 при natural будет отсортирована корректно: файл1, файл2, файл10, тогда как при alpha порядок будет файл1, файл10, файл2. Применяется для имён файлов, версий с суффиксами и других строк, содержащих числа.
Сортировка типа file
Специализированная сортировка для файловых менеджеров. Элементы сортируются в алфавитном порядке, при этом директории всегда выводятся перед файлами. Применяется только в сочетании с типом данных prop или xprop, когда колонка отображает иконки файлов или папок.
Страничная навигация
При наличии большого количества элементов в списке список разбивается на страницы. Определить количество страниц можно по количеству элементов page в корне XML-файла. При количестве страниц более одной следует показать элемент постраничной навигации (пейджер).
page может отсутствовать в корневом элементе XML-файла. Элемент постраничной навигации следует отображать при наличии атрибутов p_elems, p_cnt, p_num и условии p_elems > p_cnt (элементов больше, чем помещается на одной странице).
<xml>
<doc...>
...
<p_sort>time</p_sort>
<p_order>asc</p_order>
<p_cnt>50</p_cnt>
<p_num>1</p_num>
<p_elems>352</p_elems>
...
</doc>
</xml>При страничной навигации предполагается поле для ввода количества элементов на странице. Значение по умолчанию передаётся в элементе p_cnt.
Для получения выбранной пользователем страницы нужно к запросу списка добавить параметр p_num с номером страницы, p_sort — значение из элемента p_sort, p_order — значение из элемента p_order, p_cnt — значение из p_cnt или заданное пользователем.
Локализация
Сообщение "Показать" берётся из локализованных сообщений с именем pagershow.
Сообщение "Строк на страницу" берётся из локализованных сообщений с именем pagerline.
Строка состояния
Если элемента col содержит атрибут @total, в строке состояния выводится статистика по соответствующему столбцу. Аттрибут поддерживается только для колонок с числами, индикаторами или свойствами.
Пример строки состояния в dragon.
Поведение строки состояния
Данные в строке состояния зависят от количества выделенных элементов таблицы. Если в списке нет выделенных элементов, отображается значение атрибута @total. При выделении строк система вычисляет и выводит сумму значений только для отмеченных элементов.
Для колонки со свойствами в строке должны быть отражены иконки с количеством.
Предполагается, что под первой колонкой показано общее количество элементов (из элемента p_elems), а при выделении строк — показано количество выделенных строк.
Если у числа есть суффикс, например ("EUR", "RUB", "USD" ...), то сумма должна считаться отдельно по этим суффиксам и выводиться через ;.

Если колонка имеет атрибут convert="money", то итоги нужно выводить в формате 100 000.00.
Локализация
Сообщение Всего берётся из локализованных сообщений главного меню с именем msg_total.
Сообщение Выделено берётся из локализованных сообщений главного меню с именем msg_selected.
Раскраска текста и фона строки
Если элемент elem имеет атрибут @color, укажите фон строки в заданный атрибутом цвет. Доступные значения:
red;green;blue;yellow;cyan.
Если элемент с данными поля имеет атрибут @color, укажите цвет текста строки с помощью атрибута. Доступные значения:
red;green;blue;yellow;cyan.

<xml>
<doc>
...
<elem color="red">
<line_color>red</line_color>
<text_color_1 color="red">red</text_color_1>
<text_color_2 color="yellow">yellow</text_color_2>
<text_color_3 color="yellow">yellow</text_color_3>
<text_color_4 color="blue">blue</text_color_4>
<text_color_5 color="red">red</text_color_5>
<text_color_6 color="green">green</text_color_6>
<text_color_7 color="yellow">yellow</text_color_7>
</elem>
...
</doc>
</xml>Внутренние ссылки
Для отображения ссылок внутри ячейки можно прислать тег link внутри тега ячейки.
<xml>
...
<metadata>
...
<coldata>
<col name="id" type="digit"/>
<col name="bundle" type="data"/>
<col name="account" type="data"/>
<col name="project" type="data"/>
<col name="status" type="msg"/>
<col name="cost" type="data"/>
<col name="items" type="list"/>
</coldata>
...
</metadata>
<elem>
<id>1</id>
<bundle>Первый набор, минимальная настройка</bundle>
<account>Уткин N7x6V7r7N8 (cl8@test.com)</account>
<project>Провайдер</project>
<status color="green">Активен</status>
<cost>184260.75 RUB</cost>
<items>
<link internal="yes" newtab="yes" href="func=test_tp">20084
</link>
<link internal="yes" newtab="yes" href="func=test_tp">20085
</link>
<link internal="yes" newtab="yes" href="func=test_tp">20101
</link>
<link internal="yes" newtab="yes" href="func=test_tp">20103
</link>
...
</items>
</elem>
...
</xml>
Настройка таблицы и экспорт в csv
У каждой таблицы есть форма настроек, где можно задать колонки, сортировку, количество элементов на страницу. Чтобы вызвать эту форму, вызовите функцию tsetting с параметрами:
elid— имя функции списка;plid— все параметры, с которыми вызывался список.
Чтобы экспортировать список в файл в формате .csv, добавьте к параметрам запроса out=csv.
Чтобы экспортировать список для печати, добавьте к параметрам запроса out=print.

Локализация
Подробное описание настроек таблицы (подсказка) берётся из сообщений локализации с именем msg_tsetting.
Подробное описание экспорта в .csv (подсказка) берётся из сообщений локализации с именем hint_export.
Настройка ширины колонок в таблице
Предполагается, что можно регулировать ширину колонок таблицы. При регулировке ширины колонок нужно отправить запрос платформе для сохранения ширины, заданной пользователем. Для этого нужно вызвать функцию colwidth. В параметрах нужно передать имена колонок и их размер (предполагается, что размер в процентах; в них же он будет применён к элементу col) без знака %, а также нужен параметр elid — имя функции списка.
id=6&name=18&user=12&host=17&pool=11&size=10&attached=25&func=colwidth&out=xml&elid=volumeФильтр
Во многих списках существует фильтр, с помощью которого можно отфильтровать строки в списке. Когда фильтр применён, нужно отобразить это в таблице, а также нужна кнопка для его снятия.
Сообщение с параметрами применённого фильтра передаётся в элементе p_filter .Для снятия фильтра нужно вызвать функцию фильтра (её можно взять из @func элемента toolbtn с @name=filter) с параметром drop=on и перезагрузить список.

<xml>
<doc...>
...
<p_filter>Логин ~ admin, Уровень доступа = Администратор</p_filter>
...
</doc>
</xml>Если вы хотите выводить иконки фильтра, нужно проверять значения формы на непустые поля, select, не равный '*', и checkbox, не равный 'off'.
Быстрый фильтр по списку
Быстрый фильтр по списку даёт возможность применить фильтр по текущему значению ячейки таблицы списка.

Быстрый фильтр применяется для колонки, если:
- у колонки есть атрибут
@fastfilter; - в фильтре есть
select,и в списке есть соответствующая ему колонка.
Баннеры
В списках могут быть показаны баннеры. Баннеры — это информационные сообщения. Могут быть трёх типов: ошибка, предупреждение и совет или информация. У баннера могут быть две ссылки: Скрыть и Подробнее.
Тип баннера (атрибут @status) задаёт цвет баннера:
- ошибка — красный;
- предупреждение — жёлтый;
- совет или информация — зелёный.
Сообщение баннера передаётся в элементе msg. Если у баннера нет атрибута @pinned="yes", то баннер должен быть отображён в виде всплывающего уведомления.

<xml>
<doc...>
...
<banner id="table_status_lastlogin" status="3">
<param name="date">2013-08-01 11:07:31</param>
<param name="ip">188.120.252.26</param>
<msg>Последний раз вы заходили в панель: 2013-08-01 11:07:31, с IP-адреса: 188.120.252.26</msg>
</banner>
...
</doc>
</xml>
<xml>
<doc...>
...
<banner id="table_status_lastlogin" status="3">
<param name="date">2013-08-01 11:07:31</param>
<param name="ip">188.120.252.26</param>
<msg>Последний раз вы заходили в панель: 2013-08-01 11:07:31, с IP-адреса: 188.120.252.26</msg>
</banner>
...
</doc>
</xml>Атрибуты элемента banner
Поведение баннеров
Ссылка Скрыть скрывает баннер, а также отправляет запрос платформе о том, что пользователь скрыл баннер и его можно больше не показывать. Нужно вызвать функцию dismiss с параметром id из атрибута @id. Если есть атрибут @infoelid, его значение нужно передать в параметре elid.
Ссылка Подробнее может открывать список, форму или URL. Если @infotype равен url или help, нужно открыть URL из значения атрибута @info. Если @infotype равен func или formfunc, нужно открыть список или форму. Имя функции будет передано в атрибуте @info, а если задан атрибут @infoelid, то его нужно передать параметром elid.
Баннер с ошибкой при групповой операции
При выполнении групповой операции может произойти ошибка. В XML с ответом будет баннер и, возможно, элементы warning с элементами, вызвавшими ошибку.
Нужно отобразить баннер в списке, выделить элементы из warning (идентификатор элемента задаёт атрибут @elid), отобразить иконку с ошибкой и подробным сообщением (берётся из элемента msg).

<xml>
<doc>
<warning elid="1973">
<error type="account_delete_expense" lang="ru">
<param name="group_id">1973</param>
<stack>
<action level="29" user="admin">account.delete</action>
</stack>
<group>Удаление клиентов с ненулевыми расходами запрещено</group>
<msg>Удаление клиентов с ненулевыми расходами запрещено</msg>
</error>
</warning>
<warning elid="1962">
<error type="account_delete_payment" lang="ru">
<param name="group_id">2546</param>
<stack>
<action level="29" user="admin">account.delete</action>
</stack>
<group>Удаление клиентов с зачисленными платежами запрещено</group>
<msg>Удаление клиентов с зачисленными платежами запрещено</msg>
</error>
</warning>
<banner id="groupfail_delete" status="1">
<param name="count">94</param>
<msg>Не удалось удалить 94 элемент(-а,-ов). Для получения подробностей наведите курсор на значок ошибки в строке таблицы.</msg>
</banner>
<ok/>
</doc>
</xml>Баннер с формы
В ответе на отправку формы может быть баннер. Его нужно отобразить в дочернем списке.
Элемент toolbar
Элемент toolbar содержит в себе элементы toolgrp (группы кнопок), которые содержат в себе элементы toolbtn, описывающие кнопки операций над элементом.

<xml> <metadata type="list">
<toolbar>
<toolgrp name="one">
<toolbtn type="new" name="new" func="spec.list_a.edit" img="t-new" sprite="yes"/>
<toolbtn type="edit" name="edit" func="spec.list_a.edit" img="t-edit" sprite="yes"/>
<toolbtn type="groupform" name="groupedit" func="spec.list_a.groupedit" img="t-project" sprite="yes"/>
<toolbtn type="group" name="delete" func="spec.list_a.delete" img="t-delete" sprite="yes"/>
</toolgrp>
<toolgrp name="two">
<toolbtn type="editlist" name="sublist" func="spec.sublist_a" img="t-editlist" sprite="yes"/>
<toolbtn type="window" name="window" func="void" img="t-invoice" sprite="yes"/>
<toolbtn type="list" name="list" func="spec.list_refresh" img="t-liststart" sprite="yes"/>
<toolbtn type="new" name="void" func="void" img="t-mime" default="yes" sprite="yes"/>
<toolbtn type="refresh" name="refresh" func="spec.list_a" img="t-retry" sprite="yes"/>
<toolbtn type="new" name="admin" func="admin" img="t-users" sprite="yes"/>
</toolgrp>
<toolgrp name="tree">
<toolbtn type="group" name="setnull" func="spec.list_a.setnull" img="t-discount" sprite="yes">
<hide name="text" value="hello"/>
<hide name="admintext" value="hallo"/>
</toolbtn>
<toolbtn type="group" name="randomize" func="spec.list_a.randomize" img="t-iplist" sprite="yes">
<show name="admintext" value="hallo"/>
</toolbtn>
<toolbtn type="new" name="filter" func="spec.list_a.filter" img="t-filter" sprite="yes"/>
</toolgrp>
</toolbar>
</metadata> </xml>Элемент toolgrp
Содержит в себе кнопки, объединённые общей логикой. В случае если кнопки не помещаются в допустимую для них область, они должны сворачиваться в группы.
Атрибуты элемента toolgrp
Атрибуты элемента toolbtn
Общее описание поведения кнопок
Кнопки имеют два состояния: активна и не активна. Состояние задаётся типом кнопки и условиями hide или show. Кнопка может быть скрыта по условию remove.
По нажатию кнопки могут быть открыты:
- список;
- форма;
- URL-адрес;
- окно подтверждения операции.

Типы кнопок
Активация/деактивация кнопок
Помимо стандартной активации или деактивации кнопок в зависимости от их типов, есть механизм, который позволяет принудительно:
show— активировать кнопку;hide— скрыть кнопку;remove— деактивировать кнопку.
При выделении строки нужно смотреть, совпадает ли значение в колонке с именем из @name со значением из @value элементов hide, show или remove.
Принудительная активация не может сделать кнопку активной, если такое поведение не предусмотрено её типом.
В условиях hide, show или remove может быть прописана колонка, которая не показывается пользователю (отсутствует в col).
Локализация
Подписи к кнопкам берутся из локальных сообщений по имени кнопки с префиксом short_.
Подробное описание кнопки (подсказка) берётся из локальных сообщений по имени кнопки с префиксом hint_.
Подробное описание неактивной (по условиям show или hide) кнопки берётся из локальных сообщений по имени кнопки с префиксом hint_ и суффиксом _disabled.
Подробное описание неактивной (по количеству выбранных строк) кнопки берётся из локальных сообщений по имени кнопки с префиксом hint_ и суффиксом _noselect.
Сообщения для окна подтверждения берутся из локальных сообщений по имени кнопки с префиксом msg_confirm_.
Сообщения для окна подтверждения большого числа элементов берутся из локальных сообщений с именем msg_totalelem; макрос _%s_ для замены на количество элементов.
Разделитель элементов для окна подтверждения берётся из локального сообщения с именем msg_confirm_delimiter.
Элемент contextmenu
Контекстное меню отображается при нажатии на значок в строке таблицы. Функционально полностью повторяет toolbar: действуют правила hide, show, remove, отображение группами.
