Вход:  Пароль:  
FreeSource: AltLinux/Sisyphus/Alterator/module ...
Free Source | Каталог | Изменения | НовыеКомментарии | Пользователи | Регистрация |
Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

Оглавление документа

Руководство по написанию модулей Alterator


Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

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

Название модуля

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

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

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


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


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


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


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

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


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

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


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


Пример описания группы:

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


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


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



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

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

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


Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

Бакенд

Существует два вида бакендов: нативные и внешние. Размещаются эти бакенды в каталогах /usr/lib/alterator/backend2 и /usr/lib/alterator/backend3 соответственно.


Нативные бакенды пишутся только на языке scheme и работают внутри процесса alterator. Написание нативных бакендов требует достаточно большого опыта программирования и большой аккуратности.


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

Простейший бакенд на shell


Пример простейшего бакенда на shell:

В данном примере: message_loop — запуск цикла обработки событий, on_message — обработчик входящих сообщний. Входные переменные выглядят как переменные $in_<имя>. Выходные печатаются при помощи функций write_* . alterator_api_version – текущая версия API для взаимодействия с alterator. Если к к бакенду <name> обращались из интерфейса по адресу /<name>/foo/bar, то переменная $in__objects будет равна «foo/bar» (то есть «хвост» адреса), если обращались по адресу /<name>, то $in__objects будет равна «/».

Простейший бакенд на perl


Пример аналогичного бакенда на perl (см. также здесь):


Здесь, как ив shell-бакенде message_loop — запуск цикла обработки событий, on_message — обработчик входящих сообщний. Обработчику передается ссылка на хэш с входными перемеными. Выходные печатаются при помощи функций write_*. При обращении из интерфейса по адресу /<name>/foo/bar, то в бакенде <name> в этом хэше будет присутствовать _objects="foo/bar" (то есть «хвост» адреса), если обращались по адресу /<name>, то _objects="/".


Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

Интерфейс

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

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


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

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


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

Формы

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


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

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


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

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

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

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


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


Пример для html:


Пример для qt:


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


Пример для qt:


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


Пример для qt:

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

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

текст полужирным шрифтом

Пример для qt:


Пример для html:

текст маленьким шрифтом

Пример для qt:


Пример для html:

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

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

общие атрибуты

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


Пример для qt:


Пример для html:

сheckbox

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

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


Пример для html:

Обратите внимание на написание тега в стиле xml, а не html.


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

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

button

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

Пример для qt:

Пример для html:

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

combobox/listbox/select

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


Пример для qt:

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


Пример для html:

Размер списка в строках – параметр size. Обратите внимание на написание тега в стиле xml, а не html.


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

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

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

checklistbox

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


Пример для qt:

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


Пример для html:

edit

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


Пример для qt:

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


Пример для html:


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

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


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


Пример для qt:


Пример для html:

dateedit

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


Пример для qt:

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


Пример для html:

Календарь будет работать только в браузерах с включенной поддержкой Javascript.

timeedit

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


Пример для qt:

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


Пример для html:

Часы будут работать только в браузерах с включенной поддержкой Javascript.


Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

Визуальные эффекты


Все описания интерфейсов — статические. Для улучшения восприятия пользователем интерфейса можно добавить немного динамики, такой как скрытие или «засеривание» неиспользуемых полей формы. Описание эффектов выглядит в виде последовательности правил. Виджеты в правилах адресуются по значению атрибута name. Допустимо указывать одно и тоже имя и для самого поля и для его метки. Синтаксис правил зависит от синтаксиса используемого языка сценариев (scheme, javascript), но различия незначительны. Большинство правил построено на анализе значений полей, при этом для qt для заполнения полей необходимо использовать атрибут value.


В поставке с alterator идёт несколько самых распространённых эффектов.

API эффектов


html: effectDisable(<виджет>, <другой виджет>, <значение другого виджета>);
qt: (effect-disable <виджет> <другой виджет> <значение другого виджета>)


Виджет станет неактивным, если выполнены соответствующие условия. Параметры:


html://effectShow(<виджет>, <другой виджет>, <значение другого виджета>);//
qt: (effect-show <виджет> <другой виджет> <значение другого виджета>)


Виджет будет появляться, если выполнены соответствующие условия. Параметры такие же как и у effectDisable.


html: initEffect();
qt: (init-effect)


Запуск подсистемы визуализации эффектов.


Данную функцию Необходимо вызывать только один раз. В html вызов данной функции происходит автоматически. В qt необходимо поместить вызов этой функции после того как заданы правила и завершено первоначальное заполнение полей формы.


html: updateEffect();
qt: (update-effect)


Обновление состояния полей и меток.


При изменений значений полей эффект корректируется автоматически. Но если одна та же форма используется представления параметров однотипных объектов, может потребоваться явное обновление состояния визуального представления. В html при использовании стандартных worflow (/design/script/select.js, /design/scripts/card-index.js) все необходимые вызовы происходят автоматически.


У функции effectDisable существует «двойственная функция» — effectEnable, а у effectShoweffectHide.

Пример описания эффекта


В html описание помещается внутри тега script, в заголовке документа:



В qt описание помещается в конце документа перед вызовом функций, делающих первоначальное заполнение полей:


Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

Локализация

В alterator встроена система автоматического перевода текстовых сообщений на язык пользователя. Для того чтобы её задействовать необходимо отметить эти сообщения в описании интерфейса специальным образом и указать название используемого словаря.

Описание интерфейса

Если адрес описания интерфейса /<модуль>/foo/bar, то по умолчанию этому интерфейсу сопоставляется словарь alterator-<модуль> и соответственно имя его специально указывать не надо.


Вы можете явно указать другой словарь с помощью команды po-domain. Кроме того другой словарь можно задавать явно для каждого сообщения.


Пример для qt:

Инструкцией po-domain можно задать основной словарь, если он не должно вычисляться автоматически из адреса модуля.
Функция _ используется для получения перевода, принимает необязательный второй параметр, указывающий словарь.


Пример для html:

Необязательным атрибутом po-domain можно задать основной словарь, если он не должно вычисляться автоматически.


Атрибут translate применяется к span и input типа reset и submit. Наличие атрибута означает, что содержимое данного span или value данного input надо перевести используя указанный словарь, “_" — означает основной словарь. Для обратной совместимости с предыдущими модулями если у input атрибут translate отсутствует, то value всё-равно переводится и используется словарь по умолчанию.

Бакенды


Команды, приходящие к бакенду, содержат информацию о языке используемом для переводов (параметр language). Перевод сообщений в бакендах устроен по тому же принципу что и в описаниях интерфейсов:

Бакенд на shell



Переменная po_domain содержит имя основного словаря. Функция _ используется для получения перевода, принимает необязательный второй параметр, указывающий словарь.
Предпочтительно использовать обратные кавычки '`' вместо конструкции $() ибо последняя не подхватывается утилитой xgettext.

Бакенд на perl


Единая база переводов


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

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

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


Эта страница была перенесена на altlinux.org. Текст на freesource.info заморожен.

Отладка модулей

Работа с модулем без установки в систему


Все компоненты alterator используют особые переменные среды для определения местоположения основных рабочих каталогов:


Для обоих переменных допустимо перечисление нескольких каталогов через двоеточие – в этом случае поиск производится последовательно в порядке указания имён. Например, если ALTERATOR_DATADIR="/a:/b", то файл ui.scm будет искаться сначала по адресу /a/ui.scm, а потом /b/ui.scm.


Для удобства использования у утилит командной строки alterator существует ключ '-l', который добавляет текущий каталог в начало списка каталогов в ALTERATOR_LIBDIR и ALTERATOR_DATADIR.


Таким образом, находясь в модуле, можно отлаживать и запускать его не устанавливая в систему.


Во последнем варианте сервер configd не будет отцепляться от терминала и будет работать с локальными бакендами и файлами шаблонов. Для старой системы шаблонов (template-*), дополнительно существует переменная ALTERATOR_HTMLDIR, которая модифицируется при использовании '-l' аналогично остальным переменным.


alterator-standalone лучше всего запускать с указанием /usr/sbin, поскольку утилита consolehelper (/usr/bin/alterator-standalone ссылается на неё) может менять состав переменных окружения.


Обратите также внимание на то, что с локальными desktop-файлами будет работать только alterator-standalone. Поэтому при создании нового модуля вы не увидите его в общем меню центра управления.

Интерфейс командной строки

Утилита alterator-cmdline служит для выполнения запросов к бакендам из интерфейса командой строки и может с успехом использоваться для написания скриптов. Параметр -l позволяет работать с локальными бакендами, а параметр -k указывает выводить значения конкретного параметра.


Пример:


 
Файлов нет. [Показать файлы/форму]
Комментарии [Скрыть комментарии/форму]