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

[Discourse]

La création d’un plugin Discourse peut être vraiment simple, une fois que vous avez appris quelques particularités. L’objectif de ce message 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 vous avez terminé.

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 noyau de Discourse, rake plugin:create[nom-du-plugin] créera un plugin en utilisant le squelette

Au démarrage, Discourse recherche dans le répertoire plugins les sous-répertoires contenant un fichier plugin.rb. Le fichier plugin.rb a deux objectifs : il sert de manifeste pour votre plugin avec les informations requises à propos de votre plugin, y compris : son nom, les coordonnées et une description. Le deuxième objectif est d’initialiser tout code Ruby nécessaire au fonctionnement de votre plugin.

Dans notre cas, nous n’ajouterons aucun code Ruby, mais nous aurons quand même besoin du fichier 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: Un plugin très simple pour démontrer le fonctionnement des plugins
# version: 0.0.1
# authors: Super Développeur de Plugins
# url: https://github.com/votre_nom_utilisateur/basic-plugin

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

Une astuce importante !

Si vous êtes habitué au développement Rails classique, vous remarquerez peut-être que les plugins ne sont pas aussi pratiques en ce qui concerne le rechargement. En général, lorsque vous apportez des modifications à votre plugin, vous devriez Ctrl+c le serveur pour l’arrêter, 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 des anciens fichiers. Pour contourner ce problème, supprimez votre dossier tmp et relancez 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, rendez-vous sur l’URL /admin/plugins (assurez-vous d’être connecté en tant que compte administrateur au préalable, car seuls les administrateurs peuvent voir le registre des plugins).

Si tout s’est bien passé, vous devriez voir votre plugin dans la liste :

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

Ajoutons un peu de 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é en tant que 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("les boîtes d’alerte sont agaçantes !");
  },
};

Si vous redémarrez maintenant votre serveur local, vous devriez voir apparaître « les boîtes d’alerte sont agaçantes ! » à l’écran. (Si ce n’est pas le cas, consultez la section « 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 particulier exporte un objet, qui possède un name et une fonction initialize.

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

4. La fonction initialize() est appelée lorsque l’application se charge. Dans notre cas, elle se contente d’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 : Points d’extension de plugin
Partie 3 : Paramètres du site
Partie 4 : Configuration git
Partie 5 : Interfaces administrateur
Partie 6 : Tests d’acceptation
Partie 7 : Publier votre plugin

---

Ce document est versionné - proposez des modifications sur github.