Développer des plugins Discourse - Partie 1 - Créer un plugin de base

[Discourse]

Créer un plugin pour Discourse peut être très simple, une fois que l’on a compris quelques particularités. L’objectif de ce billet est de créer un squelette de plugin et de vous initier aux bases.

Votre environnement de développement

Assurez-vous d’avoir un environnement de développement Discourse en cours d’exécution sur votre ordinateur. Je vous recommande d’utiliser le guide d’installation approprié et de revenir une fois que c’est fait.

plugin.rb

Utilisez GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub pour créer un squelette de plugin Discourse complet dans votre répertoire plugins

Le squelette est désormais inclus dans le cœur de Discourse, rake plugin:create[nom-du-plugin] créera un plugin à partir du squelette

Au démarrage de Discourse, le système recherche dans le répertoire plugins des sous-répertoires contenant un fichier plugin.rb. Le fichier plugin.rb a deux fonctions : il s’agit du manifeste de votre plugin avec les informations requises sur votre plugin, y compris : son nom, les informations de contact et une description. La deuxième fonction est d’initialiser tout le code ruby nécessaire à l’exécution de votre plugin.

Dans notre cas, nous n’ajouterons aucun code ruby, mais nous avons toujours besoin du plugin.rb. Créons le répertoire basic-plugin avec le fichier plugin.rb à l’intérieur, avec le contenu suivant :

basic-plugin/plugin.rb

# name: basic-plugin
# about: A super simple plugin to demonstrate how plugins work
# version: 0.0.1
# authors: Awesome Plugin Developer
# url: https://github.com/yourusername/basic-plugin

Une fois ce fichier créé, vous devriez redémarrer votre serveur local et le plugin devrait être chargé.

Une piège important !

Si vous êtes habitué au développement rails classique, vous remarquerez peut-être que les plugins ne sont pas aussi pratiques en matière de rechargement. En général, lorsque vous apportez des modifications à votre plugin, vous devriez arrêter le serveur avec Ctrl+c, puis le relancer en utilisant bin/dev.

Mes modifications n’ont pas été prises en compte !

Parfois, le cache n’est pas entièrement vidé, en particulier lorsque vous créez de nouveaux fichiers ou supprimez de vieux fichiers. Pour contourner ce problème, supprimez votre dossier tmp et redémarrez rails. Sur un Mac, vous pouvez le faire en une seule commande : rm -rf tmp; bin/dev.

Vérifier que votre plugin a été chargé

Une fois que vous avez redémarré votre serveur local, visitez l’URL /admin/plugins (assurez-vous d’abord d’être connecté en tant que compte administrateur, car seuls les administrateurs peuvent voir le registre des plugins).

Si tout a fonctionné, vous devriez voir votre plugin dans la liste :

Félicitations, vous venez de créer votre premier plugin !

Ajoutons du Javascript

Pour l’instant, votre plugin ne fait rien. Ajoutons un fichier javascript qui affichera une boîte d’alerte lorsque Discourse se charge. Cela sera très agaçant pour tout utilisateur et n’est pas recommandé pour un plugin réel, mais cela montrera comment insérer du Javascript dans notre application en cours d’exécution.

Créez le fichier suivant :

plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js

export default {
  name: "alert",
  initialize() {
    alert("alert boxes are annoying!");
  },
};

Maintenant, si vous redémarrez votre serveur local, vous devriez voir « alert boxes are annoying! » apparaître à l’écran. (Si ce n’est pas le cas, consultez l’en-tête « Mes modifications n’ont pas été prises en compte » ci-dessus).

Décomposons comment cela a fonctionné :

1. Les fichiers Javascript placés dans assets/javascripts/discourse/initializers sont exécutés automatiquement lorsque l’application Discourse se charge.

2. Ce fichier en particulier exporte un objet qui a un name et une fonction initialize.

3. Le name doit être unique, je l’ai donc simplement appelé alert.

4. La fonction initialize() est appelée lorsque l’application se charge. Dans notre cas, elle ne fait qu’exécuter notre code alert().

Vous êtes maintenant un développeur de plugins Discourse officiel !

---

Plus dans la série

Partie 1 : Ce sujet
Partie 2 : Plugin Outlets
Partie 3 : Site Settings
Partie 4 : git setup
Partie 5 : Admin interfaces
Partie 6 : Acceptance tests
Partie 7 : Publish your plugin

---

Ce document est sous contrôle de version - suggérez des modifications sur github.