Creando un complemento

En esta guía, profundizaremos en cómo crear un complemento Climweb, discutiremos la arquitectura del complemento y daremos un complemento de ejemplo para inspirarnos y discutir cómo publicar su complemento.

Arquitectura de complementos

Un complemento ClimWeb es fundamentalmente una carpeta que lleva el nombre del complemento. La carpeta debe ser una Aplicación Django/Wagtail

Inicialice su complemento desde la plantilla del complemento

La plantilla del complemento es una plantilla cookiecutter que genera un complemento con la estructura y los archivos requeridos. Esto garantiza que el complemento siga la estructura esperada y pueda instalarse fácilmente en climweb.

Para crear una instancia de la plantilla, ejecute los siguientes comandos desde el directorio donde desea crear el complemento:

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

Para obtener más detalles sobre el uso del modelo repetitivo del complemento, puede seguir la [guía paso a paso] (#plugin-boilerplate) sobre cómo crear un complemento utilizando el modelo repetitivo del complemento.

API de instalación de complementos

Una imagen acoplable de Climweb contiene los siguientes scripts bash que se utilizan para instalar complementos. Se pueden utilizar para instalar un complemento en un contenedor adl existente en tiempo de ejecución. install_plugin.sh se puede utilizar para instalar un complemento desde una URL, un repositorio de git o una carpeta local en el sistema de archivos.

Puede encontrar estos scripts en las siguientes ubicaciones en las imágenes creadas:

1. /deploy/plugins/install_plugin.sh

En este repositorio, puede encontrar los scripts en la carpeta deploy/plugins.

Estos scripts esperan que un complemento ClimWeb siga las convenciones que se describen a continuación:

Estructura del archivo del complemento

El script install_plugin.sh espera que su complemento tenga una estructura específica de la siguiente manera:

├── 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)

La carpeta contiene tres archivos bash que los scripts del complemento de climweb llamarán automáticamente durante la instalación y desinstalación del complemento. Puede utilizar estos scripts para realizar pasos de compilación adicionales, instalación de paquetes y otros pasos de compilación del contenedor acoplable requeridos por su complemento.

1. build.sh: se llama al iniciar el contenedor si se está realizando una instalación en tiempo de ejecución.

2. runtime_setup.sh: se llama la primera vez que se inicia un contenedor después de instalar el complemento, útil para ejecutar comandos de superusuario en el contenedor.

3. uninstall.sh: Cuando se llama durante la desinstalación, la base de datos estará disponible y, por lo tanto, cualquier migración hacia atrás debe ejecutarse aquí.

El archivo de información del complemento

El archivo climweb_plugin_info.json es un archivo json, en la carpeta raíz del complemento, que contiene metadatos sobre su complemento. Debe tener la siguiente estructura JSON:

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

Estructura de complemento esperada al instalar desde un repositorio de git

Al instalar un complemento desde git, el repositorio debe contener una única carpeta de complementos, dentro de la cual debe haber una única carpeta de complementos que siga la estructura anterior y tenga el mismo nombre que su complemento.

De forma predeterminada, el plugin repetitivo genera un repositorio con esta estructura.

Por ejemplo, un repositorio de git conforme debería contener 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)

Complemento repetitivo

Con el complemento estándar, puede crear fácilmente un nuevo complemento y configurar un entorno de desarrollo de Docker que instale adl como una dependencia. Esto se puede instalar fácilmente mediante cookiecutter.

Creando un complemento

Para utilizar el complemento estándar, primero debe instalar la herramienta Cookiecutter (pip install cookiecutter).

Una vez que haya instalado Cookiecutter, puede ejecutar el siguiente comando para crear un nuevo complemento ADL a partir de nuestra plantilla. En esta guía llamaremos a nuestro complemento «My Climweb Plugin», sin embargo, puede elegir su propio nombre de complemento cuando Cookiecutter se lo solicite.

Nota

El módulo de Python depende del nombre del complemento elegido. Si, por ejemplo, elegimos «My Climweb Plugin», el nombre de la aplicación Django debería 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]:

Si no ve ningún error, significa que su complemento ha sido creado.

Escribir un complemento

Ahora que ha creado un complemento, entremos en más detalles sobre cómo extender y personalizar Climweb usando su complemento.

Estado de almacenamiento

Si su complemento necesita almacenar el estado, solo debe hacerlo en:

• La base de datos utilizada por Climweb

• Usando el mecanismo de almacenamiento predeterminado de Django

• Climweb utiliza Redis, pero solo para un estado no persistente, como un caché que puede destruirse en cualquier momento.

Nota

Nunca almacene ningún estado en la carpeta de su complemento dentro del contenedor. Esta carpeta se elimina y se vuelve a crear como parte del proceso de instalación del complemento y cualquier estado que almacene en ella se puede perder.

Agregar requisitos de Python

Su complemento es solo un módulo de Python normal que se instalará en el entorno virtual de Climweb usando pip mediante install_plugin.sh. Si utiliza el complemento estándar, puede agregar cualquier requisito de Python al archivo de requisitos de pip que se encuentra en requirements/base.txt.

Como aplicación Django/Wagtail

Cuando se inicia el servicio Climweb Django, busca complementos en el directorio de complementos. Si encuentra alguna, asume que la subcarpeta src/plugin_name/ contiene una aplicación Django y la agrega a INSTALLED_APPS. Esto significa que su complemento debe ser una aplicación Django/Wagtail cuyo nombre coincida exactamente con el nombre de la carpeta del complemento.

En la aplicación Django/Wagtail de tu complemento puedes hacer cualquier cosa que normalmente puedes hacer con una aplicación Django/Wagtail, como realizar migraciones, usar el método ready() para realizar la configuración de inicio, etc.

Publicar su complemento

La forma más sencilla de compartir su complemento con otras personas es creando un repositorio git «público» usando GitHub, GitLab o algún otro host git. Una vez que haya enviado su carpeta de complementos al repositorio de git, cualquiera podrá instalar su complemento siguiendo los pasos de la guía de instalación de complementos.