Discourse bietet die Möglichkeit, dass Themes über „Einstellungen“ verfügen, die von Theme-Entwicklern hinzugefügt werden können, um Site-Betreibern die Anpassung von Themes über die Benutzeroberfläche zu ermöglichen, ohne dass eine einzige Zeile Code geändert werden muss und ohne sich Sorgen machen zu müssen, dass Änderungen bei zukünftigen Theme-Updates verloren gehen.
Themes können auch bestimmte anpassbare Site-Einstellungen ändern. Weitere Informationen dazu finden Sie im Thema Themeable site settings.
Hinzufügen von Einstellungen zu Ihrem Theme
Das Hinzufügen von Einstellungen zu Ihrem Theme unterscheidet sich etwas vom Hinzufügen von CSS- und JS-Code, da es dafür keinen Weg über die Benutzeroberfläche gibt.
Der Weg, um Einstellungen hinzuzufügen, besteht darin, ein Repository für Ihr Theme zu erstellen und im Wurzelordner Ihres Repositories eine neue settings.yaml- (oder settings.yml-)Datei anzulegen. In dieser Datei verwenden Sie die YAML-Sprache, um Ihre Theme-Einstellungen zu definieren.
Hinweis: Es kann hilfreich sein, die Theme CLI zu nutzen, die den Entwicklungsprozess erheblich vereinfacht.
Falls Sie mit der Plugin-Entwicklung vertraut sind, sollte Ihnen das kein Unbekanntes sein – es funktioniert größtenteils so wie das Hinzufügen von Site-Einstellungen zu Ihrem Plugin. Fügen Sie einfach gültiges YAML in Ihre Einstellungsdatei ein, und Sie sind startklar.
Eine gültige Theme-Einstellung muss einen Namen und einen Standardwert haben. Das ist das Minimum und sieht so aus:
simple_setting: true
Wie Sie wahrscheinlich erkennen können, erstellt dies eine Einstellung mit dem Namen simple_setting, die true als Standardwert hat.
Ähnlich können Sie Folgendes hinzufügen:
site_name: My Forums
max_avatars: 7
Und Sie haben zwei weitere Einstellungen: site_name, eine String-Einstellung mit “My Forums” als Standardwert, und max_avatars als Integer-Einstellung mit dem Standardwert 7.
Sie können auf Ihre Einstellungen in Ihrem JS-Code so zugreifen: settings.your_setting_key.
Bis zu diesem Punkt haben wir die einfachste Art und Weise abgedeckt, Einstellungen zu definieren. Im nächsten Abschnitt werden wir etwas tiefer in die verschiedenen Einstellungstypen eintauchen und wie Sie diese verwenden können.
Unterstützte Typen
Es gibt 9 Typen von Einstellungen:
integerfloatstringbool(für Boolesche Werte)listenumobjects(Ersatz fürjson_schema)upload(für Bilder)icon(für ein einzelnes Icon aus dem Discourse-Icon-Set)
Sie können den Typ angeben, indem Sie ein type-Attribut zu Ihrer Einstellung hinzufügen, wie folgt:
float_setting:
type: float
default: 3.14
Ich sollte erwähnen, dass Sie nicht immer ein type-Attribut explizit setzen müssen, da Discourse schlau genug ist, den Einstellungstyp aus dem Standardwert der Einstellung abzuleiten. Sie können das obige Beispiel also auf Folgendes reduzieren:
float_setting:
default: 3.14
Dennoch müssen Sie ein type-Attribut setzen, wenn Sie mit list, enum und icon-Einstellungen arbeiten, da Discourse sie andernfalls nicht korrekt erkennt.
List-Einstellung:
whitelisted_fruits:
default: apples|oranges
type: list
Enum-Einstellung:
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Falls Ihnen der Unterschied zwischen List- und Enum-Einstellungen nicht klar ist: Enum-Einstellungen erlauben es Ihren Theme-Nutzern, nur einen Wert aus einem von Ihnen definierten Werteset auszuwählen (siehe das choices-Attribut).
Andererseits erlauben List-Einstellungen Ihren Benutzern, ihre eigene Liste (d. h. ein Array) von Werten zu erstellen. Sie können der Standardliste der Einstellungswerte hinzufügen oder Werte daraus entfernen.
Sie können die Standardliste der Werte für die Einstellung festlegen, indem Sie die Werte mit einem vertikalen Strich | verbinden. Siehe die List-Einstellung im obigen Beispiel.
Sie können einen praktischen Anwendungsfall für List-Einstellungen hier sehen: Auto-Linkify Words.
Icon-Einstellung:
banner_icon:
default: bullhorn
type: icon
Icon-Einstellungen geben Site-Betreibern einen durchsuchbaren Icon-Auswahlbereich, und der Wert ist der Icon-Name. Discourse fügt das ausgewählte Icon dem Spritesheet hinzu, sodass Sie es in Ihrem Theme rendern können, ohne es separat zu registrieren.
objects-Typ
Der objects-Einstellungstyp ist ein spezieller Typ, der es Ihnen ermöglicht, fortgeschrittene Einstellungen mit benutzerdefinierter Struktur und Validierungen zu erstellen. Wir haben eine separate Dokumentation für diesen Typ.
Beschreibung und Lokalisierungen der Einstellung
Sie können Ihrem Theme-Setting Beschreibungstext hinzufügen, der als Label direkt unter der Einstellung angezeigt wird. Fügen Sie dazu einfach ein description-Attribut zu Ihrer Einstellung hinzu, wie folgt:
whitelisted_fruits:
default: apples|oranges
type: list
description: "Dieser Text wird unter dieser Einstellung angezeigt und erklärt, was die Einstellung tut!"
Und Sie erhalten Folgendes:
Unterstützung mehrerer Sprachen
Wenn Sie mehr als eine Sprache beherrschen und Ihrer Theme Unterstützung für diese Sprachen hinzufügen möchten, können Sie das tun, sofern Discourse diese Sprachen unterstützt.
Zunächst stellen Sie sicher, dass die Sprache, die Sie unterstützen möchten, in dieser Liste enthalten ist:
Sprachenliste
| Code | Name | |||
|---|---|---|---|---|
| ar | اللغة العربية | |||
| bs_BA | bosanski jezik | |||
| ca | català | |||
| cs | čeština | |||
| da | dansk | |||
| de | Deutsch | |||
| el | ελληνικά | |||
| en | English | |||
| es | Español | |||
| et | eesti | |||
| fa_IR | فارسی | |||
| fi | suomi | |||
| fr | Français | |||
| gl | galego | |||
| he | עברית | |||
| id | Indonesian | |||
| it | Italiano | |||
| ja | 日本語 | |||
| ko | 한국어 | |||
| lv | latviešu valoda | |||
| nb_NO | Norsk bokmål | |||
| nl | Nederlands | |||
| pl_PL | język polski | |||
| pt | Português | |||
| pt_BR | Português (BR) | |||
| ro | limba română | |||
| ru | Русский | |||
| sk | slovenčina | |||
| sq | Shqip | |||
| sr | српски језик | |||
| sv | svenska | |||
| te | తెలुగు | |||
| th | ไทย | |||
| tr_TR | Türkçe | |||
| uk | українська мова | |||
| ur | اردو | |||
| vi | Việt Nam | |||
| zh_CN | 中文 | |||
| zh_TW | 中文 (TW) |
(Falls Sie Ihre Sprache nicht in der Liste sehen, könnten Sie sich How to add a new language ansehen)
Dann müssen Sie Ihren Sprachcode aus der obigen Liste finden und den Sprachcode als Schlüssel unter dem description-Attribut verwenden und die Übersetzung als Wert für den Schlüssel, wie folgt:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: English text
ar: نص باللغة العربية
fr: Texte français
Und jetzt haben Sie Unterstützung für 3 Sprachen: Englisch, Arabisch und Französisch.
Zusätzliche Attribut- und Optionseinstellungen
Min- und Max-Attribute
Manchmal müssen Sie Grenzen festlegen, die ein Einstellungswert nicht überschreiten darf, um zu verhindern, dass Ihre Benutzer versehentlich das Theme oder möglicherweise die gesamte Site beschädigen.
Um Grenzen festzulegen, fügen Sie einfach ein min- oder max-Attribut oder beide zu Ihrer Einstellung hinzu, wie folgt:
integer_setting:
default: 10
min: 5
max: 100
Sie können Grenzen für Einstellungen vom Typ integer, float und string festlegen. Bei integer- und float-Einstellungen wird der Wert der Einstellung selbst gegen die Grenzen geprüft. Und bei string-Einstellungen wird die Länge des Werts gegen die festgelegten Grenzen geprüft.
Wenn Ihr Benutzer versucht, einen Wert einzugeben, der nicht im erlaubten Bereich liegt, sieht er einen Fehler, der ihm die Min- und Max-Werte mitteilt.
Zugriff auf Einstellungen in Ihrem JS/CSS/Handlebars
Theme-Einstellungen stehen global als settings-Variable in Theme-JavaScript-Dateien zur Verfügung. Zum Beispiel:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("settings are", settings);
});
Dieses settings-Objekt kann auch innerhalb von .gjs <template>-Tags normal verwendet werden.
Festlegen von CSS-Variablen
In CSS wird für jede Einstellung Ihres Themes eine Variable erstellt, und jede Variable hat denselben Namen wie die Einstellung, die sie darstellt.
Wenn Sie also eine Float-Einstellung namens global_font_size und eine String-Einstellung namens site_background hätten, könnten Sie Folgendes in Ihrem Theme-CSS tun:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Auflösen der Gruppenmitgliedschaft
Theme-Komponenten müssen manchmal eine Funktion anzeigen oder ausblenden, basierend darauf, ob der aktuelle Benutzer in einer konfigurierten Gruppe ist. Vermeiden Sie es, currentUser.groups dafür zu prüfen, da es nur Gruppen enthält, die für den Benutzer sichtbar sind, und verborgene Gruppen übersehen kann.
Fügen Sie für gruppenbasierte List-Einstellungen resolve_group_membership: true hinzu, um die Prüfung serverseitig aufzulösen:
copy_button_allowed_groups:
default: "1|3"
type: list
list_type: group
resolve_group_membership: true
Diese Option ist nur gültig, wenn die Einstellung type: list und list_type: group hat. Wenn sie aktiviert ist, enthält das Frontend-settings-Objekt nicht die ursprüngliche Gruppenliste. Stattdessen fügt Discourse einen Booleschen Wert mit demselben Einstellungsnamen hinzu, der mit user_in_ beginnt:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
if (!settings.user_in_copy_button_allowed_groups) {
return;
}
// Benutzer ist in mindestens einer ausgewählten Gruppe.
});
Der generierte Boolesche Wert funktioniert auch mit automatischen Gruppen wie logged_in_users und anonymous_users. Objekt-Theme-Einstellungen können dieselbe Option für type: groups-Eigenschaften verwenden. Siehe objects type for theme settings für Details.
Verwandte Themen
Dieses Dokument wird versioniert – schlagen Sie Änderungen auf github vor.