.. _ru_outwiker_plugins: Основы создания плагинов для OutWiker ===================================== .. _ru_plugins_intro: Формат плагинов --------------- .. note:: Эта документация подразумевает, что плагины будут рассчитаны на работу в OutWiker 2.0 или более новых версий. В OutWiker 1.9 и ранее формат плагинов немного отличался (не было обязательного файла :file:`plugin.xml`). Плагины в OutWiker представляют собой Python-пакеты с дополнительным файлом :file:`plugin.xml`. Плагины располагаются в папке :file:`plugins` папки с настройками OutWiker (см. раздел :ref:`ru_faq_dir_settings`). Плагин представляет собой папку с файлами: * :file:`plugin.py` - основной модуль плагина. Каждый плагин должен иметь этот файл, в котором должен находиться класс, производный от :class:`outwiker.core.pluginbase.Plugin`. * :file:`plugin.xml` - файл с информацией о совместимости плагина и (не обязательно) с информацией об авторе плагина, домашней странице и со списокм изменений в каждой версии плагина. * :file:`__init__.py`- необходимый файл, чтобы папка с плагином считалась Python-пакетом. Файлы :file:`plugin.py` и :file:`plugin.xml` будут описаны далее. .. _ru_plugins_min: Минимальный плагин ------------------ Для примера создадим плагин с именем `FirstPlugin`. Для этого нужно создать следующую структуру файлов и папок внутри папки :file:`plugins`: .. code:: plugins └── firstplugin ├── __init__.py ├── plugin.py └── plugin.xml Файл :file:`__init__.py` останется пустым текстовым файлом, а остальные файлы начнем постепенно заполнять. Начнем с файла :file:`plugin.xml`. Минимальный файл :file:`plugin.xml` должен содержать информацию о той версии OutWiker, которая требуется плагину: .. code-block:: xml FirstPlugin 2.835 Здесь внутри тега `...` указано имя плагина, которое будет в интерфейсе OutWiker и в сообщениях об ошибках. .. _ru_plugins_versions: Версии компонентов OutWiker ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Внутри тега `...` указана внутренняя версия API программы OutWiker, которая требуются плагину для работы. Номер текущей версии API можно увидеть в файле :file:`src/outwiker/core/__init__.py`. При загрузке плагина происходит проверка требуемой версии API OutWiker по следующим правилам: * Если плагину требуется API с **большим** номером версии, чем имеется в данной версии OutWiker, плагин не будет загружен, а в лог программы будет выведена ошибка о том, что для работы данного плагина требуется более новая версия OutWiker. * Если плагину требуется API с **тем же** номером версии, что и в данной версии OutWiker, то плагин будет загружен. * Если плагину требуется API с **меньшим** номером версии, но при этом первая цифра версии API данной версии OutWiker в требованиях плагина и OutWiker **совпадает**, то плагин будет загружен. * Если плагину требуется компонент с **меньшим** номером версии, но при этом первая цифра версии API в требованиях плагина и OutWiker **не совпадает**, то плагин не будет загружен, а в лог программы будет выведено сообщение о том, что необходимо установить более новую версию плагина (данная версия плагина устарела). Например, если плагину требуется API 2.2, то он будет успешно загружен в OutWiker, API версий 2.0 и 2.1, но не 1.9 и не 2.3. Считается, что при изменении первой цифры номера версии теряется обратная совместимость. .. _ru_plugins_plugin_class: Plugin. Базовый класс для плагинов ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Файл :file:`plugin.py` должен содержать объявление класса, производного от абстрактного базового класса :class:`outwiker.core.pluginbase.Plugin`, который содержит методы, которые **нужно** и которые **можно** перегрузить в производном классе. Основные методы и свойства этого класса: .. py:class:: outwiker.core.pluginbase.Plugin .. py:method:: def __init__(application) Конструктор принимает экземпляр класса :class:`outwiker.core.application.ApplicationParams` (см. раздел :ref:`ru_application`), который будет доступен в производных классах через член `self._application`. .. py:attribute:: name *Абстрактное свойство*. Возвращает строку с именем плагина. По этой строке с помощью API OutWiker можно находить экземпляр загруженного плагина. .. py:attribute:: description *Абстрактное свойство*. Возвращает строку с кратким описанием плагина. .. py:method:: initialize() *Абстрактный метод*. Метод вызывается при загрузке плагина. Именно в этом методе плагин должен подписаться на необходимые события, чтобы взаимодействовать с OutWiker. .. py:method:: destroy() *Абстрактный метод*. Метод вызывается перед отключением плагина, в том числе перед закрытием программы OutWiker. .. py:attribute url Возвращает ссылку на страницу плагина в интернете. Свойство может быть перегружено в классе плагина. По умолчанию свойство возвращает None, это обозначает, что у плагина нет сайта в интернете. Минимально необходимый код в файле :file:`plugin.py` может выглядеть следующим образом: .. code-block:: python # -*- coding: utf-8 -*- from outwiker.core.pluginbase import Plugin class PluginFirst(Plugin): def __init__(self, application): super(PluginFirst, self).__init__(application) ######################################### # Properties and methods to overloading # ######################################### @property def name(self): return u"FirstPlugin" @property def description(self): return _(u"My first plugin") def initialize(self): pass def destroy(self): pass .. note:: Имя класса из файла :file:`plugin.py` обязательно должно начинаться со слова "Plugin", например, "PluginFirst". Если все сделано правильно, то после перезапуска OutWiker плагин `FirstPlugin` появится в списке плагинов. .. image:: /_static/plugins/ru_firstplugin_01.png :width: 600 px :align: center :alt: Список плагинов .. note:: Исходные коды такого плагина можно посмотреть в исходниках OutWiker в папке :file:`plugins/examples/firstplugin_01`. .. _ru_plugins_info: Полная информация о плагине ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Файл :file:`plugin.xml` может содержать больше информации о плагине. Ниже приведен пример файла :file:`plugin.xml` для нашего первого плагина. .. code-block:: xml FirstPlugin http://example.com/pluginname/plugin.xml 2.835 http://example.com/pluginnameEn Description. Author name example@example.com http://example.com http://example.com/pluginname-0.2.zip Added a new cool feature. Bug fixes. http://example.com/pluginname-0.1.zip The first version. http://example.com/pluginnameRu Описание. Author name example@example.com http://example.com http://example.com/pluginname-0.2.zip Добавлена новая крутая возможность. Исправление ошибок. http://example.com/pluginname-0.1.zip Первая версия. Коротко рассмотрим используемые теги. Все они являются необязательными. `info/updates` Путь до файла :file:`plugin.xml` в интернете. Используется для проверки доступной версии плагина на сайте http://jenyay.net. В перспективе это свойство будет использоваться плагином `UpdateNotifier `_ для поиска новых версий плагинов. Если у плагина нет сайта в интернете, этот тег можно не писать. `info/data` Содержит дополнительную информацию, которая предназначена в первую очередь для показа пользователям (единственное исключение - номер версии, о чем будет сказано далее). Поэтому может быть несколько тегов ``, каждый из них предназначен для показа данных на своем языке. В данный момент используются два языка: английский (тег `` должен содержать атрибут `lang="en"`) и русский (тег `` должен содержать атрибут `lang="ru"`). Несмотря на то, что OutWiker поддерживает большее количество языков, эти два языка используются по той причине, что сайт OutWiker переведен только на эти два языка. Данные из тега `` используются для создания страниц описания плагинов. Вложенные теги описаны далее. `info/data/website` Ссылка на страницу плагина в интернете. `info/data/description` Краткое описание плагина. Может не совпадать с описанием, которое возвращает свойство `description` класса, производного от :class:`outwiker.core.pluginbase.Plugin`. Используется только для создания описания плагина на сайте. `info/data/author` Содержит информацию об авторе плагина: имя автора (тег ``), e-mail автора (тег ``), сайт автора (не обязательно совпадающий с сайтом плагина, тег ``). `info/data/changelog` Содержит описание изменений в каждой версии плагина. В данный момент информация из тега `` используется только для создания списка изменений на сайте плагина. В будущем эти данные будут использоваться плагином `UpdateNotifier `_, чтобы показывать пользователю, что изменилось в новой версии плагина. `info/data/changelog/version` Содержит информацию об изменениях в конкретной версии плагина. Обязательный атрибут - `number`, который указывает описание какой версии содержит тег ``. Номер версии - целые числа, разделенные точками. Количество элементов номера версии может быть от 1 до 4. Также тег `` может содержать атрибут `date`, который хранит дату релиза данной версии плагина. Дата может описываться в произвольном формате и предназначена для показа пользователю, поэтому формат даты может быть различным для английской и русской версии тега ``. Тегов `` может быть несколько. Текущая версия плагина определяется по наибольшей версии, которая указана в атрибутах `number` тегов ``. `info/data/changelog/version/download` Содержит ссылку для скачивания данной версии плагина. Также может быть добавлен атрибут `os`, указывающий, для какой операционной системы предназначена данная ссылка. Может быть несколько тегов ``, содержащих ссылки для скачивания для разных операционных систем. В данный момент атрибут `os` игнорируется. `info/data/changelog/version/change` Содержит информацию об одном пункте списка изменений. Плагин `FirstPlugin` с приведенным выше файлом :file:`plugin.xml` в списке плагинов будет выглядеть следующим образом (появился номер версии): .. image:: /_static/plugins/ru_firstplugin_02.png :width: 600 px :align: center :alt: Список плагинов .. note:: Исходные коды такого плагина можно посмотреть в исходниках OutWiker в папке :file:`plugins/examples/firstplugin_02`. .. _outro: Заключение ---------- В данном разделе был приведен пример минимального плагина, который ничего не делает кроме как загружается вместе с OutWiker. Чтобы придать плагину какую-либо функциональность, нужно воспользоваться переменной экземпляром класса :class:`outwiker.core.application.ApplicationParams`, который получает конструктор класса :class:`outwiker.core.pluginbase.Plugin` (см. раздел :ref:`ru_application`) и подписаться на те события, которые должен обрабатывать плагин. О событиях см. раздел :ref:`ru_events`.