Créer un plugin¶

Dans ce guide, nous allons expliquer comment créer un plugin Climweb, discuter de l’architecture du plugin et donner un exemple de plugin pour vous inspirer et discuter de la façon de publier votre plugin.

Architecture des plugins¶

Un plugin ClimWeb est fondamentalement un dossier nommé d’après le plugin. Le dossier doit être une Django/Wagtail App

Initialisez votre plugin à partir du modèle de plugin¶

Le modèle de plugin est un modèle cookiecutter qui génère un plugin avec la structure et les fichiers requis. Cela garantit que le plugin suit la structure attendue et peut être facilement installé dans climweb.

Pour instancier le modèle, exécutez les commandes suivantes à partir du répertoire dans lequel vous souhaitez créer le plugin :

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

Pour plus de détails sur l’utilisation du passe-partout du plugin, vous pouvez suivre le guide étape par étape sur la création d’un plugin à l’aide du passe-partout du plugin.

API d’installation de plugins¶

Une image docker Climweb contient les scripts bash suivants qui sont utilisés pour installer les plugins. Ils peuvent être utilisés pour installer un plugin dans un conteneur adl existant au moment de l’exécution. install_plugin.sh peut être utilisé pour installer un plugin à partir d’une URL, d’un dépôt git ou d’un dossier local sur le système de fichiers.

Vous pouvez trouver ces scripts aux emplacements suivants dans les images créées :

/deploy/plugins/install_plugin.sh

Sur ce dépôt, vous pouvez trouver les scripts dans le dossier deploy/plugins.

Ces scripts attendent d’un plugin ClimWeb qu’il suive les conventions décrites ci-dessous :

Structure des fichiers du plugin¶

Le script install_plugin.sh s’attend à ce que votre plugin ait une structure spécifique comme suit :

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

Le dossier contient trois fichiers bash qui seront automatiquement appelés par les scripts du plugin de climweb lors de l’installation et de la désinstallation du plugin. Vous pouvez utiliser ces scripts pour effectuer des étapes de construction supplémentaires, l’installation de packages et d’autres étapes de construction de conteneur Docker requises par votre plugin.

build.sh : appelé au démarrage du conteneur si une installation d’exécution est en cours.
runtime_setup.sh : appelé la première fois qu’un conteneur démarre après l’installation du plugin, utile pour exécuter des commandes de superutilisateur sur le conteneur.
uninstall.sh : appelée lors de la désinstallation, la base de données sera disponible et donc toute migration vers l’arrière doit être exécutée ici.

Le fichier d’informations du plugin¶

Le fichier climweb_plugin_info.json est un fichier json, dans le dossier racine de votre plugin, contenant des métadonnées sur votre plugin. Il doit avoir la structure JSON suivante :

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

Structure de plugin attendue lors de l’installation à partir d’un référentiel git¶

Lors de l’installation d’un plugin à partir de git, le dépôt doit contenir un seul dossier de plugins, à l’intérieur duquel se trouve un seul dossier de plugin suivant la structure ci-dessus et portant le même nom que votre plugin.

Par défaut, le « plugin standard » génère un référentiel avec cette structure.

Par exemple, un dépôt git conforme devrait contenir quelque chose comme :

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

Modèle de plugin¶

Avec le passe-partout du plugin, vous pouvez facilement créer un nouveau plugin et configurer un environnement de développement Docker qui installe adl en tant que dépendance. Cela peut facilement être installé via un emporte-pièce.

Création d’un plugin¶

Pour utiliser le passe-partout du plugin, vous devez d’abord installer l’outil Cookiecutter (pip install cookiecutter).

Une fois que vous avez installé Cookiecutter, vous pouvez exécuter la commande suivante pour créer un nouveau plugin ADL à partir de notre modèle. Dans ce guide, nous nommerons notre plugin « My Climweb Plugin », mais vous pouvez choisir votre propre nom de plugin lorsque Cookiecutter vous le demande.

Note

Le module python dépend du nom du plugin choisi. Si nous choisissons par exemple « My Climweb Plugin », le nom de l’application Django devrait être 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 vous ne voyez aucune erreur, cela signifie que votre plugin a été créé.

Écrire un plugin¶

Maintenant que vous avez créé un plugin, expliquons plus en détail comment étendre et personnaliser Climweb à l’aide de votre plugin.

État de stockage¶

Si votre plugin doit stocker l’état, vous ne devez le faire que dans :

La base de données utilisée par Climweb
Utiliser le mécanisme de stockage par défaut de Django
Le Redis est utilisé par Climweb, mais uniquement pour un état non persistant comme un cache qui peut être détruit à tout moment.

Note

Ne stockez jamais d’état dans le dossier de votre plugin lui-même à l’intérieur du conteneur. Ce dossier est supprimé et recréé dans le cadre du processus d’installation du plugin et tout état que vous y stockez peut être perdu.

Ajout d’exigences Python¶

Votre plugin est juste un module python normal qui sera installé dans l’environnement virtuel Climweb en utilisant pip par install_plugin.sh. Si vous utilisez le passe-partout du plugin, vous pouvez ajouter toutes les exigences Python au fichier d’exigences pip trouvé dans requirements/base.txt.

En tant qu’application Django/Wagtail¶

Lorsque le service Climweb Django démarre, il recherche tous les plugins dans le répertoire des plugins. S’il en trouve, il suppose que le sous-dossier src/plugin_name/ contient une application Django et l’ajoute à INSTALLED_APPS. Cela signifie que votre plugin doit être une application Django/Wagtail dont le nom correspond exactement au nom du dossier du plugin.

Dans l’application Django/Wagtail de votre plugin, vous pouvez faire tout ce que vous pouvez normalement faire avec une application Django/Wagtail, comme effectuer des migrations, utiliser la méthode ready() pour effectuer la configuration de démarrage, etc.

Publier votre plugin¶

Le moyen le plus simple de partager votre plugin avec d’autres est de créer un référentiel git « public » en utilisant GitHub, GitLab ou un autre hôte git. Une fois que vous avez poussé votre dossier de plugin vers le référentiel git, n’importe qui peut alors installer votre plugin en suivant les étapes du guide d’installation du plugin.