Основы создания плагинов для OutWiker¶

Формат плагинов¶

Примечание

Эта документация подразумевает, что плагины будут рассчитаны на работу в OutWiker 2.0 или более новых версий. В OutWiker 1.9 и ранее формат плагинов немного отличался (не было обязательного файла plugin.xml).

Плагины в OutWiker представляют собой Python-пакеты с дополнительным файлом plugin.xml. Плагины располагаются в папке plugins папки с настройками OutWiker (см. раздел Где находится папка профиля программы?).

Плагин представляет собой папку с файлами:

plugin.py - основной модуль плагина. Каждый плагин должен иметь этот файл, в котором должен находиться класс, производный от outwiker.core.pluginbase.Plugin.
plugin.xml - файл с информацией о совместимости плагина и (не обязательно) с информацией об авторе плагина, домашней странице и со списокм изменений в каждой версии плагина.
__init__.py- необходимый файл, чтобы папка с плагином считалась Python-пакетом.

Файлы plugin.py и plugin.xml будут описаны далее.

Минимальный плагин¶

Для примера создадим плагин с именем FirstPlugin. Для этого нужно создать следующую структуру файлов и папок внутри папки plugins:

plugins
└── firstplugin
    ├── __init__.py
    ├── plugin.py
    └── plugin.xml

Файл __init__.py останется пустым текстовым файлом, а остальные файлы начнем постепенно заполнять.

Начнем с файла plugin.xml. Минимальный файл plugin.xml должен содержать информацию о той версии OutWiker, которая требуется плагину:

<?xml version="1.1" encoding="UTF-8" ?>
<info>
    <name>FirstPlugin</name>
    <requirements>
        <api>2.835</api>
    </requirements>
</info>

Здесь внутри тега <name>…</name> указано имя плагина, которое будет в интерфейсе OutWiker и в сообщениях об ошибках.

Версии компонентов OutWiker¶

Внутри тега <api>…</api> указана внутренняя версия API программы OutWiker, которая требуются плагину для работы. Номер текущей версии API можно увидеть в файле 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. Считается, что при изменении первой цифры номера версии теряется обратная совместимость.

Plugin. Базовый класс для плагинов¶

Файл plugin.py должен содержать объявление класса, производного от абстрактного базового класса outwiker.core.pluginbase.Plugin, который содержит методы, которые нужно и которые можно перегрузить в производном классе. Основные методы и свойства этого класса:

class outwiker.core.pluginbase.Plugin¶

def __init__(application): Конструктор принимает экземпляр класса outwiker.core.application.ApplicationParams (см. раздел Application. Экземпляр класса ApplicationParams), который будет доступен в производных классах через член self._application.

name¶: Абстрактное свойство. Возвращает строку с именем плагина. По этой строке с помощью API OutWiker можно находить экземпляр загруженного плагина.

description¶: Абстрактное свойство. Возвращает строку с кратким описанием плагина.

initialize()¶: Абстрактный метод. Метод вызывается при загрузке плагина. Именно в этом методе плагин должен подписаться на необходимые события, чтобы взаимодействовать с OutWiker.

destroy()¶: Абстрактный метод. Метод вызывается перед отключением плагина, в том числе перед закрытием программы OutWiker.

Минимально необходимый код в файле plugin.py может выглядеть следующим образом:

# -*- 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

Примечание

Имя класса из файла plugin.py обязательно должно начинаться со слова «Plugin», например, «PluginFirst».

Если все сделано правильно, то после перезапуска OutWiker плагин FirstPlugin появится в списке плагинов.

Примечание

Исходные коды такого плагина можно посмотреть в исходниках OutWiker в папке plugins/examples/firstplugin_01.

Полная информация о плагине¶

Файл plugin.xml может содержать больше информации о плагине. Ниже приведен пример файла plugin.xml для нашего первого плагина.

<?xml version="1.1" encoding="UTF-8" ?>
<info>
    <name>FirstPlugin</name>
    <updates>http://example.com/pluginname/plugin.xml</updates>
    <requirements>
        <api>2.835</api>
    </requirements>

    <data lang="en">
        <website>http://example.com/pluginnameEn</website>
        <description>Description.</description>

        <author>
            <name>Author name</name>
            <email>example@example.com</email>
            <site>http://example.com</site>
        </author>

        <changelog>
            <version number="0.2" date="August 24, 2017">
                <download os="all">http://example.com/pluginname-0.2.zip</download>
                <change>Added a new cool feature.</change>
                <change>Bug fixes.</change>
            </version>

            <version number="0.1" date="August 02, 2017">
                <download os="all">http://example.com/pluginname-0.1.zip</download>
                <change>The first version.</change>
            </version>
        </changelog>
    </data>

    <data lang="ru">
        <website>http://example.com/pluginnameRu</website>
        <description>Описание.</description>

        <author>
            <name>Author name</name>
            <email>example@example.com</email>
            <site>http://example.com</site>
        </author>

        <changelog>
            <version number="0.2" date="24.08.2017">
                <download os="all">http://example.com/pluginname-0.2.zip</download>
                <change>Добавлена новая крутая возможность.</change>
                <change>Исправление ошибок.</change>
            </version>

            <version number="0.1" date="02.08.2017">
                <download os="all">http://example.com/pluginname-0.1.zip</download>
                <change>Первая версия.</change>
            </version>
        </changelog>
    </data>
</info>

Коротко рассмотрим используемые теги. Все они являются необязательными.

info/updates: Путь до файла plugin.xml в интернете. Используется для проверки доступной версии плагина на сайте http://jenyay.net. В перспективе это свойство будет использоваться плагином UpdateNotifier для поиска новых версий плагинов. Если у плагина нет сайта в интернете, этот тег можно не писать.
info/data: Содержит дополнительную информацию, которая предназначена в первую очередь для показа пользователям (единственное исключение - номер версии, о чем будет сказано далее). Поэтому может быть несколько тегов <data>, каждый из них предназначен для показа данных на своем языке. В данный момент используются два языка: английский (тег <data> должен содержать атрибут lang=»en») и русский (тег <data> должен содержать атрибут lang=»ru»). Несмотря на то, что OutWiker поддерживает большее количество языков, эти два языка используются по той причине, что сайт OutWiker переведен только на эти два языка. Данные из тега <data> используются для создания страниц описания плагинов. Вложенные теги описаны далее.
info/data/website: Ссылка на страницу плагина в интернете.
info/data/description: Краткое описание плагина. Может не совпадать с описанием, которое возвращает свойство description класса, производного от outwiker.core.pluginbase.Plugin. Используется только для создания описания плагина на сайте.
info/data/author: Содержит информацию об авторе плагина: имя автора (тег <name>), e-mail автора (тег <email>), сайт автора (не обязательно совпадающий с сайтом плагина, тег <site>).
info/data/changelog: Содержит описание изменений в каждой версии плагина. В данный момент информация из тега <changelog> используется только для создания списка изменений на сайте плагина. В будущем эти данные будут использоваться плагином UpdateNotifier, чтобы показывать пользователю, что изменилось в новой версии плагина.
info/data/changelog/version: Содержит информацию об изменениях в конкретной версии плагина. Обязательный атрибут - number, который указывает описание какой версии содержит тег <version>. Номер версии - целые числа, разделенные точками. Количество элементов номера версии может быть от 1 до 4. Также тег <version> может содержать атрибут date, который хранит дату релиза данной версии плагина. Дата может описываться в произвольном формате и предназначена для показа пользователю, поэтому формат даты может быть различным для английской и русской версии тега <data>. Тегов <version> может быть несколько. Текущая версия плагина определяется по наибольшей версии, которая указана в атрибутах number тегов <version>.
info/data/changelog/version/download: Содержит ссылку для скачивания данной версии плагина. Также может быть добавлен атрибут os, указывающий, для какой операционной системы предназначена данная ссылка. Может быть несколько тегов <download>, содержащих ссылки для скачивания для разных операционных систем. В данный момент атрибут os игнорируется.
info/data/changelog/version/change: Содержит информацию об одном пункте списка изменений.

Плагин FirstPlugin с приведенным выше файлом plugin.xml в списке плагинов будет выглядеть следующим образом (появился номер версии):

Примечание

Исходные коды такого плагина можно посмотреть в исходниках OutWiker в папке plugins/examples/firstplugin_02.

Заключение¶

В данном разделе был приведен пример минимального плагина, который ничего не делает кроме как загружается вместе с OutWiker. Чтобы придать плагину какую-либо функциональность, нужно воспользоваться переменной экземпляром класса outwiker.core.application.ApplicationParams, который получает конструктор класса outwiker.core.pluginbase.Plugin (см. раздел Application. Экземпляр класса ApplicationParams) и подписаться на те события, которые должен обрабатывать плагин. О событиях см. раздел События.

Основы создания плагинов для OutWiker¶

Формат плагинов¶

Минимальный плагин¶

Версии компонентов OutWiker¶

Plugin. Базовый класс для плагинов¶

Полная информация о плагине¶

Заключение¶

OutWiker

Навигация

Related Topics