Discourse permet aux thèmes de disposer de « paramètres » que les développeurs de thèmes peuvent ajouter pour 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 paramètres de site personnalisables ; pour plus d’informations à ce sujet, consultez le sujet Paramètres de site personnalisables.
Ajout de paramètres à votre thème
L’ajout de paramètres à votre thème diffère légèrement de l’ajout de code CSS et JS, car il n’est pas possible de le faire via l’interface utilisateur.
Pour ajouter des paramètres, vous devez créer un dépôt pour votre thème, puis créer un nouveau fichier settings.yaml (ou settings.yml) dans le dossier racine de votre dépôt. Dans ce fichier, vous utiliserez le langage YAML pour définir les paramètres de votre thème.
Remarque : Il peut être utile d’utiliser la CLI de thème, qui simplifie considérablement le processus de développement.
Si vous êtes familier avec le développement de plugins, cela ne devrait rien vous apprendre de nouveau — cela fonctionne essentiellement de la même manière que l’ajout de paramètres de site à votre plugin. Il vous suffit d’insérer du YAML valide dans votre fichier de paramètres et vous êtes prêt à démarrer.
Un paramètre 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 paramètre nommé simple_setting avec 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 disposerez de deux paramètres supplémentaires : site_name, qui sera un paramètre de type chaîne avec « My Forums » comme valeur par défaut, et max_avatars, qui sera un paramètre de type entier avec une valeur par défaut de 7.
Vous pouvez accéder à vos paramètres dans votre code JS comme suit : settings.your_setting_key.
Jusqu’à présent, nous avons couvert la manière la plus simple de définir des paramètres. Dans la section suivante, nous explorerons plus en détail les différents types de paramètres et comment les utiliser.
Types pris en charge
Il existe 8 types de paramètres :
integerfloatstringbool(pour les booléens)listenumobjects(remplacement dejson_schema)upload(pour les images)
Et vous pouvez spécifier le type en ajoutant un attribut type à votre paramètre comme suit :
float_setting:
type: float
default: 3.14
Je devrais préciser que vous n’avez pas toujours besoin de définir explicitement un attribut type, car Discourse est suffisamment intelligent pour déduire le type de paramètre à partir de la valeur par défaut du paramètre. 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 les paramètres list et enum, sinon Discourse ne les reconnaîtra pas correctement.
Paramètre de liste :
whitelisted_fruits:
default: apples|oranges
type: list
Paramètre d’énumération :
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Au cas où la différence entre les paramètres de liste et d’énumération ne serait pas claire pour vous : les paramètres d’énumération permettent à vos utilisateurs de thème de sélectionner une seule valeur parmi un ensemble de valeurs définies par vous (voir l’attribut choices).
En revanche, les paramètres de liste permettent à vos utilisateurs de créer leur propre liste (c’est-à-dire un tableau) de valeurs. Ils peuvent ajouter ou supprimer des valeurs de la liste par défaut du paramètre.
Vous pouvez définir la liste par défaut de valeurs pour le paramètre en joignant les valeurs avec un caractère barre verticale |. Voir le paramètre de liste dans l’exemple ci-dessus.
Vous pouvez voir un cas d’utilisation réel pour les paramètres de liste ici : Auto-Linkify Words.
Type objects
Le type de paramètre objects est un type spécial qui vous permet de réaliser des paramètres avancés avec une structure et des validations personnalisées. Nous disposons d’une documentation séparée pour ce type.
Description des paramètres et localisations
Vous pouvez ajouter un texte de description à votre paramètre de thème et il sera affiché sous forme d’étiquette directement sous le paramètre. Pour ce faire, il vous suffit d’ajouter un attribut description à votre paramètre comme suit :
whitelisted_fruits:
default: apples|oranges
type: list
description: "Ce texte sera affiché sous ce paramètre et il explique ce que fait le paramètre !"
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 | Nom | |||
|---|---|---|---|---|
| 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 trouvez pas votre langue dans la liste, vous pourriez vouloir consulter 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: Texte en anglais
ar: نص باللغة العربية
fr: Texte français
Et vous disposez désormais de la prise en charge de 3 langues : l’anglais, l’arabe et le français.
Attributs et options supplémentaires des paramètres
Attributs min et max
Parfois, vous devrez peut-être spécifier des limites que la valeur d’un paramètre ne peut pas dépasser pour empêcher vos utilisateurs de casser accidentellement le thème ou même tout le site.
Pour spécifier des limites, il vous suffit d’ajouter un attribut min ou max ou les deux à votre paramètre comme suit :
integer_setting:
default: 10
min: 5
max: 100
Vous pouvez spécifier des limites pour les paramètres de type integer, float et string. Pour les paramètres integer et float, la valeur du paramètre lui-même est vérifiée par rapport aux limites. Et pour les paramètres string, la longueur de la valeur est vérifiée par rapport aux limites spécifiées.
Si votre utilisateur tente 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 paramètres dans votre JS/CSS/Handlebars
Les paramètres de thème sont disponibles globalement sous forme de variable settings dans les fichiers JavaScript du thème. Par exemple :
// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer((api) => {
console.log("les paramètres sont", settings);
});
Cet objet settings est également utilisable normalement dans les balises <template> .gjs.
Définition des variables CSS
En CSS, une variable sera créée pour chaque paramètre de votre thème et chaque variable aura le même nom que le paramètre qu’elle représente.
Ainsi, si vous aviez un paramètre float nommé global_font_size et un paramètre string nommé site_background, vous pourriez faire quelque chose comme ceci dans le CSS de votre 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 l’appartenance de l’utilisateur actuel à un groupe configuré. Évitez de vérifier currentUser.groups pour cela, car cela inclut uniquement les groupes visibles par l’utilisateur et peut manquer des groupes masqués.
Pour les paramètres 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 paramètre a type: list et list_type: group. Lorsqu’elle est activée, l’objet settings côté frontend n’inclut pas la liste de groupes originale. À la place, Discourse ajoute un booléen avec le même nom de paramètre 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;
}
// L’utilisateur est dans au moins un groupe sélectionné.
});
Le booléen généré fonctionne également avec les groupes automatiques tels que logged_in_users et anonymous_users.
Sujets connexes
Ce document est sous contrôle de version - suggérez des modifications sur github.