Vorheriges Tutorial: Developing Discourse Plugins - Part 2 - Connect to a plugin outlet
Site Settings (Site-Einstellungen)
Wenn Sie /admin/site_settings auf einer Discourse-Instanz besuchen, auf der Sie Administratorrechte haben, sehen Sie eine Liste von Konfigurationseinstellungen. Standardmäßig liefern wir die Einstellungen, die unserer Meinung nach für eine Discourse-Installation am besten geeignet sind, aber wir verstehen auch, dass Benutzer ihre Installationen anpassen möchten, um ihr Forum genau so zu gestalten, wie sie es wünschen.
Wenn Ihr Plugin nicht sehr einfach ist, möchten Sie wahrscheinlich Einstellungen hinzufügen, die die Benutzer Ihres Plugins ändern und zur Konfiguration der Funktionalität verwenden können. Glücklicherweise ist dies recht einfach zu bewerkstelligen!
config/settings.yml
Das Erste, was Sie tun müssen, ist, config/settings.yml in Ihrem Plugin-Ordner zu erstellen. Diese Datei listet alle Einstellungen auf, die Ihr Plugin benötigt. Hier ist eine Beispiel-Datei:
plugins:
awesomeness_enabled:
default: true
client: true
awesomeness_max_volume:
default: 10
client: true
Die Datei muss im YAML-Format vorliegen. YAML kann sehr heikel sein. Wenn Discourse Probleme beim Laden Ihrer Einstellungen hat, empfehle ich Ihnen, Ihr YAML mit einem Tool wie YAMLint zu validieren.
Ich werde die Beispieldatei im Detail erläutern. Die oberste Ebene ist plugins, und das teilt Discourse mit, dass wir möchten, dass diese Einstellungen unter „Plugins“ in den Site-Einstellungen angezeigt werden.
Danach werden zwei Einstellungen deklariert: awesomeness_enabled und awesomeness_max_volume. Discourse leitet den Typ der Einstellungen vom Standardwert ab, daher ist awesomeness_enabled ein Boolescher Wert und awesomeness_max_volume eine Zahl.
Das client: true ist wichtig zu verstehen. Discourse besteht aus zwei Hauptanwendungen: der serverseitigen API, geschrieben in Ruby on Rails, und der clientseitigen Anwendung, geschrieben in Ember.js. Standardmäßig stellen wir Einstellungen der Ember.js-Clientanwendung nicht zur Verfügung, es sei denn, Sie fügen client: true hinzu. Wir tun dies, weil einige Einstellungen privat sind, wie z. B. API-Schlüssel, und nicht an Endbenutzer gesendet werden sollten. Außerdem könnte das Senden jeder Einstellung an den Client für Endbenutzer eine große Downloadmenge bedeuten!
In unserem Beispiel möchten wir, dass beide Einstellungen sowohl in der JavaScript-Welt als auch in der serverseitigen Welt zugänglich sind.
Ein wichtiger zweiter Schritt
Bevor Sie Ihre neu hinzugefügten Site-Einstellungen verwenden können, müssen Sie Übersetzungen dafür hinzufügen. Da Discourse viele Sprachen unterstützt, muss jeder von Ihnen hinzugefügte Text die Übersetzung in andere Sprachen unterstützen.
Erstellen wir die Übersetzungen für unsere Einstellungen auf Englisch:
config/locales/server.en.yml
en:
site_settings:
awesomeness_enabled: "Is this plugin awesome?"
awesomeness_max_volume: "What is the maximum volume possible?"
Die in dieser Datei hinzugefügten Bezeichnungen werden im Admin-Bereich angezeigt. Es ist eine gute Idee, so klar wie möglich zu beschreiben, was die Einstellung bewirkt.
Deklarieren der Einstellung als „aktivierte Einstellung“
Nachdem wir nun unsere Site-Einstellung haben, sollten wir Discourse mitteilen, dass dies die Einstellung ist, die unsere Funktionen ein- und ausschaltet.
Öffnen Sie Ihre plugin.rb-Datei und fügen Sie die folgende Zeile unter den Metadaten-Kommentaren hinzu:
enabled_site_setting :awesomeness_enabled
Stellen Sie sicher, dass alle Ihre anderen Einstellungen mit „awesomeness_“ beginnen, damit die Einstellungs-Schaltfläche unter /admin/plugins korrekt funktioniert.
Zugriff auf Ihre neuen Einstellungen
Zuerst müssen Sie Ihren Entwicklungsserver neu starten, damit die Einstellungen wirksam werden. Sobald Sie dies getan haben, sollten die Einstellungen für Ihren Server- und Client-Code verfügbar sein.
Wir injizieren die Site-Einstellungen automatisch in die meisten JavaScript-Objekte. Wenn Sie also eine Component, Controller, Route, View oder Model deklarieren, sollten Sie auf die Site-Einstellung zugreifen können, indem Sie einfach this.siteSettings.awesomeness_enabled verwenden. In den meisten Handlebars-Vorlagen sollten Sie auch {{siteSettings.awesomeness_enabled}} sagen können, und der Einstellungswert wird angezeigt.
Wir haben in dieser Reihe noch nicht viel über Ruby-Sachen behandelt, aber wenn Sie in der Ruby-Anwendung auf die Site-Einstellungen zugreifen möchten, können Sie dies über tun: SiteSetting.awesomeness_enabled
Gehen Sie nun vor und fügen Sie Ihren Plugins benutzerdefinierte Einstellungen hinzu!
Mehr in der Serie
Teil 1: Plugin Basics
Teil 2: Plugin Outlets
Teil 3: Dieses Thema
Teil 4: git setup
Teil 5: Admin interfaces
Teil 6: Acceptance tests
Teil 7: Publish your plugin
Dieses Dokument wird versioniert – schlagen Sie Änderungen auf github vor.
