Discourse ermöglicht es Themes, “Einstellungen” zu haben, die von Theme-Entwicklern hinzugefügt werden können, damit Site-Betreiber Themes über die Benutzeroberfläche anpassen können, ohne Codezeilen ändern zu müssen und sich keine Sorgen machen zu müssen, dass ihre Änderungen bei zukünftigen Theme-Updates verloren gehen.
Themes können auch bestimmte anpassbare Site-Einstellungen ändern. Für weitere Informationen dazu siehe das 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 größtenteils 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 ihr Standardwert ist true.
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 wie folgt 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 werden wir etwas tiefer in die verschiedenen Einstellungstypen und deren Nutzung eintauchen.
Unterstützte Typen
Es gibt 9 Einstellungstypen:
integerfloatstringbool(für boolesche Werte)listenumobjects(Ersatz fürjson_schema)upload(für Bilder)icon(für ein einzelnes Symbol aus dem Discourse-Symbolset)
Und du kannst den Typ angeben, indem du deiner Einstellung ein type-Attribut wie folgt hinzufügst:
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, um 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 type-Attribut setzen, wenn du mit list, enum und icon-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 Menge von Werten auszuwählen (siehe das choices-Attribut).
Andererseits ermöglichen Listeneinstellungen deinen Nutzern, 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 vertikalen Strich | verknüpfst. Siehe die Listeneinstellung im obigen Beispiel.
Ein realweltlicher Anwendungsfall für Listeneinstellungen findest du hier: Auto-Linkify Words.
Symbol-Einstellung:
banner_icon:
default: bullhorn
type: icon
Symbol-Einstellungen bieten Site-Betreibern einen durchsuchbaren Symbol-Auswähler, und der Wert ist der Symbolname. Discourse fügt das ausgewählte Symbol dem Sprite-Sheet hinzu, sodass du es in deinem Theme rendern kannst, ohne es separat registrieren zu müssen.
objects-Typ
Der Einstellungstyp objects ist ein spezieller Typ, der es dir ermöglicht, erweiterte Einstellungen mit benutzerdefinierter Struktur und Validierungen zu erstellen. Wir haben eine separate Dokumentation für diesen Typ.
Einstellungsbeschreibung und Lokalisierungen
Du kannst deiner Theme-Einstellung Beschreibungstext hinzufügen, der als Label direkt unter der Einstellung angezeigt wird. Dazu fügst du deiner Einstellung einfach ein description-Attribut wie folgt hinzu:
whitelisted_fruits:
default: apples|oranges
type: list
description: "Dieser Text wird unter dieser Einstellung angezeigt und erklärt, was die Einstellung tut!"
Und du erhältst dies:
Unterstützung mehrerer Sprachen
Wenn du mehr als eine Sprache beherrschst und Unterstützung für diese Sprachen in deinem Theme hinzufügen möchtest, kannst du das definitiv 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, solltest du dir How to add a new language ansehen.)
Dann musst du deinen 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 angeben:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: English text
ar: نص باللغة العربية
fr: Texte français
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 deiner Einstellung einfach ein min- oder max-Attribut oder beide wie folgt hinzu:
integer_einstellung:
default: 10
min: 5
max: 100
Du kannst Grenzen für Einstellungen der Typen integer, float und string 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 in Theme-JavaScript-Dateien global als settings-Variable verfügbar. Zum Beispiel:
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("settings sind", settings);
});
Dieses settings-Objekt ist auch innerhalb von .gjs <template>-Tags normal verwendbar.
CSS-Variablen festlegen
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 etwas wie folgendes tun:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Gruppenmitgliedschaft auflösen
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 versteckte 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 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 bei type: groups-Eigenschaften verwenden. Siehe Objekttyp für Theme-Einstellungen für Details.
Verwandte Themen
Dieses Dokument ist versionskontrolliert – vorschlage Änderungen auf github.