Stiamo introducendo un nuovo type: objects per i tipi supportati nelle impostazioni dei temi, che può essere utilizzato per sostituire il tipo json_schema esistente, che intendiamo deprecare a breve.
Definizione di un’impostazione del tema di tipo objects
Per creare un’impostazione del tema di tipo objects, prima di tutto definisci una chiave di livello superiore, proprio come per qualsiasi altra impostazione del tema, che verrà utilizzata come nome dell’impostazione.
links: ...
Successivamente, aggiungi le parole chiave type, default e schema all’impostazione.
links:
type: objects
default: []
schema: ...
type: objects indica che questa sarà un’impostazione di tipo objects, mentre l’annotazione default: [] imposta il valore predefinito dell’impostazione su un array vuoto. Nota che il valore predefinito può anche essere impostato su un array di oggetti, cosa che dimostreremo una volta definita la schema.
Per definire lo schema, prima di tutto definisci il name dello schema come segue:
links:
type: objects
default: []
schema:
name: link
Successivamente, aggiungeremo la parola chiave properties allo schema, che ci consentirà di definire e validare come dovrebbe essere strutturato ciascun oggetto.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
Nell’esempio sopra, stiamo affermando che l’oggetto link ha una proprietà name. Per definire il tipo di dati atteso, ogni proprietà deve definire la parola chiave type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
La definizione dello schema sopra indica che l’oggetto link ha una proprietà name di tipo string, il che significa che verranno accettati solo valori stringa per la proprietà. Attualmente sono supportati i seguenti tipi:
string: Il valore della proprietà viene memorizzato come stringa.integer: Il valore della proprietà viene memorizzato come intero.float: Il valore della proprietà viene memorizzato come float.boolean: Il valore della proprietà ètrueofalse.upload: Il valore della proprietà è l’URL dell’allegatoenum: Il valore della proprietà deve essere uno dei valori definiti nella parola chiavechoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3categories: Il valore della proprietà è un array di ID categoria validi.groups: Il valore della proprietà è un array di ID gruppo validi.tags: Il valore della proprietà è un array di nomi tag validi.icon: Il valore della proprietà è il nome di un singolo icona dal set di icone di Discourse. Le icone selezionate vengono aggiunte automaticamente alla sprite sheet, quindi possono essere renderizzate senza essere registrate separatamente.
Con lo schema definito, il valore predefinito dell’impostazione può ora essere impostato definendo un array in yaml come segue:
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
Proprietà obbligatorie
Tutte le proprietà definite sono facoltative di default. Per contrassegnare una proprietà come obbligatoria, basta annotare la proprietà con required: true. Una proprietà può anche essere contrassegnata come facoltativa annotandola con required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
I valori vuoti per string, datetime e icon e le liste vuote per categories, groups e tags contano come mancanti: le proprietà obbligatorie li rifiutano e le proprietà facoltative saltano le loro validazioni. false conta come impostato.
Validazioni personalizzate
Per determinati tipi di proprietà, esiste un supporto integrato per le validazioni personalizzate, che possono essere dichiarate annotando la proprietà con la parola chiave validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
Validazioni per i tipi string
min_length: Lunghezza minima della proprietà. Il valore della parola chiave deve essere un intero.max_length: Lunghezza massima della proprietà. Il valore della parola chiave deve essere un intero.url: Convalida che la proprietà sia un URL valido. Il valore della parola chiave può esseretrue/false.
Validazioni per i tipi integer e float
min: Valore minimo della proprietà. Il valore della parola chiave deve essere un intero.max: Valore massimo della proprietà. Il valore della parola chiave deve essere un intero.
Validazioni per i tipi tags, groups e categories
min: Numero minimo di record per la proprietà. Il valore della parola chiave deve essere un intero.max: Numero massimo di record per la proprietà. Il valore della parola chiave deve essere un intero.
Risoluzione dell’appartenenza ai gruppi
Le impostazioni di tipo objects possono risolvere le proprietà type: groups in un booleano per l’utente corrente. Questo è utile quando il codice del tema ha solo bisogno di sapere se l’utente corrente appartiene a uno dei gruppi configurati, poiché currentUser.groups include solo i gruppi visibili all’utente.
Aggiungi resolve_group_membership: true alla proprietà 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’interfaccia di amministrazione e il valore dell’impostazione memorizzata utilizzano ancora l’array originale groups. Nell’oggetto settings del runtime frontend, Discourse rimuove gli ID dei gruppi da ciascun oggetto e aggiunge un booleano con lo stesso nome di proprietà prefissato da user_in_:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// L'utente appartiene ad almeno uno dei gruppi selezionati per questa sezione.
}
}
Questa opzione è valida solo per le proprietà dello schema di oggetto con type: groups. Funziona anche con gli schemi di oggetti annidati e con i gruppi automatici come logged_in_users e anonymous_users.
Struttura di oggetti annidati
Un oggetto può anche avere una proprietà che contiene un array di oggetti. Per creare una struttura di oggetti annidati, una proprietà può anche essere annotata con type: objects e la relativa definizione schema.
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
Descrizione dell’impostazione e localizzazione
Per aggiungere una descrizione per l’impostazione nella locale en, crea un file locales/en.yml con il seguente formato, dato il seguente tipo di impostazione del tema objects.
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
Questo documento è sottoposto a controllo delle versioni - suggerisci modifiche su github.
. È stato più un tentativo di vedere se fosse possibile, ma non un approccio ragionevole.