Discourse-Plugins und Theme-Komponenten im Überblick

Discourse lässt sich auf zwei Wegen erweitern: mit Theme-Komponenten und mit Plugins. Eine Theme-Komponente besteht aus JavaScript, Templates und SCSS, läuft nur im Browser und wird im Admin-Bereich per Klick installiert. Ein Plugin bringt zusätzlich Ruby-Code für den Server mit, kann Datenbank, Schnittstellen und Logik erweitern und wird beim Neubau der Instanz eingebunden. Die Wahl hängt also davon ab, ob Ihre Idee nur die Oberfläche betrifft oder auch den Server.

Der Unterschied auf einen Blick

Wann reicht eine Theme-Komponente?

Theme-Komponenten decken einen erstaunlich großen Teil üblicher Wünsche ab:

• zusätzliche Links oder Banner im Kopfbereich,
• eigene Schaltflächen in der Themenliste oder im Editor,
• angepasste Darstellung bestimmter Kategorien,
• Hinweise für neue Mitglieder,
• kleine Helfer, die vorhandene Daten anders anzeigen.

Sobald Sie neue Daten speichern, Berechtigungen auf dem Server prüfen, Hintergrundaufgaben ausführen oder fremde Dienste mit geheimen Zugangsdaten anbinden müssen, führt kein Weg am Plugin vorbei. Geheimnisse wie API-Schlüssel gehören nie in eine Theme-Komponente, denn ihr Code ist im Browser jeder Besucherin und jedes Besuchers lesbar.

Aufbau einer Theme-Komponente

meine-komponente/
├── about.json
├── settings.yml
├── common/
│   └── common.scss
├── javascripts/discourse/
│   ├── api-initializers/
│   │   └── hinweis.gjs
│   └── components/
│       └── neulings-hinweis.gjs
└── locales/
    └── de.yml

Die Datei about.json beschreibt die Komponente:

{
  "name": "Neulings-Hinweis",
  "component": true,
  "about_url": "https://example.org/komponente",
  "license_url": "https://example.org/lizenz",
  "authors": "Beispiel"
}

Der eigentliche Code hängt sich über die Plugin-API in die Oberfläche ein. Obwohl der Name anderes vermuten lässt, steht diese API auch Theme-Komponenten zur Verfügung:

// javascripts/discourse/api-initializers/hinweis.gjs
import { apiInitializer } from "discourse/lib/api";
import NeulingsHinweis from "../components/neulings-hinweis";

export default apiInitializer((api) => {
  api.renderInOutlet("above-main-container", NeulingsHinweis);
});

Die Funktion renderInOutlet setzt eine eigene Komponente in einen sogenannten Plugin-Outlet, eine von Discourse vorgesehene Andockstelle in der Oberfläche. Solche Outlets gibt es an vielen Stellen, etwa über dem Hauptinhalt, neben Beiträgen oder in Benutzerprofilen. Weitere Methoden der API verändern Beiträge nach dem Rendern, ergänzen Menüs oder Symbolleisten.

In settings.yml legen Sie Einstellungen an, die Administratoren später im Admin-Bereich ändern können, etwa Texte, Farben oder Kategorien, ohne den Code anzufassen.

Eine settings.yml für den Neulings-Hinweis könnte so aussehen:

hinweis_text:
  default: "Willkommen! Bitte lies zuerst die Community-Regeln."
  description: "Text, der neuen Mitgliedern angezeigt wird"
nur_fuer_neue:
  default: true
  description: "Hinweis nur Mitgliedern mit niedriger Vertrauensstufe zeigen"

Im Code der Komponente stehen die Werte über das globale Objekt settings zur Verfügung. Übersetzbare Texte legen Sie in den Dateien unter locales/ ab, damit die Komponente in mehrsprachigen Communitys funktioniert. Für Daten, die über die Oberfläche hinausgehen, kann eine Komponente die öffentliche JSON-Schnittstelle von Discourse abfragen, allerdings nur mit den Rechten der angemeldeten Person.

Aufbau eines Plugins

discourse-beispiel/
├── plugin.rb
├── config/
│   ├── settings.yml
│   └── locales/
├── app/
│   ├── controllers/
│   └── models/
├── db/migrate/
├── assets/
│   ├── javascripts/discourse/
│   └── stylesheets/
└── spec/

Die zentrale Datei ist plugin.rb. Sie beginnt mit Metadaten in Kommentarzeilen und enthält den Code, der beim Start ausgeführt wird:

# name: discourse-beispiel
# about: Ergänzt Themen um ein Feld für die Bearbeitungsfrist
# version: 0.1.0
# authors: Beispiel
# url: https://example.org/discourse-beispiel

enabled_site_setting :beispiel_enabled

after_initialize do
  # Hier registriert das Plugin z. B. eigene Felder, Routen,
  # Serializer-Erweiterungen oder Event-Handler.
end

Mit enabled_site_setting lässt sich das Plugin im Admin-Bereich ein- und ausschalten. Im Block after_initialize hat das Plugin Zugriff auf die Rails-Anwendung von Discourse. Datenbankänderungen erfolgen über gewöhnliche Rails-Migrationen im Ordner db/migrate. Frontend-Code liegt unter assets/javascripts und nutzt dieselbe Plugin-API wie Theme-Komponenten.

Installation in der Praxis

Theme-Komponente: Im Admin-Bereich unter „Anpassen“ wählen Sie die Installation einer neuen Komponente, geben die Adresse eines Git-Repositorys an oder laden ein Archiv hoch. Anschließend hängen Sie die Komponente an die Themes, in denen sie wirken soll. Deaktivieren und Entfernen funktioniert genauso einfach.

Plugin: Bei der üblichen Docker-basierten Installation tragen Sie in der Konfigurationsdatei des Containers einen git clone-Befehl für das Plugin ein und bauen die Instanz anschließend neu. Der Neubau dauert einige Minuten, in denen das Forum je nach Vorgehen kurz nicht erreichbar ist. Schlägt er wegen eines fehlerhaften Plugins fehl, entfernen Sie den Eintrag und bauen erneut.

Entwickeln und testen

Für Theme-Komponenten gibt es ein Kommandozeilenwerkzeug als Ruby-Gem, das einen lokalen Ordner mit einer Discourse-Instanz verbindet und Änderungen beim Speichern sofort hochlädt. So sehen Sie Ergebnisse ohne Neubau. Für Plugins richten Sie eine lokale Entwicklungsumgebung von Discourse ein, entweder nativ oder per Docker, und legen das Plugin in den Plugin-Ordner. Discourse setzt auf automatisierte Tests: Ruby-Code wird mit RSpec getestet, Frontend-Code mit den Testwerkzeugen von Ember. Beide Erweiterungsarten können eigene Tests mitbringen.

Updates und Kompatibilität

Discourse wird kontinuierlich weiterentwickelt, und das Frontend hat sich in den vergangenen Jahren stark verändert, etwa durch den Wechsel zu Glimmer-Komponenten und neuen Dateiformaten. Ältere Komponenten, die Templates direkt überschreiben, erzeugen in aktuellen Versionen Warnungen oder funktionieren nicht mehr. Verlassen Sie sich deshalb auf Plugin-Outlets und dokumentierte API-Methoden statt auf interne Strukturen. Discourse kündigt geplante Änderungen in der Regel mit Hinweisen in der Konsole an, sodass Sie Zeit für Anpassungen haben.

Für den Fall, dass eine Erweiterung nur mit einer älteren Discourse-Version funktioniert, kann ein Plugin oder eine Komponente in einer Kompatibilitätsdatei festlegen, welcher Stand für welche Discourse-Version verwendet werden soll.

Checkliste vor der Veröffentlichung

• Lässt sich die Funktion als Theme-Komponente umsetzen? Dann kein Plugin bauen.
• Nutzt der Code nur Plugin-Outlets und dokumentierte API-Methoden?
• Sind alle Texte übersetzbar und alle Einstellungen in settings.yml beschrieben?
• Gibt es eine Lizenz und eine kurze Anleitung im Repository?
• Wurde die Erweiterung mit der aktuellen Discourse-Version auf einer Testinstanz geprüft?
• Enthält der Code keine Zugangsdaten oder geheimen Schlüssel?

Einordnung

Discourse folgt damit derselben Lehre wie andere moderne Forensysteme: keine Änderungen am Kern, sondern dokumentierte Andockstellen. Bei phpBB übernehmen das Events und Migrationen, wie der Artikel phpBB-Extension entwickeln zeigt. Wer seine Community eher auf einer Chat-Plattform betreibt, findet den passenden Einstieg unter Discord-App oder Bot?. Wie sich das Erweitern von Foren seit den Zeiten der Datei-Hacks verändert hat, beschreibt die Geschichte der Forensoftware und ihrer Add-ons.