Tipo di oggetto per l'impostazione del tema

Documentazione Guide per sviluppatori
,
1

Stiamo introducendo un nuovo type: objects nei tipi supportati per le impostazioni del tema, che può essere utilizzato per sostituire il tipo esistente json_schema, 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 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ò essere impostato anche 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 in questo modo:

links:
  type: objects
  default: []
  schema:
    name: link

Successivamente, aggiungeremo la parola chiave properties allo schema, che ci permetterà di definire e validare come dovrebbe essere strutturato ogni 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 previsto, ogni proprietà deve definire la parola chiave type.

links:
  type: objects
  default: []
  schema:
    name: link
    properties:
      name:
        type: string

La definizione dello schema sopra afferma che l’oggetto link ha una proprietà name di tipo string, il che significa che per la proprietà verranno accettati solo valori di tipo stringa. Attualmente sono supportati i seguenti tipi:

  • string: Il valore della proprietà è memorizzato come stringa.
  • integer: Il valore della proprietà è memorizzato come intero.
  • float: Il valore della proprietà è memorizzato come numero decimale (float).
  • boolean: Il valore della proprietà è true o false.
  • upload: Il valore della proprietà è l’URL dell’allegato.
  • enum: Il valore della proprietà deve essere uno dei valori definiti nella parola chiave choices.
    links:
  type: objects
  default: []
  schema:
    name: link
    properties:
      name:
        type: enum
        choices:
          - nome 1
          - nome 2
          - nome 3
  • categories: Il valore della proprietà è un array di ID di categoria validi.
  • groups: Il valore della proprietà è un array di ID di gruppo validi.
  • tags: Il valore della proprietà è un array di nomi di tag validi.

Con lo schema definito, il valore predefinito dell’impostazione può ora essere impostato definendo un array in yaml in questo modo:

links:
  type: objects
  default:
    - name: link 1
      title: titolo link 1
    - name: link 2
      title: titolo link 2
  schema:
    name: link
    properties:
      name:
        type: string
      title:
        type: string

Proprietà obbligatorie

Tutte le proprietà definite sono opzionali per impostazione predefinita. Per segnare una proprietà come obbligatoria, basta annotare la proprietà con required: true. Una proprietà può anche essere segnata come opzionale annotandola con required: false.

links:
  type: objects
  default: []
  schema:
    name: link
    properties:
      name:
        type: string
        required: true
      title:
        type: string
        required: false

Convalide personalizzate

Per determinati tipi di proprietà, esiste un supporto integrato per convalidhe 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: 1
          max: 2048
          url: true

Convalidhe 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ò essere true/false.

Convalidhe 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.

Convalidhe 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 degli oggetti possono risolvere le proprietà type: groups in un booleano per l’utente corrente. Questo è utile quando il codice del tema ha bisogno solo di sapere se l’utente corrente è in uno dei gruppi configurati, perché currentUser.groups include solo i gruppi visibili all’utente.

Aggiungi resolve_group_membership: true alla proprietà groups:

menu_sections:
  type: objects
  default:
    - name: sezione 1
      groups:
        - 1
        - 3
  schema:
    name: menu section
    properties:
      name:
        type: string
      groups:
        type: groups
        resolve_group_membership: true

L’interfaccia utente di amministrazione e il valore dell’impostazione memorizzata utilizzano ancora l’array originale groups. Nell’oggetto settings di runtime del frontend, Discourse rimuove gli ID dei gruppi da ogni oggetto e aggiunge un booleano con lo stesso nome della proprietà preceduto da user_in_:

for (const section of settings.menu_sections) {
  if (section.user_in_groups) {
    // L'utente è in almeno uno dei gruppi selezionati per questa sezione.
  }
}

Questa opzione è valida solo per le proprietà dello schema degli oggetti con type: groups. Funziona anche con schemi di oggetti annidati e con 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ò essere annotata anche con type: objects e la relativa definizione schema.

sections:
  type: objects
  default:
    - name: sezione 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 lingua 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: sezione 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: Questa è una descrizione per l'impostazione del tema sezioni
        schema:
          properties:
            name:
              label: Nome
              description: La descrizione per la proprietà
            links:
              name:
                label: Nome
                description: La descrizione per la proprietà
              url:
                label: URL
                description: La descrizione per la proprietà

Questo documento è sotto controllo di versione - suggerisci modifiche su github.

16 Mi Piace
Add settings to your Discourse theme
Brand Header links and icons settings now Object setting type
Best Practice for Automating Titles by Group + Trust Level Combinations
Custom Header Links
Icon type SiteSetting
Custom Components -- add button or text at any plugin outlet
Watermark Image
Easy Responsive Footer
How do I replicate the meta banner links?
⬇️ Dropdown Header
How do I make json_schema translatable?
Labels and descriptions missing from nested object settings
Can `%{base_path}` be used in object setting descriptions?
Hidden User Fields
Nav Button Highlighter component - now working
Granular group-based permissions for anonymous and logged in users
2

Rimango da convincere che la deprecazione dello stile dello schema JSON sia una buona idea.

Sebbene questi possano diventare piuttosto complessi e non siano i formati più “amichevoli per gli sviluppatori” (quindi questo è un ottimo cambiamento a riguardo), ci sono strumenti online per convalidare gli schemi JSON che è un modo davvero utile per convalidare sia lo schema che contro qualsiasi dato predefinito.

ad es. https://www.jsonschemavalidator.net/

Come funzionerà in questo nuovo mondo?

2 Mi Piace
4

Quando si carica un tema, convalidiamo i dati predefiniti rispetto allo schema definito. Detto questo, al momento non stiamo convalidando la validità della definizione dello schema, ma non sarebbe difficile farlo. Anche per l’impostazione dello schema json attuale, non credo che stiamo convalidando i dati predefiniti rispetto allo schema definito.

La nostra attuale implementazione delle impostazioni del tipo di schema json è in qualche modo difettosa per molti versi, il più ovvio dei quali è l’editor nell’interfaccia di amministrazione. Ne abbiamo discusso internamente e abbiamo deciso che è molto più facile per noi mantenere un formato di schema limitato definito da noi invece di consentire tutte le possibilità che derivano dallo schema json.

2 Mi Piace
6

Alcune fantastiche funzionalità qui:

  • puoi sbarazzarti di JSON.parse e accedere direttamente all’impostazione per ottenere l’oggetto, il che è davvero bello.

  • il validatore di URL!

:chefs_kiss: :chefs_kiss:

5 Mi Piace
7

C’è un modo per rispettare più righe nell’editor?

Questo predefinito funziona:

- name: markdown
  value: > 
    ## Heading
      * first bullet
      * second bullet

Ma una volta modificato, i ritorni a capo vengono persi

Inoltre, sarebbe bello avere un tipo “text” che possa memorizzare dati più lunghi e magari esporre un editor “text-area” più grande.

5 Mi Piace
8

Ecco alcuni feedback:

2 Mi Piace
9

Ho notato questo ed è stato corretto in

1 Mi Piace
10

Saremo in grado di riordinare gli elementi sull’interfaccia?

Ad esempio, questo è l’editor delle impostazioni dell’oggetto sul componente del tema easy footer. Al momento non posso riorganizzare nessun elemento:

image
image335×431 13.2 KB

4 Mi Piace
11

Volevo richiedere anche questa funzionalità! :+1:

A parte questo, sarebbe utile se il primo post contenesse informazioni sulla proprietà identifier.

Prima di guardare l’immagine di Nolo qui sopra, pensavo che fosse impossibile sostituire l’etichetta figlio predefinita con un valore di proprietà. Dopo aver esaminato il codice, ho trovato la proprietà identifier.

4 Mi Piace
12

Il riordino è certamente qualcosa che è stato sollevato internamente. Cercherò di implementarlo questa settimana.

Preso nota. Aggiornerò il primo post sulla proprietà identifier.

5 Mi Piace
13

Sì, per sostituire il sistema JSON (che presto diventerà obsoleto?) è necessario che corrisponda o superi la vecchia interfaccia:

image
image365×103 915 Bytes

inclusa l’ordinazione.

1 Mi Piace
14

Ciao, ci sono piani per supportare presto altri tipi di campo?

Ad esempio;

  • una long_string con formato markdown; forse con barra degli strumenti personalizzabile,
  • un campo date (con regole di validazione),
  • un campo color (con regole di validazione)?
1 Mi Piace
15

Non ci sono piani attuali, anche se concordo sul fatto che sarebbe utile. Mi piacerebbe un campo icona per me.

8 Mi Piace
16

Per mia esperienza, sembra funzionare come preset salvati. In questo esempio le prime 2 voci potrebbero beneficiare di questi preset, ma qualsiasi cosa dopo, tutte le nuove voci appariranno inizialmente vuote.

Ciò significa anche che non possiamo impostare valori predefiniti per ogni campo. Ad esempio, se voglio che una casella di controllo sia selezionata per impostazione predefinita, non posso farlo.

links:
  type: objects
  default:
    - name: link 1
      title: link 1 title
    - name: link 2
      title: link 2 title
  schema:
    name: link
    properties:
      is_active:
        type: boolean
        default: true

default: true non funzionerà come previsto.

Ci potrebbe essere un modo per impostare i valori predefiniti per campo, per ogni voce creata?

18

Esiste un modo per importare le proprietà degli oggetti in variabili in Sass?

19

Puoi sempre analizzare la stringa, ma non sembra una buona idea promuoverla in questo modo. :sweat_smile:

1 Mi Piace
20

Grazie per aver condiviso l’esempio! Anche se sì… non sembra molto allettante :upside_down_face:

1 Mi Piace
21

Per curiosità, senza perdere troppo tempo a cercare, a che punto siamo con questo?

2 Mi Piace
22

Sì, non è molto buono, non farlo. :smile:. È stato più un tentativo di vedere se fosse possibile, ma non un approccio ragionevole.
Sono d’accordo con te; sarebbe bello avere un modo diretto! :+1:

Mi piacerebbe saperlo anche a me!
Inoltre, se non erro, quella sarebbe l’unica funzionalità mancante in parità con json_schema.

2 Mi Piace
23

Stavo cercando che il tipo di caricamento fosse disponibile, ma non lo è. Una rapida occhiata al core mostra che i tipi topic, post e upload sono stati implementati lato server ma non nel front end. C’è un motivo specifico per questo? :thinking: