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

/
/
/
Описание списков

Описание списков

Введение

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

  • атрибут key — ключевое поле. Значение этого поля будет передано в форму в параметре elid при редактировании;
  • атрибут keyname — задаёт поле, значение которого используется для отображения списка выбранных элементов при групповых операциях. Если не указан, используется значение ключевого поля;
  • атрибут autoupdate — задаёт интервал автоматического обновления страницы в секундах;
  • атрибут selficon — этот список имеет свой собственный логотип. Значение параметра — имя картинки.
  <metadata name="product" type="list" key="mpname" keyname="name" mgr="core">
    <toolbar view="buttontext">
      <toolgrp name="one">
        <toolbtn func="product.params" type="edit" default="yes" img="t-edit" name="params">
          <hide name="isinstalled" value="off"/>
        </toolbtn>
        <toolbtn func="product.update" type="edit" img="t-retry" name="update">
          <hide name="isinstalled" value="off"/>
        </toolbtn>
        <toolbtn func="product.install" type="edit" img="t-install" name="install">
          <hide name="isinstalled" value="on"/>
        </toolbtn>
        <toolbtn func="product.delete" type="group" img="t-delete" name="delete">
          <hide name="isinstalled" value="off"/>
          <hide name="name" value="COREmanager"/>
        </toolbtn>
      </toolgrp>
      <toolgrp name="two">
        <toolbtn func="product.go" type="edit" img="t-goisp" name="go">
          <hide name="isinstalled" value="off"/>
          <hide name="name" value="COREmanager"/>
        </toolbtn>
      </toolgrp>
      <toolgrp name="three">
        <toolbtn func="product.config" type="new" img="t-attr" name="config"/>
      </toolgrp>
    </toolbar>
    <coldata>
      <col name="name" type="data" sort="alpha" sorted="yes"/>
      <col name="version" type="data"/>
      <col name="avail_version" type="data"/>
      <col name="state" sort="prop">
        <prop name="installed" defimg="p-off" onimg="p-on"/>
        <prop name="installing" onimg="p-install" animated="yes"/>
        <prop name="updating" onimg="p-install" animated="yes"/>
        <prop name="deleting" onimg="p-install" animated="yes"/>
      </col>
      <col name="descr" type="msg"/>
    </coldata>
  </metadata>

Панель инструментов (элемент toolbar)

Панель инструментов содержит в себе кнопки, разделенные на группы (элемент toolgrp).

  • атрибут view — задаёт внешний вид панели инструментов. Данный атрибут навешивается автоматически и его значение зависит от настроек текущего пользователя. Возможные значения:
    • button: показывать только кнопки;
    • buttontext: показывать подписи к кнопкам.
  • элемент toolgrp — предназначен для логического разделения кнопок, содержит в себе элементы toolbtn, должен иметь атрибут name;
  • элемент toolbtn — см. Кнопка панели инструментов.

Группа кнопок (элемент toolgrp)

  • атрибут name — имя группы. Используется для идентификации кнопки и привязки к языкам;
  • атрибут img имя картинки. Если задан атрибут, то при сворачивании в группы, вместо первой кнопки в группе будет отображена фейковая кнопка, с картинкой из значения атрибута, и подписью взятой из локальных сообщений по имени группы.
  • атрибут collapsed — говорит о том, что группу кнопок нужно показать в виде дропдауна, который раскрывается при наведении на неё курсором.

Кнопка панели инструментов (элемент toolbtn)

  • атрибут name — имя кнопки. Используется для идентификации кнопки и привязки к языкам;
  • атрибут func — имя функции, которая будет вызвана при нажатии;
  • атрибут img — имя картинки, которая будет отображена на кнопке. Необходимо указать без расширения;
  • атрибут customicon — URL для svg-иконки, такая иконка имеет приоритет над @img и темизируется автоматически (при смене темы с теменой на светлую и наоборот);
  • атрибут sprite — значение "yes" означает, что иконка кнопки  находится в спрайте иконок ispmanager;
  • атрибут progressbar — значение "yes" означает, что на время обработки действия будет показан прогрессбар ;
  • атрибут default — значение "yes" является признаком действия по умолчанию (при двойном щелчке по строке таблицы); атрибут может быть у нескольких элементов, в таком случае будет вызвана функция первой активной кнопки;
  • атрибут cgi — адрес cgi скрипта на который отправлять запрос. Например /mancgi/download;
  • атрибут sametab — модуль будет открыт в той же вкладке вместо дочерней вкладки;
  • атрибут newtab — модуль будет открыт в новой вкладке панели вместо дочерней вкладки;
  • атрибут drawer — модуль будет открыт в дровере вместо дочерней вкладки, значение описывает ширину дровера - large, medium или small;
  • атрибут nogroupedit — запретить групповое редактирование;
  • атрибут detached — значение "yes" означает, что это отдельная кнопка, которая может быть расположена вне тулбара. Часто используется для обозначения создания сущности в списках;
  • атрибут danger — значение "yes" означает, что в конфирме кнопка подтверждения действия будет красной;
  • атрибут confirmform — указывает на функцию (func) формы, из которой будут взяты поля ввода для отображения в конфирме;
  • атрибут location — единственное возможное значение context означает, что кнопку нужно показать не в тулбаре, а в контекстном меню элемента в таблице
  • атрибут type — тип действия кнопки. Может принимать следующие значения:
    • new: будет показана форма создания нового элемента;
    • back: вернуться к предыдущему списку;
    • edit: вызов формы редактирования одного выбранного элемента;
    • action: операция над выбранным элементом без подтверждения;
    • editnosel: аналог edit за тем исключением, что открывает форму редактирования, когда ни один элемент таблицы не выбран;
    • editlist: вызов функции-списка, для которого родительским элементом (plid) будет являться выбранный элемент в текущем списке;
    • group: групповая операция над выбранными элементами;
    • groupform: вызов формы группового редактирования выбранных элементов;
    • groupformnosel: аналог groupform за тем исключением, что позволяет вызов функции, когда ни один элемент таблицы не выбран;
    • groupdownload: аналог групповой операции с той разницей, что в ответ ожидаем файл;
    • list: вызов функции-списка;
    • refresh: вызов функции для обновления текущего списка;
    • windownosel: функция будет открыта в новом окне;
    • window: функция будет открыта в новом окне, для выбранного элемента;
    • groupwindow: функция будет открыта в новом окне, для выбранных элементов;
    • url: открыть URL указанный в атрибуте func в отдельной вкладке браузера;
    • preview: будет отображена картинка, отданная вызванной функцией.

Сообщения

Для локализации при работе с кнопками панели инструментов используются следующие сообщения:

  • hint_<имя кнопки> — сообщения для всплывающей подсказки;
  • short_<имя кнопки> — подпись под кнопкой в панели инструментов;
  • msg_confirm_<имя кнопки> — сообщение, используемое для подтверждения операции (@type='group');
  • msg_confirm_delimiter — строка, которая будет использоваться как разделитель в подтверждении, при выборе нескольких элементов. По умолчанию в качестве разделителя используется запятая с пробелом.

Элементы hide, show, remove:

Элемент hide

Отключение кнопки в зависимости от выбранной строчки.

  • атрибут name — имя столбца;
  • атрибут value — значение при котором кнопка будет недоступна.

Элемент show

Включение кнопки в зависимости от выбранной строчки.

  • атрибут name — имя столбца;
  • атрибут value — значение, при котором будет показана кнопка.

Элемент remove

Удаление кнопки в зависимости от выбранной строчки.

  • атрибут name — имя столбца;
  • атрибут value — значение, при котором будет удалена кнопка.

Описание колонок таблицы (элемент coldata)

Узел coldata должен содержать один или более узлов col, описывающих колонки таблицы.

  • элемент col — описывает колонку таблицы;
  • элемент setcolor — задаёт условия для раскраски строки. Подробнее смотрите описание элемента setcolor.

Описание колонки (элемент col)

  • атрибут name — имя колонки. Должно иметь уникальное значение в пределах одного metadata. Необходимо для привязки к языкам;
  • атрибут type — тип данных в колонке. Может принимать значения:
    • data: данные от панели управления. Используется по умолчанию;
    • indicator: индикатор значения лимита и фактического использования передаёт панель управления;
    • msg: показ сообщения, соответствующего переданному значению от панели управления;
    • toggle: отображает переключатель строки. Используется как альтернатива toolbtn для более быстрого выполнения действия. Значение в ячейках: on для включенного состояния и off для выключенного. Используется совместно с элементом toggle внутри элемента col. Элемент toggle может содержать в себе элементы hide и соответственно быть заблокирован в зависимости от данных в строке, может иметь атрибуты: name - имя свойства, onenable - задает имя функции, которую нужно вызвать при переводе переключателя в значение "включено", ondisable - задает имя функции, которую нужно вызвать при переводе переключателя в значение "выключено";
    • prop:  используется совместно с элементами prop и xprop в элементе col, отображает в колонке иконки состояния.  

     

  • атрибут sort — задаёт тип сортировки данных в колонке. Возможные значения:
    • alpha: алфавитная сортировка; по умолчанию;
    • calpha: регистронезависимая алфавитная сортировка;
    • digit: сортировка в порядке числового возрастания;
    • version: сортировка версий программного обеспечения;
    • file: аналогична "alpha", но символ '/' считается меньше любого другого, таким образом файлы внутри одного каталога всегда располагаются вместе;
    • indicator: сортировка по "использованному значению" индикатора.Только для колонок с индикаторами;
    • ip: сортировка IP-адресов;
    • prop: сортировка по наличию свойств, при одинаковых свойствах сортируем по значению колонки в алфавитном порядке;
    • priority: сортировка в алфавитном порядке по по атрибуту @priority.
  • атрибут sorted — задаёт сортировку по умолчанию, в качестве значения должно быть указано число задающее порядок сортировки, знак перед числом определяет направление '-' — по убыванию, '+' — по возрастанию (знак обязателен);
    Обратите внимание!
    Устаревший вариант: если sorted="yes", таблица по умолчанию отсортирована по этой колонке. sorted="desc" — сортировать по убыванию.
  • атрибут stat — показывать сумму чисел в данном столбце. При этом, если за числом идёт некая строка (суффикс), то суммирование производится отдельно для каждого суффикса. Для индикаторов суммируется и всего, и использовано. Если в значение элемента списка есть атрибут total, то при total="ignore" — при выделении эта строка будет игнорироваться в сумме, а при total="final" в сумме будет отображаться только это значение;
  • атрибут wrap — если установлен, переносы строк в данных не будут проигнорированы. Данные в колонке отображаются в нескольких строках;
  • атрибут align — выравнивание данных колонки. Может принимать значения: left, right, center.
  • атрибут width — ширина колонки по умолчанию в процентах;
  • атрибут editform — значение ячейки будет отображено в виде ссылки на форму редактирования. Имя функции должно быть задано в значении атрибута, в запрос на форму редактирования будут добавлены elid строки и plid списка.;
  • атрибут fastfilter — будет отображена иконка быстрого фильтра по списку, дающая установить фильтр по значению ячейки таблицы списка в один клик;
  • атрибут if — см. Введение;
  • атрибут hidden —по умолчанию, скрывать данную колонку. Для отображения необходимо выполнить настройку вида таблицы;
  • атрибут level — см. Введение;
  • атрибут noescaping — наличие этого атрибута отключает экранирование html;
  • атрибут convert — задаёт алгоритм кодирования для столбца. Все значения в этом столбце будут преобразованы с использованием заданного алгоритма. На данный момент реализован только punycode — алгоритм преобразования из punycode в последовательность символов в кодировке UTF-8;
  • атрибут edit — разрешить редактирование элемента прямо из списка. Значение атрибута задаёт имя функции (формы), которую необходимо позвать для сохранения значения. Важно, чтобы название колонки совпадало с названием поля (field) из формы и это поле должно быть доступно для изменения. Помимо значения в форму будет передано имя колонки (scolname) и имя списка (stablename).
    Обратите внимание!
    Если значение поля влияет на идентификатор строки, функция обязана возвращать новый идентификатор elid и имя elname (если его значение не совпадает с идентификатором).
    Поддерживаются следующие типы полей формы: input[type=text][zoom, unlimit, date], select, radio, slider, textarea.
  • атрибут nestedlist — задаёт имя списка, в который следует перейти при нажатии на значение в этой колонке. Перед переходом в список на него будет установлен фильтр. Параметры фильтра будут взяты из значения @nestedlist, который имеет формат QUERY_STRING. Кроме имени списка, с которого должно начинаться значение @nestedlist, в атрибуте могут быть использованы следующие макросы:
    • col_value — значение ячейки
    • elid — идентификатор строки (@key)
    • plid — идентификатор подсписка
    • +значения полей фильтра текущего списка

Например:

<coldata>
  <col sort="ip" sorted="yes" name="name" type="data" nestedlist="webdomain&ipaddr=__col_value__"/>
</coldata>

При нажатии на значение в списке IP адресов будет отображен список сайтов (webdomain). Перед вызовом списка на него будет установлен фильтр следующим вызовом webdomain&ipaddr=col_value&sok=ok, где вместо _col_value_ будет подставлено значение ячейки. Для игнорирования данного функционала для определенных строк нужно использовать атрибут nestedlist="no" в элементе со значением.

  • атрибут nestedlist_blank — списки будут открываться в новой вкладке панели, используется только в связке с атрибутом nestedlist;
  • атрибут nestedlist_child — списки будут открываться в дочерней вкладке панели, используется только в связке с атрибутом nestedlist;
  • элемент setcolor — задаёт условия для раскраски ячейки. Подробнее смотрите описание элемента setcolor.

Подсказки к колонкам (hint) сообщения могут содержать подсказки к колонкам: hint_<имя_колонки>

Описание свойства (prop/xprop)

Любая колонка может содержать до 64 свойств (элементов prop и xprop). Свойства сортируются согласно порядку их объявления в метаданных.

Элемент prop — отображается при наличии в строке значения с именем указанным в атрибуте @name;

Элемент xprop — отображается, если значение указанное в атрибуте @name равно значению, указанному в атрибуте @value. Если атрибут @value не указан, такое свойство будет отображено, если значению этого элемента не соответствует никакого другого xprop с таким же @name.

Элементы prop и xprop могут содержать следующие атрибуты:

  • атрибут name — см. описание выше;
  • атрибут value — только для xprop см. описание выше;
  • атрибут img — задаёт картинку, которая будет отображена;
  • атрибут animated — картинка img — анимированный gif файл;
  • атрибут cgi — адрес cgi скрипта, на который отправлять запрос. Например /mancgi/download;
  • атрибут func — задаёт функцию, которая должна быть вызвана при нажатии на картинку. Этой функции будут переданы в качестве параметров значения elid — идентификатор выбранной строки, plid — идентификатор в базовом списке, value — значение свойства;
  • атрибут sort — задаёт тип сортировки для данного свойства. Атрибут sort имеет смысл использовать только совместно с сортировкой типа "prop". Возможные значения этого атрибута:
    • no: данное свойство не будет учитываться при сортировке;
    • invert: при сортировке по убыванию строки без этого свойства будут идти раньше строк с ним;
  • атрибут type — задаёт тип функции @func. Может принимать следующие значения:
    • edit: вызов формы редактирования одного выбранного элемента;
    • list: вызов функции-списка, для которого родительским элементом (plid) будет являться выбранный элемент в текущем списке;
    • group: операция с подтверждением над выбранным элементом;
    • window: вызов фукции в отдельной вкладке браузера;
    • url: открыть URL, указанный в атрибуте func в отдельной вкладке браузера.
  • атрибут stat — показывать общее количество строк с таким свойством внизу таблицы;
  • атрибут activehint — если установлен в "yes", то сообщение описывающее свойство будет загружено из панели отдельным запросом всякий раз, когда его необходимо отобразить. Для этого будет вызвана функция формирования списка с параметрами hint_field, содержащим имя свойства, value — его значение, elid — идентификатор строки, результатом функции должен быть xml документ содержащий элемент value с текстом сообщения. Текст будет подставлен в соответствующее сообщение (см. далее) вместо макроса _value_.

Сообщения могут содержать описание для свойства:

  • hint_p_ — описание для xprop с заданным именем и значением;
  • hint_p — описание для prop/xprop. В котором макрос _value_ будет заменен на значение.

Раскраска (элемент setcolor)

Действие элемента setcolor распространяется на одну ячейку (цвет текста), если он описан внутри элемента col или на всю строку (цвет фона), если он описан внутри элемента coldata. Вы можете описать любое количество условий раскраски строк или ячеек таблицы.

  • атрибут name — задаёт имя элемента (это может быть имя col, prop, xprop или имя колонки, не описанной в xml), значение которого будет сравниваться с указанным в атрибуте value. Этот атрибут можно не указывать в правилах для раскраски ячеек. В этом случае будет взято содержимое ячейки, для которой это правило написано.
  • атрибут value — задаёт значение, с которым будет сравниваться значение поля, заданного атрибутом @name. Если значение не указано или пустое — проверяет наличие поля в строке.
  • атрибут color — задаёт цвет, который будет применен, если выполняется заданное условие

Ячейки и строки таблицы могут быть раскрашены вручную при формировании данных (элементов elem). Для этого необходимо добавить атрибут color в соответствующий элемент elem для раскраски строки или в любой элемент с данными ячейки, для раскраски соответствующей ячейки. На момент передачи данных в xslt обработчик, все условия, заданные элементом setcolor, будут вычислены и выставлены соответствующие атрибуты в элементах данных списка.

На данный момент доступны следующие цвета: red, green, blue, yellow, cyan. Пример раскраски состояний в списке изменений:

...
        <col name="state" sort="alpha" type="msg">
            <setcolor color="red" value="testing"/>
            <setcolor color="yellow" value="planned"/>
            <setcolor color="green" value="release"/>
        </col>
...

Описание диаграм (элемент diagram)

К таблицам возможно добавить визуальное отображение данных с помощью элемента diagram.

  • атрибут type — тип графика. Возможные значения: line, histogram, pie (посмотреть примеры можно тут);
  • атрибут label — из какой колонки взять подпись к значениям;
  • атрибут data — из какой колонки взять данные для круговой диаграммы (только для type="pie");
  • атрибут min — задаёт нижний вертикальный предел для графика (только для type="line" и type="histogram");
  • атрибут max — задаёт верхний вертикальный предел для графика (только для type="line" и type="histogram");
  • атрибут others — задаёт минимальный процент для отображения на круге, все данные ниже этого процента будут отображаются как "другое" (только для type="pie", задаётся дробным числом например 20% это 0.2).

Элемент line — один или несколько таких элементов описывают данные, которые должны быть отображены на графике.

  • атрибут @data этого элемента задаёт имя колонки, из которой будут взяты значения;
  • атрибут @color задаёт цвет линии/столбца, для применения необходимо задать этот атрибут для всех элементов line.

В этой статье