Développement de plugins Discourse - Partie 1 - Créer un plugin basique

[Discourse]

Créer une extension (plugin) pour Discourse peut être très simple une fois que vous avez appris quelques particularités. L’objectif de ce billet est de créer un squelette d’extension et de vous initier aux bases.

Votre environnement de développement

Assurez-vous d’avoir un environnement de développement Discourse fonctionnel sur votre ordinateur. Je vous recommande d’utiliser le guide d’installation approprié et de revenir lorsque vous avez terminé.

plugin.rb

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

Le squelette est maintenant intégré au cœur de Discourse, rake plugin:create[nom-de-l-extension] créera une extension en utilisant le squelette

Lorsque Discourse démarre, il recherche dans le répertoire plugins des sous-répertoires contenant un fichier plugin.rb. Le fichier plugin.rb a deux objectifs : il sert de manifeste pour votre extension avec les informations requises à son sujet, y compris : son nom, les coordonnées et une description. Le second objectif est d’initialiser tout code ruby nécessaire pour exécuter votre extension.

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, contenant ce qui suit :

basic-plugin/plugin.rb

# name: basic-plugin
# about: Une extension super simple pour démontrer le fonctionnement des extensions
# version: 0.0.1
# authors: Awesome Plugin Developer
# url: https://github.com/yourusername/basic-plugin

Une fois que vous avez créé ce fichier, vous devriez redémarrer votre serveur local et l’extension devrait être chargée.

Un piège important !

Si vous êtes habitué au développement Rails classique, vous pourriez remarquer que les extensions ne sont pas aussi pratiques en ce qui concerne le rechargement. En général, lorsque vous apportez des modifications à votre extension, vous devez arrêter le serveur en appuyant sur Ctrl+c, puis le redémarrer en utilisant bin/ember-cli -u.

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

Parfois, le cache n’est pas entièrement vidé, surtout lorsque vous créez de nouveaux fichiers ou supprimez d’anciens 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/ember-cli -u.

Vérifier que votre extension a été chargée

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

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

Félicitations, vous venez de créer votre première extension !

Ajoutons du Javascript

Actuellement, votre extension ne fait rien. Ajoutons un fichier javascript qui affichera une boîte d’alerte lorsque Discourse se charge. Ce sera super ennuyeux pour tout utilisateur et n’est pas recommandé comme extension réelle, 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 le titre “Mes modifications n’ont pas été prises en compte” ci-dessus).

Décortiquons 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 seul objet, qui possède 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, tout ce qu’elle fait est d’exécuter notre code alert().

Vous êtes maintenant un développeur d’extensions Discourse officiel !

---

Plus dans la série

Partie 1 : Ce sujet
Partie 2 : Passerelles d’extension (Plugin Outlets)
Partie 3 : Paramètres du site (Site Settings)
Partie 4 : Configuration Git
Partie 5 : Interfaces d’administration
Partie 6 : Tests d’acceptation
Partie 7 : Publiez votre extension

---

Ce document est contrôlé par version - suggérez des modifications sur github.