Alterator/module/interface: различия между версиями
| Строка 68: | Строка 68: | ||
!align="right"|html: | !align="right"|html: | ||
|<td colspan="2"><hr/></td> | |<td colspan="2"><hr/></td> | ||
|- | |- | ||
!align="right"|qt: | !align="right"|qt: | ||
| Строка 78: | Строка 79: | ||
!align="right"|html: | !align="right"|html: | ||
|<td><strong>Group title</strong></td> | |<td><strong>Group title</strong></td> | ||
|- | |||
!align="right"|qt: | !align="right"|qt: | ||
|(label text (bold "Group title") align "right") | |(label text (bold "Group title") align "right") | ||
|- | |||
|} | |} | ||
Версия от 17:07, 30 июля 2008
Интерфейс
Основу интерфейса модуля составляют формы - графическое отображение параметров того или иного объекта системы. При создании интерфейсов следует придерживаться определённых правил, чтобы интерфейс был единообразен и понятен для пользователя. На данный момент интерфейс имеет отдельное описание для 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.