Alterator/module/structure

<onlyinclude>
=== Структура модуля ===

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

==== Расположение файлов и каталогов ====
Стандартный модуль alterator может содержать следующие каталоги:
* '''backend2''' — нативные бэкенды
* '''backend3''' — внешние бэкенды
* '''ui''' — описания интерфейсов (qt)
* '''applications''' — desktop-файлы с описанием модуля (для отображения в меню центра управления)
* '''desktop-directories''' — directory-файлы с описанием групп модулей (для отображения в меню центра управления)
* '''design''' — дополнительные к стандартным файлы с изображениями, стилями, скриптами.

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

Файлы описания интерфейсов раскладываются следующим образом:
* html-описание, адресуемое как '''/foo/bar''', должно находиться в файле '''ui/foo/bar/index.html'''
* qt-описание, адресуемое как '''/foo/bar''', должно находиться в файле '''ui/foo/bar/index.scm'''

Файлы стилей размещаются в директории '''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''' — вес группы. В меню группы сортируются согласно их весу.
 
Пример описания группы:
<source lang="ini">[Desktop Entry]
Type=Directory
Name=Statistics
Name[ru]=Статистика
Icon=system
X-Alterator-Category=X-Alterator-Statistics
X-Alterator-Weight=15</source>

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

В файле описания модуля используются следующие параметры:
* '''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''' — вес модуля. Внутри группы, элементы сортируются согласно их весу.
 
Пример описания модуля:

<source lang="ini">[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</source>

'''Замечание про разные интерфейсы'''

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

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

all:
install: install-module
include /usr/share/alterator/build/module.mak
</pre>

'''Стандартные правила''':
* install-module — установка модуля в систему
* check-module — создание виртуальной среды и запуск тестов
* generate-module — автоматическое создание отдельных компонент модуля

Сборочная система модульная и расширяема по следующим направлениям:

'''Автоматизация работы над модулем'''
Наиболее часто повторяющиеся действия могут быть оформлены как скрипт и размещены в каталоге ''/usr/share/alterator/build/generators''. После этого скрипт с именем <name> может быть вызван посредством команды: <pre>make generate-<name></pre>

Доступные генераторы:
{| class="standard"
!align="left"|backend-pl
|простейший бэкенд на perl
|-
!align="left"|backend-sh
|простейший бэкенд на shell
|-
!align="left"|desktop-file
|простейший desktop-файл с описанием модуля alterator
|-
!align="left"|ui-html
|простейший интерфейс для html
|-
!align="left"|ui-qt
|простейший интерфейс для qt
|-
!align="left"|module
|генератор, запускающий несколько генераторов одновременно, список генераторов задаётся в makefile в переменной GENERATE_LIST
|}
Большинство генераторов учитывают значение переменной NAME.

Пример создания простейшего интерфейса qt:
<pre>
make generate-ui-qt
</pre>

Пример запуска серии генераторов:
<pre>
make GENERATE_LIST="ui-qt ui-html" generate-module
</pre>
Значение по умолчанию переменной GENERATE_LIST — 'desktop-file ui-qt ui-html backend-sh', поэтому:
<pre>
make generate-module
</pre>
Создаст стандартный модуль с бэкендом на shell с qt и html интерфейсами.


'''Вытаскивание строк для формирования словаря переводов'''

Для разных языков разметки и для разных языков программирования требуется разный способ «вытаскивания» строк для создания шаблона переводов (pot-файл). Если вы написали бэкенд на языке не имеющим официальной поддержки в alterator, то можете оформить алгоритм вытаскивания переводов в виде скрипта и разместить в каталоге ''/usr/share/alterator/build/xgettext''. Скрипт будет автоматически выполнен при выполнении команды make update-po

Поддерживаемые форматы:
{| class="standard"
!align="left"|desktop
|desktop-файлы с описанием модуля и directory-файлы с описанием групп модулей
|-
!align="left"|html
|файлы с описанием html интерфейса модуля
|-
!align="left"|perl
|бэкенды на perl
|-
!align="left"|shell
|бэкенды на shell
|-
!align="left"|scm
|нативные бэкенды и файлы с описанием графического интерфейса модуля
|}

'''Генерация словарей'''

При установке модуля автоматически генерируются словари в формате mo-файлов, а также добавляются переводы в desktop-файлы и directory-файлы. Если вам требуется что-то ещё — оформляйте как скрипт и размещайте в каталоге <tt>/usr/share/alterator/build/msgfmt</tt>
</onlyinclude>


{{Alterator modules-nav}}