Criando um plug-in

Neste guia iremos nos aprofundar em como criar um plugin Climweb, discutir a arquitetura do plugin e dar um exemplo de plugin para se inspirar e discutir como publicar seu plugin.

Arquitetura de plug-ins

Um Plugin ClimWeb é fundamentalmente uma pasta com o nome do plugin. A pasta deve ser um aplicativo Django/Wagtail

Inicialize seu plugin a partir do modelo de plugin

O modelo de plugin é um modelo cookiecutter que gera um plugin com a estrutura e os arquivos necessários. Isso garante que o plugin siga a estrutura esperada e possa ser facilmente instalado no climweb.

Para instanciar o template, execute os seguintes comandos no diretório onde deseja criar o plugin:

pip install cookiecutter
cookiecutter gh:wmo-raf/climweb --directory plugin-boilerplate

Para obter mais detalhes sobre como usar o plugin padrão, você pode seguir o guia passo a passo sobre como criar um plugin usando o plugin padrão.

API de instalação de plug-ins

Uma imagem docker Climweb contém os seguintes scripts bash que são usados ​​para instalar plug-ins. Eles podem ser usados ​​para instalar um plugin em um contêiner adl existente em tempo de execução. install_plugin.sh pode ser usado para instalar um plugin a partir de uma URL, um repositório git ou uma pasta local no sistema de arquivos.

Você pode encontrar esses scripts nos seguintes locais nas imagens construídas:

  1. /deploy/plugins/install_plugin.sh

Neste repositório, você pode encontrar os scripts na pasta deploy/plugins.

Esses scripts esperam que um plugin ClimWeb siga as convenções descritas abaixo:

Estrutura do arquivo de plug-in

O script install_plugin.sh espera que seu plugin tenha uma estrutura específica como segue:

├── plugin_name
│  ├── climweb_plugin_info.json (A simple json file containing info about your plugin)
|  ├── setup.py
|  ├── build.sh (Called when installing the plugin in a Dockerfile/container)
|  ├── runtime_setup.sh (Called on first runtime startup of the plugin)
|  ├── uninstall.sh (Called when uninstalling the plugin in a container)
|  ├── src/plugin_name/src/config/settings/settings.py (Optional Django setting file)

A pasta contém três arquivos bash que serão chamados automaticamente pelos scripts do plugin do climweb durante a instalação e desinstalação do plugin. Você pode usar esses scripts para executar etapas extras de construção, instalação de pacotes e outras etapas de construção do contêiner docker exigidas pelo seu plug-in.

  1. build.sh: Chamado na inicialização do contêiner se uma instalação em tempo de execução estiver ocorrendo.

  2. runtime_setup.sh: Chamado na primeira vez que um contêiner é iniciado após a instalação do plugin, útil para executar comandos de superusuário no contêiner.

  3. uninstall.sh: Chamado na desinstalação, o banco de dados estará disponível e qualquer migração retroativa deverá ser executada aqui.

O arquivo de informações do plugin

O arquivo climweb_plugin_info.json é um arquivo json, na pasta raiz do plugin, contendo metadados sobre o seu plugin. Deve ter a seguinte estrutura JSON:

{
  "name": "TODO",
  "version": "TODO",
  "description": "TODO",
  "author": "TODO",
  "author_url": "TODO",
  "url": "TODO",
  "license": "TODO",
  "contact": "TODO"
}

Estrutura esperada do plugin ao instalar a partir de um repositório git

Ao instalar um plugin do git, o repositório deve conter uma única pasta de plugins, dentro da qual deve haver uma única pasta de plugins seguindo a estrutura acima e com o mesmo nome do seu plugin.

Por padrão, o plugin boilerplate gera um repositório com esta estrutura.

Por exemplo, um repositório git compatível deve conter algo como:

├─ * (an outermost wrapper directory named anything is allowed but not required) 
│  ├── plugins/ 
│  │  ├── plugin_name
│  |  |  ├── climweb_plugin_info.json
|  |  |  ├── setup.py
|  |  |  ├── build.sh
|  |  |  ├── runtime_setup.sh
|  |  |  ├── uninstall.sh
|  |  |  ├── src/plugin_name/src/config/settings/settings.py (Optional Django setting file)

Padrão de plug-in

Com o plugin padrão você pode facilmente criar um novo plugin e configurar um ambiente de desenvolvimento docker que instala o adl como uma dependência. Isso pode ser facilmente instalado via cookiecutter.

Criando um plug-in

Para usar o plugin padrão você deve primeiro instalar a ferramenta Cookiecutter (pip install cookiecutter).

Depois de instalar o Cookiecutter, você pode executar o seguinte comando para criar um novo plugin ADL a partir do nosso modelo. Neste guia nomearemos nosso plugin “My Climweb Plugin”, porém você pode escolher o nome do seu próprio plugin quando solicitado pelo Cookiecutter.

Nota

O módulo python depende do nome do plugin escolhido. Se, por exemplo, escolhermos “My Climweb Plugin”, o nome do aplicativo Django deve ser my_climweb_plugin

cookiecutter gh:wmo-raf/climweb --directory plugin-boilerplate
project_name [My Climweb Plugin]: 
project_slug [my-climweb-plugin]: 
project_module [my_climweb_plugin]:

Se você não encontrar nenhum erro, significa que seu plugin foi criado.

Escrevendo um plug-in

Agora que você criou um plugin, vamos entrar em mais detalhes sobre como realmente estender e personalizar o Climweb usando seu plugin.

Armazenando Estado

Se o seu plugin precisar armazenar estado, você só deve fazer isso em:

  • O banco de dados que está sendo usado pelo Climweb

  • Usando o mecanismo de armazenamento padrão do Django

  • O Redis sendo usado pelo Climweb, mas apenas para estados não persistentes como um cache que pode ser destruído a qualquer momento.

Nota

Nunca armazene nenhum estado na própria pasta do plugin dentro do contêiner. Esta pasta é excluída e recriada como parte do processo de instalação do plugin e qualquer estado armazenado dentro dela pode ser perdido.

Adicionando Requisitos Python

Seu plugin é apenas um módulo python normal que será instalado no ambiente virtual Climweb usando pip por install_plugin.sh. Se estiver usando o plugin padrão, você pode adicionar quaisquer requisitos python ao arquivo de requisitos pip encontrado em requirements/base.txt.

Como um aplicativo Django/Wagtail

Quando o serviço Climweb Django é iniciado, ele procura por plug-ins no diretório de plug-ins. Se encontrar algum, ele assume que a subpasta src/plugin_name/ contém um aplicativo Django e o adiciona ao INSTALLED_APPS. Isso significa que seu plugin deve ser um aplicativo Django/Wagtail cujo nome corresponda exatamente ao nome da pasta do plugin.

No aplicativo Django/Wagtail do seu plugin você pode fazer qualquer coisa que normalmente faria com um aplicativo Django/Wagtail, como fazer migrações, usar o método ready() para fazer a configuração de inicialização, etc.

Publicando seu plugin

A maneira mais fácil de compartilhar seu plugin com outras pessoas é criar um repositório git público usando GitHub, GitLab ou algum outro host git. Depois de enviar a pasta do plug-in para o repositório git, qualquer pessoa poderá instalar o plug-in seguindo as etapas do guia de instalação do plug-in.