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

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

Примечание

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

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

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

  • plugin.py - основной модуль плагина. Имя этого файла может быть произвольным (с расширением .py), но рекомендуется его называть именно как plugin.py, чтобы было понятно, какой python-модуль является основным для плагина.
  • 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>
        <packages>
            <core>1.3</core>
            <actions>1.1</actions>
            <gui>1.5</gui>
            <pages>2.0</pages>
            <utilites>1.0</utilites>
            <libs>1.0</libs>
        </packages>
    </requirements>
</info>

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

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

Внутри тега <packages>...</packages> перечислены версии внутренних компонентов OutWiker, которые требуются плагину для работы. Основные компоненты следующие:

core
Содержит базовые классы OutWiker, не касающиеся интерфейса программы (чтение и запись заметок в дереве, загрузка плагинов, работа с событиями и др.) Версию компонента core можно увидеть в файле src/outwiker/core/__init__.py.
actions
Содержит классы действий (actions, см. раздел Actions (не написано)), которые выполняют какие-то действия над интерфейсом. Версию компонента actions можно увидеть в файле src/outwiker/actions/__init__.py.
gui
Содержит классы и функции для создания интерфейса OutWiker. Версию компонента gui можно увидеть в файле src/outwiker/gui/__init__.py.
pages
Содержит классы для работы со встроенными типами страниц OutWiker. Версию компонента pages можно увидеть в файле src/outwiker/pages/__init__.py.
utilites
Содержит классы и функции, которые выполняют вспомогательные действия и могут быть полезны для упрощения работы плагинов. Версию компонента utilites можно увидеть в файле src/outwiker/utilites/__init__.py.
libs
Содержит сторонние библиотеки, которые можно хранить внутри проекта OutWiker, чтобы не добавлять их в зависимость. На момент написания документации там располагается только библиотека pyparsing. Версию компонента libs можно увидеть в файле src/outwiker/libs/__init__.py.

При загрузке плагина происходит проверка требуемых версий компонентов OutWiker по следующим правилам:

  • Если плагину требуется компонент с большим номером версии, чем имеется в запущенной версии OutWiker, плагин не будет загружен, а в лог программы будет выведена ошибка о том, что для работы данного плагина требуется более новая версия OutWiker.
  • Если плагину требуется компонент с тем же номером версии, что и в запущенной версии OutWiker, то плагин будет загружен.
  • Если плагину требуется компонент с меньшим номером версии, но при этом первая цифра версии компонента в требованиях плагина и OutWiker совпадает, то плагин будет загружен.
  • Если плагину требуется компонент с меньшим номером версии, но при этом первая цифра версии компонента в требованиях плагина и OutWiker не совпадает, то плагин не будет загружен, а в лог программы будет выведено сообщение о том, что необходимо установить более новую версию плагина (данная версия плагина устарела).

Например, если плагин требует компонент pages версии 2.2, то он будет успешно загружен в OutWiker, который содержит компонент pages версий 2.0 и 2.1, но не 1.9 и не 2.3 и выше. Считается, что при изменении первой цифры номера версии теряется обратная совместимость.

Таблицу со списком номеров версий встроенных компонентов см. в разделе Список версий внутренних компонентов OutWiker.

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.

version

Возвращает строку, содержащую номер версии плагина. Номер версии читается из файла plugin.xml. Классы плагинов, которые предназначены для работы в OutWiker 1.9 и более старых, должны были явно переопределять свойство version. Сейчас этот способ также работает, то считается устаревшим.

Минимально необходимый код в файле 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>
        <os>Windows, Linux</os>
        <packages>
            <core>1.3</core>
            <actions>1.1</actions>
            <gui>1.5</gui>
            <pages>2.0</pages>
            <utilites>1.0</utilites>
            <libs>1.0</libs>
        </packages>
    </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/requirements/os
Указывает, в каких операционных системах может работать плагин. В данный момент используется только для создания описания плагина на сайте.
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) и подписаться на те события, которые должен обрабатывать плагин. О событиях см. раздел События.