Alterator/module/interface

Эта страница была перемещена с freesource.info.
Эта страница наверняка требует чистки и улучшения — смело правьте разметку и ссылки.
Просьба по окончанию убрать этот шаблон со страницы.

Интерфейс

Основу интерфейса модуля составляют формы - графическое отображение параметров того или иного объекта системы. При создании интерфейсов следует придерживаться определённых правил, чтобы интерфейс был единообразен и понятен для пользователя. На данный момент интерфейс имеет отдельное описание для 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 - адрес к которому надо обращаться к бакенду за списком.

Пример для qt:

(combobox enumref "/x11/avail_resolution") ;;компактное представление списка
(listbox enumref "/x11/avail_driver") ;; развёрнутое представление списка

Текущий выбранный вариант - параметр value.

Пример для html:

<select name="item1" enumref="/x11/avail_resolution"/> <!-- компактное представление списка -->
<select name="item1" size="10" enumref="/x11/avail_driver"/> <!-- развёрнутое представление списка -->

Размер списка в строках - параметр 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 принимает два параметра:

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

Если функция вызвана без параметра, то она начинает со стандартного ввода строки с одним или более значениями, разделённых стандартным разделителем (переменная IFS). Первое и второе значение интерпретируются также: вариант и его название.

checklistbox

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

Пример для qt:

(checklistbox enumref "/dovecot/avail_mechanisms")

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

Пример для html:

<table class="alterator-checklistbox" enumref="/dovecot/avail_mechanisms" name="mechanisms" />

edit

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

Пример для qt:

(edit)

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

Пример для html:

<input type="text" class="text" name="name1"/>

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

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

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

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

Пример для qt:

(edit echo "stars")

Пример для html:

<input type="password" class="text" name="name"/>

dateedit

Специализированный виджет в виде календаря и текстового поля для работы с датой — строкой формата ГГГГ-ММ-ДД.

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

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

timeedit

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

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

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