Discourse permet aux thèmes de posséder des « réglages » que les développeurs de thèmes peuvent ajouter afin de permettre aux propriétaires de sites de personnaliser les thèmes via l’interface utilisateur, sans avoir à modifier une seule ligne de code et sans craindre de perdre leurs modifications lors des mises à jour futures du thème.
Les thèmes peuvent également modifier certains réglages de site personnalisables. Pour plus d’informations à ce sujet, consultez le sujet Réglages de site personnalisables.
Ajout de réglages à votre thème
L’ajout de réglages à votre thème diffère un peu de l’ajout de code CSS et JS, car il n’y a pas de moyen de le faire via l’interface utilisateur.
La façon d’ajouter des réglages consiste à créer un dépôt pour votre thème et, dans le dossier racine de votre dépôt, à créer un nouveau fichier settings.yaml (ou settings.yml). Dans ce fichier, vous utiliserez le langage YAML pour définir vos réglages de thème.
Note : Vous pourriez trouver utile de vous servir de l’interface en ligne de commande pour les thèmes (Theme CLI), qui simplifie considérablement le processus de développement.
Si vous êtes familier avec le développement de plugins, cela ne devrait pas être nouveau pour vous - cela fonctionne principalement de la même manière que l’ajout de réglages de site à votre plugin. Il suffit de saisir du YAML valide dans votre fichier de réglages et vous serez prêt à partir.
Un réglage de thème valide doit avoir un nom et une valeur par défaut, c’est le minimum requis et cela ressemble à ceci :
simple_setting: true
Comme vous pouvez probablement le deviner, cela créera un réglage nommé simple_setting et il aura true comme valeur par défaut.
De même, vous pouvez ajouter quelque chose comme ceci :
site_name: My Forums
max_avatars: 7
Et vous aurez deux réglages de plus, site_name qui sera un réglage de type chaîne avec “My Forums” comme valeur par défaut, et max_avatars comme réglage de type entier avec une valeur par défaut de 7.
Vous pouvez accéder à vos réglages dans votre code JS comme ceci : settings.your_setting_key.
Jusqu’à présent, nous avons couvert la manière la plus simple de définir des réglages. Dans la section suivante, nous approfondirons un peu les différents types de réglages et comment vous pouvez les utiliser.
Types pris en charge
Il existe 9 types de réglages :
integerfloatstringbool(pour booléen)listenumobjects(remplacement dejson_schema)upload(pour les images)icon(pour une icône unique du jeu d’icônes Discourse)
Et vous pouvez spécifier le type en ajoutant un attribut type à votre réglage comme ceci :
float_setting:
type: float
default: 3.14
Je devrais dire que vous n’avez pas toujours besoin de définir explicitement un attribut type, car Discourse est assez intelligent pour déterminer le type de réglage à partir de la valeur par défaut du réglage. Vous pouvez donc réduire l’exemple ci-dessus à ceci :
float_setting:
default: 3.14
Cela dit, vous devez définir un attribut de type lorsque vous travaillez avec des réglages list, enum et icon, sinon Discourse ne les reconnaîtra pas correctement.
Réglage de liste (List Setting) :
whitelisted_fruits:
default: apples|oranges
type: list
Réglage d’énumération (Enum Setting) :
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Au cas où la différence entre les réglages de liste et d’énumération ne serait pas claire pour vous : les réglages d’énumération permettent à vos utilisateurs de thème de sélectionner uniquement une valeur parmi un ensemble de valeurs défini par vous (voir l’attribut choices).
En revanche, les réglages de liste permettent à vos utilisateurs de créer leur propre liste (c’est-à-dire un tableau) de valeurs. Ils peuvent ajouter ou supprimer des éléments de la liste de valeurs par défaut du réglage.
Vous pouvez définir la liste de valeurs par défaut du réglage en joignant les valeurs avec le caractère barre verticale |. Voir le réglage de liste dans l’exemple ci-dessus.
Vous pouvez voir un cas d’utilisation réel pour les réglages de liste ici : Auto-Linkify Words.
Réglage d’icône (Icon Setting) :
banner_icon:
default: bullhorn
type: icon
Les réglages d’icône offrent aux propriétaires de sites un sélecteur d’icônes avec recherche, et la valeur est le nom de l’icône. Discourse ajoute l’icône sélectionnée à la feuille de sprites, vous pouvez donc l’afficher dans votre thème sans avoir à l’enregistrer séparément.
Type objects
Le type de réglage objects est un type spécial qui vous permet d’accomplir des réglages avancés avec une structure et des validations personnalisées. Nous avons une documentation séparée pour ce type.
Description et localisations des réglages
Vous pouvez ajouter un texte de description à votre réglage de thème et il s’affichera comme une étiquette directement sous le réglage. Pour cela, il suffit d’ajouter un attribut description à votre réglage comme suit :
whitelisted_fruits:
default: apples|oranges
type: list
description: "Ce texte sera affiché sous ce réglage et il explique ce que fait le réglage !"
Et vous obtiendrez ceci :
Prise en charge de plusieurs langues
Si vous connaissez plus d’une langue et que vous souhaitez ajouter la prise en charge de ces langues à votre thème, vous pouvez tout à fait le faire, à condition que Discourse prenne en charge ces langues.
Tout d’abord, assurez-vous que la langue que vous souhaitez prendre en charge figure dans cette liste :
Liste des langues
| 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) |
(Si vous ne voyez pas votre langue dans la liste, vous voudrez peut-être jeter un œil à How to add a new language)
Ensuite, vous devrez trouver le code de votre langue dans la liste ci-dessus et utiliser le code de langue comme clé sous l’attribut description et la traduction comme valeur pour la clé comme suit :
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: English text
ar: نص باللغة العربية
fr: Texte français
Et maintenant vous avez la prise en charge de 3 langues : l’anglais, l’arabe et le français.
Attributs et options de réglage supplémentaires
Attributs min et max
Parfois, vous pouvez avoir besoin de spécifier des limites qu’une valeur de réglage ne peut pas dépasser pour empêcher vos utilisateurs de casser accidentellement le thème ou peut-être tout le site.
Pour spécifier des limites, il suffit d’ajouter un attribut min ou max ou les deux à votre réglage comme suit :
integer_setting:
default: 10
min: 5
max: 100
Vous pouvez spécifier des limites pour les réglages de type integer, float et string. Pour les réglages integer et float, la valeur du réglage lui-même est vérifiée par rapport aux limites. Et pour les réglages string, la longueur de la valeur est vérifiée par rapport aux limites spécifiées.
Si votre utilisateur essaie de saisir une valeur qui n’est pas dans la plage autorisée, il verra une erreur lui indiquant quelles sont les valeurs min et max.
Accès aux réglages dans votre JS/CSS/Handlebars
Les réglages de thème sont rendus disponibles globalement en tant que variable settings dans les fichiers JavaScript de thème. Par exemple :
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("settings are", settings);
});
Cet objet settings est également utilisable normalement dans les balises <template> .gjs.
Définition de variables CSS
En CSS, une variable sera créée pour chaque réglage de votre thème et chaque variable aura le même nom que le réglage qu’elle représente.
Donc, si vous aviez un réglage flottant nommé global_font_size et un réglage de chaîne nommé site_background, vous pourriez faire quelque chose comme ceci dans votre CSS de thème :
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Résolution de l’appartenance aux groupes
Les composants de thème ont parfois besoin d’afficher ou de masquer une fonctionnalité en fonction de savoir si l’utilisateur actuel appartient à un groupe configuré. Évitez de vérifier currentUser.groups pour cela, car cela n’inclut que les groupes visibles pour l’utilisateur, et cela peut manquer des groupes cachés.
Pour les réglages de liste basés sur des groupes, ajoutez resolve_group_membership: true pour résoudre la vérification côté serveur :
copy_button_allowed_groups:
default: "1|3"
type: list
list_type: group
resolve_group_membership: true
Cette option n’est valide que lorsque le réglage a type: list et list_type: group. Lorsqu’elle est activée, l’objet settings du frontend n’inclut pas la liste de groupes originale. Au lieu de cela, Discourse ajoute un booléen avec le même nom de réglage préfixé par user_in_ :
// {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;
}
// User is in at least one selected group.
});
Le booléen généré fonctionne également avec les groupes automatiques tels que logged_in_users et anonymous_users. Les réglages de thème de type objet peuvent utiliser la même option sur les propriétés type: groups. Voir Type objects pour les réglages de thème pour plus de détails.
Sujets liés
Ce document est sous contrôle de version - suggérez des modifications sur github.