Все модули называются в стиле alterator-<имя>. Предпочтительно в качестве <имя> использовать название конкретного сервиса, а не решаемую задачу. Например, alterator-postfix лучше чем alterator-mail, потому что может существовать ещё модуль alterator-sendmail.

Расположение файлов и каталогов

Стандартный модуль alterator может содержать следующие каталоги (их может инициализировать скрипт из пакета alterator-sdk):

help – документация
backend2 – нативные бакенды
backend3 – внешние бакенды
ui – описания интерфейсов (qt)
templates – описания интерфейсов (html)
applications – desktop-файлы с описанием модуля (для отображения в меню центра управления)
desktop-directories – directory-файлы с описанием групп модулей (для отображения в меню центра управления)
design – дополнительные к стандартным файлы с изображениями, стилями, скриптами.

Каталоги с бакендами не имеют никакой вложенной иерархии: бакенд, адресуемый как /foo должен находиться в файле backend3/foo, если это внешний бакенд, и backend2/foo, если это нативный бакенд.

Файлы описания интерфейсов раскладываются следующим образом:

html-описание, адресуемое как /foo/bar, должно находиться в файле templates/foo/bar/index.html
qt-описание, адресуемое как /foo/bar, должно находиться в файле ui/foo/bar/index.scm

Документация пишется в формате html и раскладывается в подкаталоги, соответствующие названию локали. Справка, по теме “foo” для русского языка должна находиться в файле help/ru_RU/foo.html, а для украинского — в файле help/uk_UA/foo.html

Файлы стилей размещаются в директории design, ссылка в html-интерфейсе на файл стилей /design/my.css

Регистрация в центре управления

Центр управления – это прежде всего способ объединить разрозненные модули alterator.
Каждый модуль содержит некоторое описание, на основании которого вычисляется его имя и местоположение внутри
двухуровневого меню. Это описание имеет традиционный формат desktop-файла и располагается в каталоге applications.
Модули объединяются в группы (первый уровень меню), каждая группа имеет описание в виде directory-файла и располагается в каталоге desktop-directories. Группы связаны с модулями косвенно через так называемые категории.

Описание группы

В файле описания группы модулей используются следующие параметры:

Name – имя группы. Также возможна запись локализованных имён в параметрах Name[locale], где locale – имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8.
Icon – картинка для группы, пока не используется
Type – всегда равно directory
X-Alterator-Category – имя категории, которую представляет данная группа.
X-Alterator-Weight – вес группы. В меню группы сортируются согласно их весу.

Пример описания группы:
[Desktop Entry] Type=Directory Name=Statistics Name[ru]=Статистика Icon=system X-Alterator-Category=X-Alterator-Statistics X-Alterator-Weight=15

Описание модуля

В файле описания модуля используются следующие параметры:

Name – имя модуля. Также возможна запись локализованных имён в параметрах Name[locale], где locale – имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8.
Icon – картинка для модуля, пока не используется
Categories – категории, с которыми связан данный модуль (пока допустимо перечислять только одну категорию)
Type – всегда равно application
Terminal – всегда равно false.
X-Alterator-URI – местоположение модуля (трактовка несколько отличается в acc и в fbi)
X-Alterator-Help – название темы справки. Справка пишется в формате html и размещается по адресу /usr/share/alterator/help/locale/name.html, где locale – полное имя локали, а name – имя, указанное в данном параметре.
X-Alterator-Weight – вес модуля. Внутри группы, элементы сортируются согласно их весу.

Пример описания модуля:

[Desktop Entry] Type=Application Categories=X-Alterator-System Icon=control Terminal=false Name=System objects Name[ru]=Системные объекты Name[uk]=Системні об'єкти X-Alterator-URI=/control X-Alterator-Weight=10 X-Alterator-Help=control

Замечание про разные интерфейсы:
Система меню и справки едина и для GUI и HTML интерфейса, однако до сих пор ещё встречаются модули, которые работают только в одном типе интерфейса. Для того чтобы они не появлялись в меню того центра управления, где они не работают, существует параметр X-Alterator-UI, позволяющий ограничить доступные интерфейсы. Допустимые значения данного параметра “html” и “qt”. В будущем, при окончательном переходе с устаревшей системы с template-*, данный параметр потеряет смысл, поскольку оценку возможностей модуля можно будет производить автоматически.

Бакенд

Бакенд может быть написан на произвольном языке програмирования, при этом настоятельно рекомендуется использовать готовые библиотеки, предоставляющие API для взаимодействия с alterator. Все библиотеки построены по одному и тому же принципу – есть главный цикл взаимодействующий с alterator и есть функция-обработчик пришедших сообщений.
В функции обработчике:

анализируется вид запроса (параметр action)
анализируется url запроса, а также значения входных параметров
вычисляются и выводятся значения выходных параметров.

Пример простейшего бакенда на shell:
#!/bin/sh -f po_domain="alterator-foo" api_version=1 . alterator-sh-functions on_message() { case "$in_action" in list) write_enum_item "item1" "label1" write_enum_item "item2" "label2" ;; read) case "$in__objects" in url1) write_string_param param1 "value1";; url2) write_bool_param param2 "yes";; esac ;; write) [ -n "$in_param1" ] && echo "$in_param1" >/tmp/file1 test_bool "$in_param2" && echo "yes">/tmp/file2 ;; esac } message_loop
В данном примере: message_loop — запуск цикла обработки событий, on_message — обработчик входящих сообщний. Входные переменные выглядят как переменные $in_<имя>. Выходные печатаются при помощи функций write_* . alterator_api_version – текущая версия API для взаимодействия с alterator. Если к к бакенду <name> обращались из интерфейса по адресу /<name>/foo/bar, то переменная $in__objects будет равна «foo/bar» (то есть «хвост» адреса), если обращались по адресу /<name>, то $in__objects будет равна «/».

Пример аналогичного бакенда на perl (см. также здесь):
#!/usr/bin/perl -w use strict; use Alterator::Backend3; $TEXTDOMAIN='alterator-foo'; $DEBUG = 1; sub on_message{ my message=shift; if ($message->{action} eq 'list'){ write_named_auto_list('item1', 'label', 'label1'); write_named_auto_list('item2', 'label', 'label2'); } elsif ($message->{action} eq 'read'){ write_string_param('param1', 'value1'); write_bool_param('param2', 'yes'); } elsif ($message->{action} eq 'write'){ print F1 $message->{param1} if (exists($message->{param1})); print F2 ($message->{param2} eq '#t')? 'yes':'no' if (exists($message->{param2})); } } message_loop(\&on_message);

Интерфейс

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

Формы

Названия полей формы не должны быть «оторваны» от самих полей.
Пример правильного описания для 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")

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

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

сheckbox

Данный элемент предназначен для представления атрибута логического типа.
Метка к checkbox должна идти после галочки и начинаться с заглавной буквы.
Пример для qt:
(checkbox text "Label for checkbox")
Для получения/изменения значения пользуйтесь атрибутом value.

Пример для html:
<input type="checkbox"/>Label for checkbox
Обратите внимание на написание тега в стиле xml, а не html.

Пример работы в бакенде на 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

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

Текст кнопок должен начинаться с заглавной буквы
Если кнопка открывает дополнительное диалоговое окно, то текст кнопки должен заканчиватья многоточием “...»
Ни один диалог модуля не должен содержать кнопки «Выход»

Пример для qt:
(button text "Button name")
Пример для html:
<input type="submit" class="btn" name="somename" value="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 принимает два атрибута: имя и значение.

Локализация

Для переводов стоит пользоваться единой базой переводов alterator-l10n. Данный пакет содержит переводы для всех модулей альтераторов. Тем самым достигается единый стиль названий (например перевод “Apply” и “Reset”). Чтобы подключить модуль к единой базе необходимо выполнить следующие действия:

подключить стандартный набор правил /usr/share/alterator/build/po.mak
сказать make update-po и получить файл-заготовку
связаться с мантейнером пакета alterator-l10n (inger@, cas@) и переслать свой .pot файл.
Дождитесь когда ваш пакет будет включён в alterator-l10n
Добавить пакет alterator-l10n в сборочные зависимости модуля (buildprereq)

После этого при каждой сборке пакета автоматически будут создаваться и размещаться в результирующем rpm-пакете) переводы для всех поддерживаемых языков. Если в вашем модуле уже были свои варианты переводов (файлы po/<language>.po), то их надо удалить.

Сборка модуля

Для всех модулей alterator, предоставлена стандартная сборочная система в виде стандартного набора правил make. Все их можно включать при помощи директивы include:

/usr/share/alterator/build/po.mak – правила для работы с переводами
- update-po – синхронизация po-файлов с бакендами и описаниями интерфейсов.
- install-po – сборка и инсталляция po-файлов в систему.
/usr/share/alterator/build/ui2.mak
- install-ui – инсталляция в систему каталогов: ui, layouts, applications, desktop-directories, help, templates, design.
/usr/share/alterator/build/backend.mak
- install-backend – инсталляция в систему каталогов: backend2, backend3.

Для работы правил необходимо записать имя модуля (без префикса alterator) в переменную NAME, а также задать переменную INSTALL (как правило /usr/bin/install).

Вот как выглядит типичный makefile для модуля:
NAME=users INSTALL=/usr/bin/install all: clean: clean-po install: install-backend install-ui install-po include /usr/share/alterator/build/po.mak include /usr/share/alterator/build/ui2.mak include /usr/share/alterator/build/backend.mak

Страница, вызываемая из Действия, пока не существует.(/Alt Linux / Sisyphus / Alterator / module / debug?)