Nous introduisons un nouveau type: objects dans les types pris en charge pour les paramètres de thème, qui peut être utilisé pour remplacer le type json_schema existant, que nous prévoyons de déprécier prochainement.
Définir un paramètre de thème de type objects
Pour créer un paramètre de thème de type objects, définissez d’abord une clé de niveau supérieur, comme pour n’importe quel paramètre de thème, qui servira de nom au paramètre.
links: ...
Ajoutez ensuite les mots-clés type, default et schema au paramètre.
links:
type: objects
default: []
schema: ...
type: objects indique qu’il s’agit d’un paramètre de type objects, tandis que l’annotation default: [] définit la valeur par défaut du paramètre sur un tableau vide. Notez que la valeur par défaut peut également être définie sur un tableau d’objets, comme nous le montrerons une fois le schema défini.
Pour définir le schéma, définissez d’abord le name du schéma comme suit :
links:
type: objects
default: []
schema:
name: link
Ensuite, nous ajouterons le mot-clé properties au schéma, ce qui nous permettra de définir et de valider l’apparence de chaque objet.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
Dans l’exemple ci-dessus, nous indiquons que l’objet link possède une propriété name. Pour définir le type de données attendu, chaque propriété doit définir le mot-clé type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
La définition du schéma ci-dessus indique que l’objet link possède une propriété name de type string, ce qui signifie que seules des valeurs de type chaîne seront acceptées pour cette propriété. Les types suivants sont actuellement pris en charge :
-
string: La valeur de la propriété est stockée sous forme de chaîne. Définisseztextarea: truepour utiliser une zone de texte extensible :description: type: string textarea: true validations: max_length: 500 -
integer: La valeur de la propriété est stockée sous forme de nombre entier. -
float: La valeur de la propriété est stockée sous forme de nombre flottant. -
boolean: La valeur de la propriété esttrueoufalse. -
upload: La valeur de la propriété est l’URL de la pièce jointe. -
enum: La valeur de la propriété doit être l’une des valeurs définies dans le mot-cléchoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: La valeur de la propriété est un tableau d’identifiants de catégories valides. -
groups: La valeur de la propriété est un tableau d’identifiants de groupes valides. -
tags: La valeur de la propriété est un tableau de noms de tags valides. -
icon: La valeur de la propriété est le nom d’une icône unique parmi l’ensemble d’icônes de Discourse. Les icônes sélectionnées sont automatiquement ajoutées à la feuille de sprites, ce qui permet de les afficher sans devoir les enregistrer séparément.
Une fois le schéma défini, la valeur par défaut du paramètre peut désormais être définie en spécifiant un tableau dans le yaml comme suit :
links:
type: objects
default:
- name: link 1
title: link 1 title
- name: link 2
title: link 2 title
schema:
name: link
properties:
name:
type: string
title:
type: string
Propriétés requises
Toutes les propriétés définies sont facultatives par défaut. Pour marquer une propriété comme requise, il suffit d’annoter la propriété avec required: true. Une propriété peut également être marquée comme facultative en l’annotant avec required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
Les valeurs vides de type string, datetime et icon, ainsi que les listes categories, groups et tags vides, sont considérées comme manquantes : les propriétés requises les rejettent et les propriétés facultatives ignorent leurs validations. false est considéré comme défini.
Validations personnalisées
Pour certains types de propriétés, il existe une prise en charge intégrée des validations personnalisées, qui peuvent être déclarées en annotant la propriété avec le mot-clé validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
Validations pour les types string
min_length: Longueur minimale de la propriété. La valeur du mot-clé doit être un entier.max_length: Longueur maximale de la propriété. La valeur du mot-clé doit être un entier.url: Valide que la propriété est une URL valide. La valeur du mot-clé peut êtretrue/false.
Validations pour les types integer et float
min: Valeur minimale de la propriété. La valeur du mot-clé doit être un entier.max: Valeur maximale de la propriété. La valeur du mot-clé doit être un entier.
Validations pour les types tags, groups et categories
min: Nombre minimum d’enregistrements pour la propriété. La valeur du mot-clé doit être un entier.max: Nombre maximum d’enregistrements pour la propriété. La valeur du mot-clé doit être un entier.
Résolution de l’appartenance aux groupes
Les paramètres d’objet peuvent résoudre les propriétés type: groups en un booléen pour l’utilisateur actuel. Cela est utile lorsque le code du thème a simplement besoin de savoir si l’utilisateur actuel fait partie de l’un des groupes configurés, car currentUser.groups n’inclut que les groupes visibles pour l’utilisateur.
Ajoutez resolve_group_membership: true à la propriété groups :
menu_sections:
type: objects
default:
- name: section 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
L’interface d’administration et la valeur du paramètre stocké utilisent toujours le tableau groups d’origine. Dans l’objet settings de l’environnement d’exécution du frontend, Discourse supprime les identifiants de groupe de chaque objet et ajoute un booléen portant le même nom de propriété préfixé par user_in_ :
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// L'utilisateur est dans au moins un des groupes sélectionnés pour cette section.
}
}
Cette option n’est valide que sur les propriétés de schéma d’objet de type type: groups. Elle fonctionne également avec les schémas d’objets imbriqués et avec les groupes automatiques tels que logged_in_users et anonymous_users.
Structure d’objets imbriqués
Un objet peut également posséder une propriété contenant un tableau d’objets. Pour créer une structure d’objets imbriqués, une propriété peut être annotée avec type: objects et la définition de schema associée.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
Description et localisation du paramètre
Pour ajouter une description pour le paramètre dans la locale en, créez un fichier locales/en.yml avec le format suivant, étant donné le paramètre de thème de type objects ci-dessous.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
en:
theme_metadata:
settings:
sections:
description: Ceci est une description pour le paramètre de thème sections
schema:
properties:
name:
label: Nom
description: La description pour la propriété
links:
name:
label: Nom
description: La description pour la propriété
url:
label: URL
description: La description pour la propriété
Ce document est sous contrôle de version - proposez des modifications sur github.
. C’était plus une tentative de voir si c’était possible, mais pas une approche raisonnable.