Discourse ermöglicht es Themes, „Einstellungen“ zu haben, die von Theme-Entwicklern hinzugefügt werden können, damit Site-Besitzer Themes über die Benutzeroberfläche anpassen können, ohne Codezeilen ändern zu müssen und sich Sorgen machen zu müssen, ihre Änderungen bei zukünftigen Theme-Updates zu verlieren.
Themes können auch bestimmte anpassbare Site-Einstellungen ändern. Weitere Informationen dazu findest du im Thema Anpassbare Site-Einstellungen.
Einstellungen zu deinem Theme hinzufügen
Das Hinzufügen von Einstellungen zu deinem Theme unterscheidet sich etwas vom Hinzufügen von CSS- und JS-Code, da dies nicht über die Benutzeroberfläche möglich ist.
Um Einstellungen hinzuzufügen, erstelle ein Repository für dein Theme und erstelle im Stammverzeichnis deines Repositories eine neue settings.yaml- (oder settings.yml-)Datei. In dieser Datei verwendest du die YAML-Sprache, um deine Theme-Einstellungen zu definieren.
Hinweis: Es kann hilfreich sein, die Theme-CLI zu nutzen, die den Entwicklungsprozess erheblich vereinfacht.
Wenn du mit der Plugin-Entwicklung vertraut bist, ist dies für dich nichts Neues – es funktioniert weitgehend genauso wie das Hinzufügen von Site-Einstellungen zu deinem Plugin. Füge einfach gültiges YAML in deine Einstellungsdatei ein, und du bist startklar.
Eine gültige Theme-Einstellung muss einen Namen und einen Standardwert haben. Das ist das absolute Minimum und sieht so aus:
einfache_einstellung: true
Wie du wahrscheinlich erkennen kannst, erstellt dies eine Einstellung mit dem Namen einfache_einstellung und hat true als Standardwert.
Ebenso kannst du etwas wie folgendes hinzufügen:
site_name: Meine Foren
max_avatars: 7
Und du hast zwei weitere Einstellungen: site_name, eine String-Einstellung mit „Meine Foren“ als Standardwert, und max_avatars, eine Integer-Einstellung mit dem Standardwert 7.
Du kannst auf deine Einstellungen in deinem JS-Code so zugreifen: settings.dein_einstellungsschlüssel.
Bis zu diesem Punkt haben wir also die einfachste Möglichkeit zur Definition von Einstellungen behandelt. Im nächsten Abschnitt gehen wir etwas tiefer auf die verschiedenen Einstellungstypen und deren Verwendung ein.
Unterstützte Typen
Es gibt 8 Einstellungstypen:
integerfloatstringbool(für Boolean)listenumobjects(Ersatz fürjson_schema)upload(für Bilder)
Und du kannst den Typ angeben, indem du deiner Einstellung ein type-Attribut hinzufügst, wie hier:
float_einstellung:
type: float
default: 3.14
Ich sollte sagen, dass du nicht immer ein type-Attribut explizit setzen musst, da Discourse intelligent genug ist, den Einstellungstyp aus dem Standardwert der Einstellung zu ermitteln. Du kannst das obige Beispiel also auf folgendes reduzieren:
float_einstellung:
default: 3.14
Trotzdem musst du ein Typ-Attribut setzen, wenn du mit list- und enum-Einstellungen arbeitest, da Discourse diese sonst nicht korrekt erkennt.
Listeneinstellung:
whitelisted_fruits:
default: apples|oranges
type: list
Enum-Einstellung:
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Falls dir der Unterschied zwischen Listen- und Enum-Einstellungen nicht klar ist: Enum-Einstellungen ermöglichen es deinen Theme-Nutzern, nur einen Wert aus einer von dir definierten Wertemenge auszuwählen (siehe choices-Attribut).
Listen-Einstellungen ermöglichen es deinen Nutzern hingegen, ihre eigene Liste (d. h. ein Array) von Werten zu erstellen. Sie können der Standardwerteliste der Einstellung Werte hinzufügen oder daraus entfernen.
Du kannst die Standardwerteliste für die Einstellung festlegen, indem du die Werte mit einem senkrechten Strich | verknüpfst. Siehe die Listeneinstellung im obigen Beispiel.
Ein reales Anwendungsbeispiel für Listeneinstellungen findest du hier: Auto-Linkify Words.
objects-Typ
Der objects-Einstellungstyp ist ein spezieller Typ, der es dir ermöglicht, erweiterte Einstellungen mit benutzerdefinierter Struktur und Validierungen zu erstellen. Für diesen Typ haben wir eine separate Dokumentation.
Einstellungsbeschreibung und Lokalisierungen
Du kannst deiner Theme-Einstellung Beschreibungstext hinzufügen, der als Beschriftung direkt unter der Einstellung angezeigt wird. Füge dazu einfach ein description-Attribut zu deiner Einstellung hinzu, wie hier:
whitelisted_fruits:
default: apples|oranges
type: list
description: "Dieser Text wird unter dieser Einstellung angezeigt und erklärt, was die Einstellung bewirkt!"
Und du erhältst folgendes Ergebnis:
Unterstützung mehrerer Sprachen
Wenn du mehr als eine Sprache beherrschst und Unterstützung für diese Sprachen in dein Theme aufnehmen möchtest, kannst du das problemlos tun, vorausgesetzt, Discourse unterstützt diese Sprachen.
Stelle zunächst sicher, dass die Sprache, die du unterstützen möchtest, 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) |
(Wenn du deine Sprache nicht in der Liste findest, schaue dir gerne How to add a new language an.)
Dann musst du deinen Sprachcode aus der obigen Liste finden und den Sprachcode als Schlüssel unter dem description-Attribut und die Übersetzung als Wert für den Schlüssel verwenden, wie hier:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: Englischer Text
ar: نص باللغة العربية
fr: Französischer Text
Und jetzt hast du Unterstützung für 3 Sprachen: Englisch, Arabisch und Französisch.
Zusätzliche Einstellungsattribute und -optionen
Min- und Max-Attribute
Manchmal musst du Grenzen angeben, die ein Einstellungswert nicht überschreiten darf, um zu verhindern, dass deine Nutzer das Theme oder möglicherweise die gesamte Site versehentlich beschädigen.
Um Grenzen anzugeben, füge einfach ein min- oder max- oder beide Attribute zu deiner Einstellung hinzu, wie hier:
integer_einstellung:
default: 10
min: 5
max: 100
Du kannst Grenzen für integer-, float- und string-Einstellungstypen angeben. Für integer- und float-Einstellungen wird der Wert der Einstellung selbst gegen die Grenzen geprüft. Und für string-Einstellungen wird die Länge des Werts gegen die angegebenen Grenzen geprüft.
Wenn dein Nutzer versucht, einen Wert einzugeben, der nicht im zulässigen Bereich liegt, sieht er einen Fehler, der ihm die Mindest- und Höchstwerte mitteilt.
Zugriff auf Einstellungen in deinem JS/CSS/Handlebars
Theme-Einstellungen sind global als settings-Variable in Theme-JavaScript-Dateien verfügbar. Zum Beispiel:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("Einstellungen sind", settings);
});
Dieses settings-Objekt ist auch innerhalb von .gjs <template>-Tags normal verwendbar.
Festlegen von CSS-Variablen
In CSS wird für jede Einstellung deines Themes eine Variable erstellt, und jede Variable hat denselben Namen wie die Einstellung, die sie darstellt.
Wenn du also eine Float-Einstellung namens global_font_size und eine String-Einstellung namens site_background hättest, könntest du in deinem Theme-CSS folgendes 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. Vermeide es, currentUser.groups dafür zu prüfen, da dies nur Gruppen enthält, die für den Benutzer sichtbar sind, und verborgene Gruppen übersehen werden können.
Für gruppenbasierte Listeneinstellungen, füge 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 Boolean 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 Boolean funktioniert auch mit automatischen Gruppen wie logged_in_users und anonymous_users.
Verwandte Themen
Dieses Dokument ist versioniert – schlage Änderungen auf GitHub vor.