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é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 comme pour n’importe quel paramètre de thème, qui sera utilisée comme nom du 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’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 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 attendue 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 de 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: - nom 1 - nom 2 - nom 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 tags valides.
Le schéma étant défini, la valeur par défaut du paramètre peut désormais être définie en spécifiant un tableau en YAML comme suit :
links:
type: objects
default:
- name: lien 1
title: titre du lien 1
- name: lien 2
title: titre du lien 2
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, un support intégré pour les validations personnalisées est disponible, qui peut être déclaré 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 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 une valeur booléenne pour l’utilisateur actuel. Ceci est utile lorsque le code du thème n’a besoin que 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 original. Dans l’objet settings exécuté sur le frontend, Discourse supprime les identifiants de groupe 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 des groupes sélectionnés pour cette section.
}
}
Cette option n’est valide que pour les propriétés de schéma d’objet 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
n
Un objet peut également avoir une propriété contenant un tableau d’objets. Pour 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: lien 1
url: /une/url
- name: lien 2
url: /une/autre/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 des paramètres
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: lien 1
url: /une/url
- name: lien 2
url: /une/autre/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.