Создание плагина

Посетите наш подфорум сообщества плагинов для плагинов, созданных сообществом, и дальнейшего обсуждения.

В этом руководстве мы рассмотрим, как создать плагин Baserow с нуля, предоставим вам примеры плагинов для вдохновения и обсудим, как опубликовать ваш плагин.

Инициализация вашего плагина из официального шаблона

Мы настоятельно рекомендуем использовать Шаг за шагом руководство по созданию плагина с использованием шаблона плагина, которое настроит базовый плагин Baserow, готовый для начала работы.

Для создания экземпляра шаблона выполните следующие команды:

$ cd ~/baserow
$ pip install cookiecutter
$ cookiecutter gl:baserow/baserow --directory plugin-boilerplate

Получите вдохновение от наших примеров

Кроме того, мы создали два примера плагинов, чтобы показать авторам плагинов, как выполнять обычные задачи с помощью плагина.

Плагин Baserow Geo

Плагин Geo — это пример плагина, который добавляет новый тип поля "Точка". Он показывает, как:

• Установить и включить расширение postgres (только при запуске Baserow в образе all-in-one при использовании встроенной базы данных)
• Установить дополнительные системные пакеты с помощью apt-get
• Добавить пользовательские зависимости Python и Node.js на бэкенде и фронтенде
• Добавить новый тип поля с пользовательскими компонентами и SCSS

Пример плагина Baserow Formula

Пример плагина формулы добавляет новую функцию формулы timezone. Он показывает, как:

• Добавить новую функцию формулы в Baserow
• Использовать пользовательскую хранимую процедуру plpgsql для реализации новой функции формулы
• Использовать миграцию для добавления хранимой процедуры

Архитектура плагина

Плагин Baserow по сути является папкой, названной в честь плагина, содержащей папки backend и/или web-frontend. В Baserow есть две основные службы: Django backend API-сервер и Nuxt web-frontend сервер. Плагин Baserow может интегрироваться либо с обеими, либо с одной из этих служб, заполняя соответствующую подпапку плагина.

Так как служба backend построена на Django, подпапка backend в плагине должна быть Django приложением. Аналогично, служба web-frontend построена с использованием Nuxt.js, поэтому подпапка web-frontend плагина должна содержать модуль Nuxt ( v2) модуль.

API установки плагина

Текущая версия API плагина Baserow — 0.0.1-alpha.

Все официальные образы Baserow поставляются со следующими скриптами bash, которые используются для установки плагинов. Их можно использовать либо в Dockerfile во время сборки для включения плагина в Docker-образ, либо для установки плагина в существующий контейнер Baserow во время выполнения. install_plugin.sh можно использовать для установки плагина из URL, репозитория Git или локальной папки на файловой системе.

Вы можете найти эти скрипты в следующих местах в наших образах:

1. /baserow/plugins/install_plugin.sh
2. /baserow/plugins/uninstall_plugin.sh
3. /baserow/plugins/list_plugins.sh

Эти скрипты ожидают, что плагин Baserow будет следовать описанным ниже соглашениям.

Структура файлов плагина

Скрипты install_plugin.sh/uninstall_plugin.sh ожидают, что ваш плагин будет иметь определенную структуру следующим образом:

├── plugin_name
│  ├── baserow_plugin_info.json (Простой JSON-файл, содержащий информацию о вашем плагине)
│  ├── backend/ (Приложение Django вашего плагина, которое будет установлено на бэкенд)
│  │  ├── setup.py
│  │  ├── build.sh (Вызывается при установке плагина в Dockerfile/контейнере)
│  │  ├── runtime_setup.sh (Вызывается при первом запуске контейнера после установки плагина)
│  │  ├── uninstall.sh (Вызывается при удалении плагина из контейнера)
│  │  ├── src/plugin_name/src/config/settings/settings.py (Необязательный файл настроек Django)
│  ├── web-frontend/ (Модуль Nuxt вашего плагина, который будет установлен на фронтенд)
│  │  ├── package.json
│  │  ├── build.sh (Вызывается при установке плагина в Dockerfile/контейнере)
│  │  ├── runtime_setup.sh (Вызывается при первом запуске контейнера после установки плагина)
│  │  ├── uninstall.sh (Вызывается при удалении плагина из контейнера)
│  │  ├── modules/plugin-name/module.js (Файл модуля вашего плагина)

Подпапки backend и web-frontend содержат три файла bash, которые будут автоматически вызываться скриптами плагина Baserow во время установки и удаления. Вы можете использовать эти скрипты для выполнения дополнительных шагов сборки, установки пакетов и других шагов сборки Docker-контейнера.

1. build.sh: Вызывается при сборке плагина в Dockerfile или при запуске контейнера, если происходит установка во время выполнения.
2. runtime_setup.sh: Вызывается при первом запуске контейнера после установки плагина, полезно для выполнения команд суперпользователя на встроенной базе данных, если она существует.
3. uninstall.sh: Вызывается при удалении, база данных будет доступна, поэтому здесь следует выполнять обратные миграции.

Файл информации о плагине

Файл baserow_plugin_info.json — это JSON-файл в корневой папке вашего плагина, содержащий метаданные о вашем плагине. Он должен иметь следующую структуру JSON:

{
  "name": "TODO",
  "version": "TODO",
  "supported_baserow_versions": "1.33.4",
  "plugin_api_version": "0.0.1-alpha",
  "description": "TODO",
  "author": "TODO",
  "author_url": "TODO",
  "url": "TODO",
  "license": "TODO",
  "contact": "TODO"
}

Ожидаемая структура плагина при установке --url или --git

При использовании install_plugin.sh --url URL_TO_PLUGIN_TAR_GZ или install_plugin.sh --git URL_TO_PLUGIN_REPO архив/репозиторий плагина должен содержать одну папку plugins, внутри которой должна быть одна папка плагина, следующая описанной выше структуре и имеющая то же имя, что и ваш плагин. По умолчанию, шаблон плагина генерирует репозиторий с этой структурой. Например, соответствующий архив tar.gz должен содержать что-то вроде:

├─ * (разрешена внешняя обертывающая директория с любым именем, но это не обязательно) 
│  ├── plugins/ 
│  │  ├── plugin_name/
│  │  │  ├── baserow_plugin_info.json 
│  │  │  ├── backend/
│  │  │  ├── web-frontend/

Написание плагина

Теперь вы создали плагин, давайте подробнее рассмотрим, как фактически расширять и настраивать Baserow с помощью вашего плагина.

Сначала вы должны прочитать следующую документацию для базового ознакомления с технической архитектурой Baserow:

1. Техническое введение в Baserow
2. Плагин базы данных

Хранение состояния

Если вашему плагину необходимо хранить состояние, вы должны делать это только в:

1. Базе данных, используемой Baserow
2. С использованием механизма хранения по умолчанию Django
3. В Redis, используемом Baserow, но только для непостоянного состояния, такого как кэш, который можно уничтожить в любой момент.

Никогда не храните состояние внутри папки вашего плагина внутри контейнера. Эта папка удаляется и создается заново в процессе установки плагина, и любое состояние, которое вы храните внутри нее, может быть потеряно.

Написание бэкенд-плагина

Добавление требований Python

Ваш бэкенд-плагин — это обычный модуль Python, который будет установлен в виртуальное окружение Baserow с помощью pip скриптом install_plugin.sh. Если вы используете шаблон плагина, вы можете добавить любые требования Python в файл требований pip, расположенный по пути backend/requirements/base.txt.

Как Django-приложение

Когда служба бэкенда Django Baserow запускается, она ищет любые плагины в папке плагинов, которые имеют подпапку backend. Если она находит какие-либо, она предполагает, что подпапка backend/src/plugin_name/ содержит Django-приложение и добавляет его в INSTALLED_APPS. Это означает, что ваш бэкенд-плагин должен быть Django-приложением, чье имя точно совпадает с именем папки плагина.

В вашем Django-приложении плагина вы можете делать все то же самое, что обычно делаете с Django-приложением, например иметь миграции, использовать метод ready() для конфигурации при запуске и т.д.

Регистры бэкенда

Baserow имеет несколько регистров, которые используются для динамической настройки Baserow. Например, field_type_registry содержит различные реализации класса FieldType.

Каждый регистр содержит различные реализации определенного класса "интерфейса". Регистр в Baserow — это просто одиночный словарь, заполняемый приложениями в их методе ready. Затем различные API-конечные точки Baserow будут использовать эти регистры во время выполнения.

Таким образом, в методе ready вашего Django-приложения плагина вы должны импортировать любые соответствующие регистры и зарегистрировать свои собственные реализации типов полей.

Например, регистр plugin_registry используется для регистрации реализаций интерфейса baserow.core.registries.Plugin. Вы можете создать свой собственный класс, реализующий этот базовый класс, и зарегистрировать его с помощью plugin_registry следующим образом:

from baserow.core.registries import plugin_registry
from django.apps import AppConfig


class PluginNameConfig(AppConfig):
    name = "my_baserow_plugin"

    def ready(self):
        from .plugins import PluginNamePlugin

        plugin_registry.register(PluginNamePlugin())

Вы можете увидеть все разные вещи, которые вы можете динамически зарегистрировать в Baserow с помощью вашего плагина, поискав по кодовой базе Baserow и изучив файлы registry.py и registries.py.

Написание фронтенд-плагина

Добавление требований Node

Ваш фронтенд-плагин — это обычный пакет Node.js, который будет установлен в node_modules Baserow с помощью yarn скриптом install_plugin.sh. Вы можете добавить любые дополнительные требования фронтенда в ваш файл web-frontend/package.json.

Регистры фронтенда

Фронтенд-приложение Nuxt Baserow также следует модели регистров, как и бэкенд. Это означает, что у него есть эквивалентный фронтенд-регистр для большинства бэкенд-регистров, где это имеет смысл. Таким образом, если вы зарегистрируете новый тип поля в бэкенд-регистре, то также убедитесь, что зарегистрируете новый тип поля в фронтенд-регистре.

Публикация вашего плагина

Самый простой способ поделиться вашим плагином с другими — создать публичный репозиторий Git с использованием GitLab, GitHub или другого хостинга Git. После того как вы загрузите папку вашего плагина в репозиторий Git, любой сможет установить ваш плагин, следуя шагам в руководстве по установке плагина.

Также пожалуйста поделитесь и опубликуйте информацию о вашем плагине на нашем подфоруме сообщества плагинов!

Дополнительное чтение

Ознакомьтесь со следующими руководствами в разделе плагинов, которые более подробно рассматривают, например, создание нового типа поля:

1. Руководство по типам приложений
2. Руководство по типам полей
3. Руководство по конвертерам полей
4. Руководство по типам представлений
5. Руководство по типам фильтров представлений