Nous introduisons un nouveau type: objects pour les types pris en charge par les paramètres de thème, qui peut être utilisé pour remplacer le type json_schema existant, dont nous prévoyons la dépréciation prochainement.
Définition d’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 premier niveau, tout comme pour tout autre paramètre de thème, qui sera utilisée comme nom du paramètre.
links: ...
Ensuite, ajoutez les mots-clés type, default et schema au paramètre.
links:
type: objects
default: []
schema: ...
type: objects indique qu’il s’agira 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, ce que nous démontrerons une fois le schema défini.
Pour définir le schéma, commencez par définir le name du schéma de la manière suivante :
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 les valeurs de type chaîne de caractères seront acceptées pour cette propriété. Actuellement, les types suivants sont pris en charge :
string: La valeur de la propriété est stockée en tant que chaîne de caractères.integer: La valeur de la propriété est stockée en tant qu’entier.float: La valeur de la propriété est stockée en tant que nombre à virgule flottante.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 3categories: 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 balises valides.icon: La valeur de la propriété est le nom d’une seule icône du jeu d’icônes Discourse. Les icônes sélectionnées sont automatiquement ajoutées à la feuille de sprites, de sorte qu’elles peuvent être rendues sans enregistrement séparé.
Avec le schéma défini, la valeur par défaut du paramètre peut maintenant être définie en créant un tableau en yaml de la manière suivante :
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
Validations personnalisées
Pour certains types de propriétés, il existe une prise en charge intégrée pour 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: 1
max: 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 minimal d’enregistrements pour la propriété. La valeur du mot-clé doit être un entier.max: Nombre maximal 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’objets 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 n’a besoin de savoir que si l’utilisateur actuel fait partie de l’un des groupes configurés, car currentUser.groups n’inclut que les groupes visibles par 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 original. Dans l’objet settings du temps d’exécution côté client, Discourse supprime les identifiants de groupes de chaque objet et ajoute un booléen avec 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 fait partie d'au moins un groupe sélectionné pour cette section.
}
}
Cette option n’est valide que pour les propriétés du schéma d’objets avec 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 avoir une propriété contenant un tableau d’objets. Afin de créer une structure d’objets imbriqués, une propriété peut également être annotée avec type: objects et la définition 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 du paramètre et localisation
Pour ajouter une description du paramètre dans la locale en, créez un fichier locales/en.yml avec le format suivant, compte tenu du paramètre de thème de type objects suivant.
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: This is a description for the sections theme setting
schema:
properties:
name:
label: Name
description: The description for the property
links:
name:
label: Name
description: The description for the property
url:
label: URL
description: The description for the property
Ce document est sous contrôle de version - suggérez des modifications sur github.
. C’était plus une tentative de voir si c’était possible, mais pas une approche raisonnable.