Die Entwicklung eines Plugins für Discourse kann wirklich einfach sein, sobald man ein paar Eigenheiten kennengelernt hat. Ziel dieses Beitrags ist es, ein Grundgerüst (Skeleton) für ein Plugin zu erstellen und die Grundlagen einzuführen.
Deine Entwicklungsumgebung
Stelle sicher, dass auf deinem Computer eine Entwicklungsumgebung für Discourse läuft. Ich empfehle, den entsprechenden Einrichtungsleitfaden zu verwenden und zurückzukommen, wenn du damit fertig bist.
plugin.rb
Nutze GitHub - discourse/discourse-plugin-skeleton: Template for Discourse plugins · GitHub, um ein vollständiges Grundgerüst für ein Discourse-Plugin in deinem Plugins-Verzeichnis zu erstellen
Das Grundgerüst ist nun in Discourse Core enthalten. Mit
rake plugin:create[plugin-name]erstellst du ein Plugin auf Basis des Grundgerüsts.
Beim Start sucht Discourse im Verzeichnis plugins nach Unterordnern, die eine Datei plugin.rb enthalten. Die Datei plugin.rb hat zwei Zwecke: Sie dient als Manifest für dein Plugin mit den erforderlichen Informationen wie Name, Kontaktdaten und Beschreibung. Der zweite Zweck besteht darin, jeden Ruby-Code zu initialisieren, der für den Betrieb deines Plugins nötig ist.
In unserem Fall fügen wir keinen Ruby-Code hinzu, aber wir benötigen weiterhin die plugin.rb. Lassen Sie uns das Verzeichnis basic-plugin mit der darin enthaltenen Datei plugin.rb erstellen, die folgenden Inhalt hat:
basic-plugin/plugin.rb
# name: basic-plugin
# about: Ein super einfaches Plugin, das die Funktionsweise von Plugins demonstriert
# version: 0.0.1
# authors: Awesome Plugin Developer
# url: https://github.com/yourusername/basic-plugin
Nachdem du diese Datei erstellt hast, solltest du deinen lokalen Server neu starten, damit das Plugin geladen wird.
Ein wichtiger Stolperstein!
Wenn du an die normale Rails-Entwicklung gewohnt bist, fällt dir vielleicht auf, dass Plugins nicht so angenehm im Reload-Verhalten sind. Im Allgemeinen solltest du bei Änderungen an deinem Plugin den Server mit Ctrl+c stoppen und ihn anschließend mit bin/dev wieder starten.
Meine Änderungen wurden nicht übernommen! 
Manchmal wird der Cache nicht vollständig geleert, insbesondere wenn du neue Dateien erstellst oder alte löschst. Um dieses Problem zu umgehen, entferne den Ordner tmp und starte Rails erneut. Auf einem Mac kannst du dies mit einem einzigen Befehl tun: rm -rf tmp; bin/dev.
Prüfen, ob dein Plugin geladen wurde
Nach dem Neustart des lokalen Servers rufe die URL /admin/plugins auf (stelle sicher, dass du zuvor als Admin angemeldet bist, da nur Admins die Plugin-Registry sehen können).
Wenn alles geklappt hat, sollte dein Plugin in der Liste erscheinen:
Glückwunsch, du hast gerade dein erstes Plugin erstellt!
Fügen wir etwas JavaScript hinzu
Momentan macht dein Plugin nichts. Lass uns eine JavaScript-Datei hinzufügen, die beim Laden von Discourse ein Alert-Fenster anzeigt. Dies wird für jeden Benutzer extrem nervig sein und ist nicht als reales Plugin empfohlen, aber es zeigt, wie man JavaScript in unsere laufende Anwendung einfügt.
Erstelle die folgende Datei:
plugins/basic-plugin/assets/javascripts/discourse/initializers/alert.js
export default {
name: "alert",
initialize() {
alert("alert boxes are annoying!");
},
};
Wenn du jetzt deinen lokalen Server neu startest, sollte „alert boxes are annoying!“ auf dem Bildschirm erscheinen. (Falls nicht, siehe oben die Überschrift „Meine Änderungen wurden nicht übernommen“).
Schauen wir uns an, wie das funktioniert:
-
JavaScript-Dateien im Ordner
assets/javascripts/discourse/initializerswerden automatisch ausgeführt, wenn die Discourse-Anwendung lädt. -
Diese spezifische Datei
exports ein Objekt, das einennameund eineinitialize-Funktion enthält. -
Der
namemuss eindeutig sein, daher habe ich ihn einfachalertgenannt. -
Die
initialize()-Funktion wird beim Laden der Anwendung aufgerufen. In unserem Fall führt sie lediglich unserenalert()-Code aus.
Daten für das Frontend vorladen
Nutze register_preloaded_data in plugin.rb, um Daten in der initialen HTML-Antwort zu enthalten, ohne eine zusätzliche Anfrage:
after_initialize do
register_preloaded_data("visibility") do |guardian|
{ can_access: guardian.authenticated? }
end
end
Core stellt dem Schlüssel den # name:-Metadaten-Wert des Plugins voran. Für das obige basic-plugin liest du den analysierten Wert im Frontend-Initializer mit:
import PreloadStore from "discourse/lib/preload-store";
const visibility = PreloadStore.get("basic-plugin:visibility");
Der Block wird bei jedem Seitenaufruf ausgeführt, der das Anwendungs-Layout rendert, erhält den Guardian der Anfrage und gibt einen JSON-serialisierbaren Wert zurück. Diese Werte sind getrennt vom gecachten anonymen Site-Payload. Gib nil zurück, um einen Eintrag wegzulassen; false wird einbezogen. Blöcke deaktivierter Plugins werden übersprungen. Schütze sensible Daten, indem du sie über den Guardian auf den anfordernden Benutzer beschränkst.
Du bist jetzt ein offizieller Discourse-Plugin-Entwickler!
Mehr in der Serie
Teil 1: Dieses Thema
Teil 2: Plugin Outlets
Teil 3: Site-Einstellungen
Teil 4: git-Setup
Teil 5: Admin-Schnittstellen
Teil 6: Akzeptanztests
Teil 7: Veröffentlichen deines Plugins
Dieses Dokument ist versioniert – schlage Änderungen auf github vor.

