Alterator/module/interface

Материал из ALT Linux Wiki


Интерфейс

Основу интерфейса модуля составляют формы — графическое отображение параметров того или иного объекта системы. При создании интерфейсов следует придерживаться определённых правил, чтобы интерфейс был единообразен и понятен для пользователя. На данный момент интерфейс имеет отдельное описание для qt и отдельное описание для html. В обоих случаях описание носит декларативный характер и состоит из описания местоположения виджетов и привязки интерфейса к соответствующему бэкенду.

Простейший интерфейс для qt

(document:support "/std/frame")

(label text "test" name "mylabel")

Интерфейс описывается на подмножестве языка scheme. Заголовок включает все необходимые определения из стандартной библиотеки, далее следует описание элементов интерфейса. Взаимодействие с бэкендом осуществляется путём вызова функций woo-*.

Простейший интерфейс для html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
<html wf="form">
  <head>
    <title>Some module</title>
  </head>
  <body>
    <form>
            <div class="alterator-text" name="url"/>
    </form>
  </body>
</html>

В alterator принято использовать запись в стиле xhtml. Описание статическое и декларативное, вся динамика и привязка к бэкенду скрыта в workflow, указанным в теге html в атрибуте wf. По умолчанию адрес бэкенда совпадает с адресом описания интерфейса.

Формы

Форма — это графическое представление интерфейса некоторого объекта системы. При создании дизайна формы следует руководствоваться простым правилом — названия полей не должны быть "оторваны" от самих полей.

Пример правильного описания для qt: 

(gridbox columns "0;100"

   (label "Label:" align "right")
   (field)

   (label "Label:" align "right")
   (field))

Обратите внимание на "0" для колонки с метками — это необходимо, чтобы колонка заняла в ширину ровно столько сколько необходимо для самой длинной метки.

Пример правильного описания для html: 

<table class="form-table">
  <tr>
    <td>Label:</td>
    <td>Field</td>
  </tr>
  <tr>
    <td>Label:</td>
    <td>Field</td>
  </tr>
</table>

CSS-класс "form-table" не будет корректно работать для старых браузеров (Internet Explorer 6.0), для них необходимо во всех td, содержащих метки использовать CSS-класс "form-table-label".

Группировка элементов формы

Иногда интерфейс становится столь большим, что приходится группировать отдельные его части.

Группировка при помощи пустых строк

html: <td colspan="2"> </td>
qt: (label colspan "2")

Группировка при помощи горизонтальной черты

html: <td colspan="2"><hr/></td>
qt: (separator colspan="2")

В этом способе группировки возможно задание названия группы. Название группы делается полужирным шрифтом и выравнено по левому краю формы.

html: <td><strong>Group title</strong></td>
qt: (label text (bold "Group title") align "right")

Простейшее форматирование текста

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

текст полужирным шрифтом
html: <strong>some text</strong>
qt: (bold "some text")
текст мелким шрифтом
html: <small>some text</small>
qt: (small "some text")

Элементы формы

Форма состоит из различных элементов. При размещении элементов стоит руководствоваться следующими правилами:

  • Метки полей и заголовки должны начинаться с заглавной буквы.
  • Если метка и поле находятся в одной строке, то метка должна заканчиваться символом двоеточия ":".
  • Заголовки групп, включая заголовки groupbox не должны содержать символа двоеточия ":".
общие атрибуты

Если элемент формы надо скрыть, то в html для этого есть параметры CSS, а в qt — атрибут visibility.

Пример для qt: 

(edit) ;; видимое поле
(edit visibility #t) ;; видимое поле
(edit visibility #f) ;; невидимое поле

Пример для html: 

<input type="text" class="text"/> <!-- видимое поле -->
<input type="text" class="text" style="display:inline" /> <!-- видимое поле -->
<input type="text" class="text" style="display:none" /> <!-- невидимое поле -->
сheckbox

Данный элемент предназначен для представления атрибута логического типа.

html: <input type="checkbox"/>Label for checkbox
qt: (checkbox text "Label for checkbox")

Для получения/изменения значения пользуйтесь атрибутом value. Обратите внимание на написание тега в стиле xml, а не html.

При создании интерфейса пожалуйста следите за тем что метка к checkbox должна идти после галочки и начинаться с заглавной буквы.

Пример работы в бэкенде на shell: 

read)
            ...
            write_bool_param"item1" "Yes"
      write)
            if test_bool "$in_item1"; then ...  else ... fi

Функция write_bool_param принимает два параметра — имя и значение. В качестве значения допустимы любые варианты: y, yes, on, true (в любом регистре). Функция test_bool применяется для "считывания" значения параметра, независимым от представления в протоколе виде.

button

Данный элемент предназначен для представления активных действий с формой.

html: <input type="submit" class="btn" name="somename" value="Button name"/>
qt: (button text "Button name")

Обратите внимание на использование класса btn и на написание тега в стиле xml, а не html.

При построении интерфейса постарайтесь следовать следующим правилам:

  • Текст кнопок должен начинаться с заглавной буквы
  • Если кнопка открывает дополнительное диалоговое окно, то текст кнопки должен заканчиватья многоточием "..."
  • Ни один диалог модуля не должен содержать кнопки "Выход"
combobox/listbox/select

В самом простом случае данные элементы представляют атрибут типа перечисление (enum), то есть обеспечивают выбор одного варианта из числа возможных. Сombobox — более компактное представление чем Listbox, но одновременно видно только один вариант, чтобы просмотреть остальные — надо вызвать выпадающий список. Список вариантов предоставляет бэкенд (вызываемый с action list). Параметр enumref — адрес к которому надо обращаться к бэкенду за списком.

Компактное представление списка:

html: <select name="item1" enumref="/x11/avail_resolution"/>
qt: (combobox enumref "/x11/avail_resolution")

Развёрнутое представление списка:

html: <select name="item1" size="10" enumref="/x11/avail_driver"/>
qt: (listbox enumref "/x11/avail_driver")

В qt текущий выбранный вариант — параметр value. В html интерфейсе размер списка в строках — параметр size. Обратите также внимание на написание тега в стиле xml, а не html.

Пример бэкенда на shell: 

...
      list)
        write_enum_item "item1" "label1"
        write_enum_item "item2" "label2"
        ;;
      read)
        write_string_param "name" "item1"
        ;;
      write)
        echo "$in_name">zzz
        ;;
...

Функция write_enum_item принимает два параметра:

  • вариант — то ключевое имя, которым пользуется бэкенд
  • название варианта (необязательно) — то описание, которое будет выведено пользователю (возможно с переводом)
checklistbox

Также как и listbox представляет атрибут перечислимого типа, но уже с возможностью множественного выбора. Для заполнения списка используется тот же параметр enumref. Для "массового" выделения бэкенд должен выводить список имён, в бэкенд результат возвращается также в виде списка . Список представляется в виде строки с разделителем ";", например "a;b;c;d".

html: <table class="alterator-checklistbox" enumref="/dovecot/avail_mechanisms" name="mechanisms"/>
qt: (checklistbox enumref "/dovecot/avail_mechanisms")

В qt текущий набор выделенных элементов — параметр value.

многоколоночный listbox

Вариант listbox с отображением информации разбитой на несколько колонок для более удобного чтения. Иначе говоря отображение таблиц. Источник данных для таблиц — бэкенд, адрес указывается при помощи атрибута enumref. В таблице есть ключевое поле. При помощи ключевого поля идентифицируется текущее значение таблицы точно также как это делалось для одноколоночного варианта. Для вывода информации бэкенд пользуется функцией write_table_item: write_table_item <парметр1> <значение1> <параметр2> <значение2> ...

В qt интерфейсе при помощи атрибута row задаётся шаблон строки таблицы: 

'#((label1 . pixmap1) (label2 . pixmap2))

.

Здесь label1,label2,pixmap1,pixmap2 — символы — имена параметров переданных бэкендом. Таким образом в зависимости от информации в строках будут различаться и текстовое и графическое содержимое строк.

Пример: 

 (listbox columns 2
          row '#((name . "") (summary . ""))
          header (vector (_ "Facility") (_ "Summary"))
          enumref "/control")

В html интерфейсе шаблон строки таблицы задаётся внутри тега <tbody>. Для каждой строки переданной бэкендом указанная строка "заполняется" и таким образом "размножается".

Пример: 

<table class="alterator-listbox" enumref="/control">
  <thead>
   <tr>
     <th><span translate="_">Facility</span></th>
     <th><span translate="_">Summary</span></th>
     <th><span translate="_">State</span></th>
   </tr>
  </thead>
  <tbody>
  <tr>
   <td nowrap="yes">
     <a href="/control/facility?fname=" class="alterator-ref2">
       <span class="alterator-label" name="name"></span>
     </a>
   </td>
   <td><span class="alterator-label" name="summary"/> </td>
   <td><span class="alterator-label" name="current"/></td>
  </tr>
  </tbody>
</table>
edit

Представляет атрибут строкового типа.

html: <input type="text" class="text" name="name1"/>
qt: (edit)

Для ввода пароля есть специальный вариант edit.

html: <input type="password" class="text" name="name"/>
qt: (edit echo "stars")

В qt для изменения и получения значения служит атрибут value.

Пример бэкенда на shell: 

...
      read)
        write_string_param name1 "value1"
        ;;
      write)
         echo $in_name1" >zzz
       ;;
...

Функция write_string_param принимает два атрибута: имя и значение.

dateedit

Специализированный виджет в виде календаря и текстового поля для работы с датой — строкой формата ГГГГ-ММ-ДД. Имеются два варианта виджета: развёрнутый и компактный. Во втором случае календарь появляется под полем ввода при нажатии на специальную клавишу.

Развернутый вариант:

html: <div class="alterator-dateedit" name="name"/>
qt: (dateedit expanded #t)

Компактный вариант:

html: <span class="alterator-dateedit" name="name"/>
qt: (dateedit expanded #f)


Для получения и изменения значения в qt используйте атрибут value. В web-интерфейсе календарь будет работать только в браузерах с включенной поддержкой Javascript.

timeedit

Специализированный виджет в виде аналоговых часов и текстового поля для работы со временем — строкой формата ЧЧ:ММ:CC.

html: <div class="alterator-timeedit" name="name"/>
qt: (timeedit expanded #t)

Для получения и изменения значения в qt используйте атрибут value. В html интерфейсе часы будут работать только в браузерах с включенной поддержкой Javascript.