.. _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`.