Tipo di oggetti per l'impostazione del tema

Stiamo introducendo un nuovo type: objects in the supported types for theme settings, che può essere utilizzato per sostituire il tipo json_schema esistente, che intendiamo deprecare a breve.

Definire un’impostazione del tema di tipo objects

Per creare un’impostazione del tema di tipo objects, definisci prima una chiave di primo livello, come faresti con qualsiasi altra impostazione del tema, che verrà utilizzata come nome dell’impostazione.

links: ...

Aggiungi successivamente le parole chiave type, default e schema all’impostazione.

links:
  type: objects
  default: []
  schema: ...

type: objects indica che si tratta di 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, come dimostreremo una volta definito lo schema.

Per definire lo schema, specifica prima il name dello schema come segue:

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

Successivamente, aggiungeremo la parola chiave properties allo schema, che ci permetterà di definire e convalidare come dovrebbe essere fatto ogni oggetto.

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

Nell’esempio sopra, affermiamo 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 stabilisce 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 salvato come stringa. Imposta textarea: true per utilizzare un’area di testo espandibile:

    description:
      type: string
      textarea: true
      validations:
        max_length: 500
    
  • integer: il valore della proprietà viene salvato come intero.

  • float: il valore della proprietà viene salvato come 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:
              - name 1
              - name 2
              - name 3
    
  • categories: il valore della proprietà è un array di ID categorie validi.

  • groups: il valore della proprietà è un array di ID gruppi validi.

  • tags: il valore della proprietà è un array di nomi tag validi.

  • icon: il valore della proprietà è il nome di una singola icona del set di icone Discourse. Le icone selezionate vengono aggiunte automaticamente al foglio sprite (sprite sheet), quindi possono essere renderizzate senza essere registrate separatamente.

Quando si aggiorna un’impostazione del tema di tipo objects tramite l’API, gli array tags possono contenere nomi di tag di origine, ID tag interi o entrambi. Gli ID vengono risolti nei nomi di origine prima della convalida e dell’archiviazione. I temi ricevono comunque array di nomi di origine. Le stringhe numeriche vengono trattate come nomi, non come ID, e i valori predefiniti devono usare i nomi.

Il renderer dei tag frontend predefinito include data-tag-id per gli oggetti tag con un ID, o per i nomi di tag renderizzati con l’opzione tagId. L’attributo data-tag-name esistente rimane invariato. L’ID rimane lo stesso tra le diverse localizzazioni anche quando il nome visualizzato cambia. Le chiamate di rendering solo-nome senza un ID omettono data-tag-id.

Gli oggetti con proprietà tags dirette ricevono automaticamente un array tag_objects associato nelle impostazioni frontend:

{
  tags: ["support"],
  tag_objects: [
    { id: 42, name: "support" }
  ]
}

Gli array di nomi di tag esistenti rimangono invariati. Ogni oggetto associato contiene l’ID del tag e l’esatta stringa del nome di origine originale dall’impostazione, inclusa la sua formattazione maiuscole/minuscole. Non sostituisce un nome visualizzato tradotto. I componenti possono utilizzare gli ID per fare riferimento ai tag selezionati, ad esempio quando si mira a data-tag-id nel CSS. Il core non renderizza l’array associato come interfaccia utente né aggiunge un’impostazione di amministrazione per esso.

L’associato combina le selezioni tags dirette dell’oggetto nel loro ordine originale, preservando le selezioni ripetute. Gli oggetti nidificati ottengono i propri associati. Vengono inclusi solo i tag visibili al visitatore; le selezioni mancanti, eliminate o nascoste vengono omesse. L’associato è comunque presente come [] quando nessun tag viene risolto. Non presumere che i suoi indici corrispondano all’array di stringhe originale.

Non è richiesta alcuna attivazione esplicita o richiesta API del browser aggiuntiva. Una proprietà di schema definita dall’autore denominata tag_objects ha la precedenza: il core conserva quel campo e non genera un associato a quel livello. Dichiara qualsiasi campo personalizzato esistente con questo nome; i valori tag_objects non dichiarati vengono trattati come metadati generati e rimossi. Gli oggetti senza proprietà tags dirette e le impostazioni di elenchi di tag legacy di primo livello rimangono invariati.

L’associato viene generato solo per i dati della pagina frontend. Le impostazioni archiviate e i valori di modifica dell’amministrazione mantengono la loro struttura esistente; i metadati generati inviati nuovamente tramite l’API delle impostazioni vengono scartati. I componenti che supportano i contesti o versioni di Discourse più vecchie senza questi dati possono verificare Array.isArray(style.tag_objects) e tornare al loro comportamento esistente basato sui nomi quando non sono disponibili.

Una volta definito lo schema, 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 per impostazione predefinita. Per contrassegnare una proprietà come obbligatoria, annota semplicemente la proprietà con required: true. Una proprietà può anche essere contrassegnata come facoltativa annotando la proprietà con required: false.

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

I valori stringa vuoti, datetime e icon, e gli elenchi vuoti categories, groups e tags contano come mancanti: le proprietà obbligatorie li rifiutano e le proprietà facoltative saltano le loro convalide. false conta come impostato.

Convalide personalizzate

Per alcuni tipi di proprietà, c’è il supporto integrato per le convalide 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

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

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

Convalide 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 al gruppo

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 solo bisogno 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: section 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 archiviata utilizzano ancora l’array groups originale. 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 è in almeno uno dei gruppi selezionati per questa sezione.
  }
}

Questa opzione è valida solo sulle proprietà dello schema degli oggetti con type: groups. Funziona anche con gli schemi di oggetti nidificati e con i gruppi automatici come logged_in_users e anonymous_users.

Struttura di oggetti nidificati

Un oggetto può anche avere una proprietà che contiene un array di oggetti. Per creare una struttura di oggetti nidificati, una proprietà può anche essere annotata con type: objects e la definizione di schema associata.

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 e localizzazione dell’impostazione

Per aggiungere una descrizione per l’impostazione nella localizzazione en, crea un file locales/en.yml con il seguente formato, data la seguente impostazione del tema di tipo 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: Questa è una descrizione per l'impostazione del tema delle 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à

Testo degli oggetti traducibile

Dichiara una proprietà stringa obbligatoria denominata translation_key e contrassegna le proprietà di testo con translatable: true per esporli in Testi del sito. Il core legge i valori predefiniti dalle impostazioni degli oggetti salvate e li include nei normali asset di traduzione dei temi. I componenti del tema non richiedono codice backend.

links:
  type: objects
  default:
    - translation_key: guidelines
      label: Community guidelines
  schema:
    name: link
    identifier: label
    properties:
      translation_key:
        type: string
        required: true
      label:
        type: string
        translatable: true

Questo espone js.theme_translations.<theme_id>.links.guidelines.label con il testo predefinito “Community guidelines” e la lingua predefinita en. Il frontend continua a utilizzare i18n(themePrefix(`links.${link.translation_key}.label`), { defaultValue: link.label }) per ogni link nell’impostazione.
L’editor anteprime le chiavi relative da passare a themePrefix e i collegamenti a Testi del sito filtrati per il componente. Salva le modifiche prima di gestire le traduzioni.

Il core limita le chiavi all’ID del tema installato e al nome dell’impostazione dell’oggetto. La lingua predefinita del testo è en; opzionalmente imposta translations: { default_locale: fr } nello schema radice per cambiarla. Non è necessario alcun blocco translations altrimenti. Gli schemi nidificati dichiarano la loro proprietà translation_key obbligatoria di tipo stringa e contrassegnano le loro proprietà traducibili; le chiavi degli oggetti antenati e i nomi delle proprietà della raccolta sono inclusi in ogni chiave nidificata. Ad esempio, una sezione con la chiave getting_started che contiene un link con la chiave guidelines produce theme_translations.<theme_id>.resource_sections.getting_started.links.guidelines.label per l’impostazione resource_sections.

Gli schemi con campi traducibili, inclusi i loro schemi di oggetti antenati, devono dichiarare translation_key con type: string e required: true. La convalida dello schema controlla ciò anche quando l’elenco predefinito degli oggetti è vuoto. L’opzione separata schema.identifier: label sceglie l’etichetta di visualizzazione dell’editor; non seleziona l’identificatore della traduzione.

Usa identificatori stabili assegnati manualmente che iniziano con una lettera minuscola e contengono solo lettere minuscole, cifre e trattini bassi. Gli identificatori devono avere una lunghezza massima di 80 caratteri ed essere unici all’interno di ogni raccolta. I nomi delle impostazioni traducibili, i nomi dei campi e i nomi delle raccolte nidificate iniziano anch’essi con una lettera minuscola e contengono solo lettere minuscole, cifre e trattini bassi. Riordinare preserva le traduzioni. Rinominare un identificatore crea nuove chiavi di traduzione; duplicare un oggetto richiede una chiave diversa. Le installazioni separate dei componenti hanno spazi dei nomi indipendenti.

Quando si aggiungono campi traducibili a un componente esistente, fornisci una migrazione delle impostazioni che aggiunga valori translation_key validi agli oggetti personalizzati. Gli aggiornamenti del componente convalidano le chiavi di traduzione finali degli oggetti e ricostruiscono le loro traduzioni dopo il completamento delle migrazioni delle impostazioni. Le chiavi finali non valide eseguono il rollback dell’aggiornamento. I salvataggi ordinari dell’editor degli oggetti convalidano immediatamente. Se gli identificatori degli oggetti salvati non sono validi, i percorsi di lettura omettono i valori predefiniti degli oggetti in modo che le traduzioni dei file delle localizzazioni e gli asset rimangano disponibili; il salvataggio delle impostazioni degli oggetti e l’applicazione delle migrazioni convalidano comunque rigorosamente.

Partecipano solo i campi stringa contrassegnati come translatable: true. I campi non contrassegnati e i campi con translatable: false sono esclusi. I campi vuoti facoltativi mantengono le loro chiavi e le traduzioni esistenti. Cancellare il testo predefinito non elimina le traduzioni. Le raccolte nidificate includono il loro nome di proprietà nella chiave, quindi raccolte separate possono riutilizzare gli stessi identificatori di oggetti.
I valori predefiniti includono i valori predefiniti del tema e le impostazioni importate. La modifica del testo predefinito contrassegna le traduzioni come obsolete. I valori predefiniti rimangono nell’impostazione dell’oggetto; le traduzioni utilizzano il modello ThemeTranslationOverride esistente, proprio come i campi dei file delle localizzazioni. Non c’è un registro di testo separato.

Rimuovere un oggetto, una dichiarazione di campo traducibile o una chiave del file delle localizzazioni non elimina le relative sostituzioni di traduzione salvate. Le sostituzioni senza una fonte attuale hanno uno stato deprecated (deprecato) e vengono mantenute attraverso salvataggi delle impostazioni, migrazioni e aggiornamenti dei componenti. Ripristinare la stessa chiave di traduzione riutilizza la personalizzazione salvata, anche dopo un rollback del componente. Questo preserva il comportamento esistente di traduzione dei file delle localizzazioni per i componenti che non optano per le traduzioni degli oggetti. Le chiavi rimosse non sono elencate in Testi del sito fino a quando le loro dichiarazioni di fonte non vengono ripristinate.
Se le modifiche allo schema fanno sì che una chiave mantenuta entri in conflitto con la struttura nidificata di una chiave attuale, la dichiarazione attuale determina la forma runtime. Entrambe le sostituzioni salvate rimangono disponibili per il ripristino se lo schema viene ripristinato.

Ripristinare esplicitamente una traduzione rimuove comunque tale sostituzione e ripristina il valore predefinito spedito per la localizzazione selezionata. Eliminare il componente rimuove tutte le sue sostituzioni di traduzione.

Testi del sito mostra il testo predefinito e la sua lingua insieme alla traduzione modificabile. Sia i campi dell’editor degli oggetti che le stringhe spedite nei file delle localizzazioni utilizzano js.theme_translations.<theme_id>.<key> in Testi del sito. Le traduzioni salvate prima che il tracciamento dei valori predefiniti fosse disponibile hanno una linea di base sconosciuta e sono escluse dal filtro obsoleto. Riconoscere il valore predefinito attuale stabilisce una linea di base senza modificare la traduzione. I segnaposto di interpolazione dei campi degli oggetti sono verificati rispetto al testo di origine dichiarato, non alle sostituzioni di origine personalizzate. Le forme plurali possono utilizzare i segnaposto dichiarati dalla loro forma other sorella. Le sostituzioni dei file delle localizzazioni mantengono il loro comportamento esistente di segnaposto illimitati perché il componente può fornire argomenti runtime che il suo testo spedito non utilizza. Testi del sito non contrassegna questi argomenti come non validi.

Il tracciamento dei valori predefiniti utilizza il campo dell’oggetto salvato o il testo inglese spedito, ricadendo sul testo spedito per la localizzazione selezionata quando non esiste una chiave inglese. Le sostituzioni della localizzazione di origine non sostituiscono questa linea di base. La lingua del valore predefinito è mostrata esplicitamente; ripristinare una sostituzione del file delle localizzazioni ripristina comunque il testo spedito per la localizzazione selezionata.

Il nome dell’impostazione riserva uno spazio dei nomi all’interno del tema. Un file delle localizzazioni non può anche definire la chiave radice di quell’impostazione: il salvataggio dell’impostazione dell’oggetto o l’aggiornamento del tema rifiuta il conflitto. Il testo viene consegnato esclusivamente tramite gli asset di traduzione dei temi in cache esistenti solo per il tema attivo e i suoi componenti, incluse le anteprime.


Questo documento è sotto controllo versione - suggerisci modifiche on github.

16 Mi Piace

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

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

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

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

Ecco alcuni feedback:

2 Mi Piace

Ho notato questo ed è stato corretto in

1 Mi Piace

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:

4 Mi Piace

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

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

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

inclusa l’ordinazione.

1 Mi Piace

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

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

8 Mi Piace

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?

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

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

1 Mi Piace

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

1 Mi Piace

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

2 Mi Piace

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

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: