# Структура плагина

Плагин для ГИС Аксиома - это специально оформленный модуль Python с дополнительными файлами.

Рассмотрим структуру минимального плагина с обязательными параметрами и более расширенного:

Минимальный:

    ru_mycompany_minimal_module  # папка плагина
    ├── __init__.py  # точка входа
    └── manifest.ini  # информация о плагине

Расширенный:

    ru_mycompany_extended_module
    ├── documentation
    │   └── index.html
    ├── business_logic.py
    ├── i18n
    │   ├── translation_en.qm
    │   └── translation_en.ts
    ├── __init__.py
    ├── manifest.ini
    └── ui
        ├── form.ui
        ├── image.png
        └── logo.png

## Идентификатор плагина

`ru_mycompany_minimal_module` - папка с плагином, она же - уникальный идентификатор плагина. Так же, как и при создании обычных модулей Python, избегайте конфликтов имен. Делайте имя плагина уникальным. Для этого следуйте простому соглашению именования: - используйте имя вашего веб-сайта или электронной почты, разделив на слова в обратном порядке; - используйте только маленькие латинские буквы и символ нижнего подчеркивания `"_"`, т.е. `[a-z0-9_]`.

Так для плагина mymodule рекомендуемым идентификатором будет: - для веб-сайта axioma-gis.ru - `ru_axioma_gis_mymodule` - для почты andrey@yandex.ru - `ru_yandex_at_andrey_mymodule`

## Точка входа

`__init__.py` - точка входа в плагин, так же как и для любого другого модуля Python - является обязательным для системы импорта. Содержит основной код плагина или импортирует другие локальные файлы.

См.также

Точка входа должна содержать пользовательский класс, наследуемый от класса Plugin.

## Информация о плагине

`manifest.ini` - содержит основную информацию, версию, название и прочее. Является ini-файлом c простыми парами ключ=значение.

Примечание

Файл `manifest.ini` должен иметь кодировку UTF-8.

Минимальный пример содержимого:

    name=Пример плагина
    description=Короткий текст с описанием плагина.

См.также

Для более подробного описания формата ini, поддерживаемого ГИС Аксиома, смотрите документацию configparser.

Таблица значений
Параметр | Обязательно | Описание
--- | --- | ---
name | True | Короткая строка с именем модуля.
description | True | Короткий текст с описанием.
version | False | Строка с версией модуля.
homepage | False | Cсылка на домашнюю страницу модуля.
target | False | Версия Аксиомы, с которой работает модуль; цифры, разделенные точкой.
platforms | False | Список поддерживаемых платформ; через запятую из возможных Windows Linux и Darwin.
icon | False | Имя файла или относительный путь (относительно корневой папки модуля) в формате PNG.

Также могут содержаться другие необязательные параметры:

    ; может содержать коментарии
    name=Пример модуля
    description=Короткий текст с описанием модуля.
        Может быть многострочным.
    ; конец обязательных параметров

    ; необязательные параметры
    version=1.0
    homepage=https://dev.axioma-gis.ru
    platforms=Windows,Darwin
    target=3.1.0
    author=Developer Name
    email=dev@axioma-gis.ru
    repository=https://github.com/developer/mymodule
    license=New BSD

    ; секция локализации
    [i18n]
    name_en=Plugin example
    description_en=Plugin example description.

## Документация

Документация может быть написана в HTML файлах. ГИС Аксиома откроет документацию в системном веб-браузере. Аксиома ищет документацию в папке с плагином documentation - файлы `index[locale].html`. Пользователь откроет документацию с суффиксом локали, совпадающим с языком системы. При отсутствии совпадения будет открываться файл без суффикса - `index.html`.

## Переводы

Можно предусмотреть загрузку плагина на разных языках.

Название и описание самого плагина может быть переведено на другие языки в манифесте в секции `i18n`:

    ; секция локализации
    [i18n]
    name_en=Plugin example
    description_en=Plugin example description.
    name_fr=Exemple de plugin
    description_fr=Description de l'exemple de plugin.

У пользователя отобразится название и описание в случае, если язык системы будет совпадать с суффиксом локали. Иначе отобразится название и описание из основной секции.

Наиболее простой способ создания и сопровождения переводов строк из исходного кода - использование «Qt Linguist».

Примечание

Подробнее о переводе в документации Qt Linguist.

Основные этапы:

1. Отмечаются строки, предназначенные для перевода.

2. Для экспорта строк используется утилита `lupdate`. Она проходит по файлам с исходным кодом и забирает все встречаемые строки, отмеченные для перевода. Результатом является файл с расширением `.ts` - простой структурированный xml файл со строками.

3. `.ts` - файл открывается в «Qt Linguist» и переводится на один или более языков.

4. После завершения перевода отдельных строк файл `.ts` “компилируется” в бинарный файл с расширением `.qm`, который будет загружен Аксиомой.ГИС. Для компиляции используется утилита `lrelease`.

    lrelease your_plugin.ts

5. `.qm` - файлы размещаются в подпапке `i18n` внутри плагина. Они будут загружены вместе с плагином.