Aggiungi impostazioni al tuo tema Discourse

[Discourse]

Discourse offre la possibilità ai temi di avere “impostazioni” che possono essere aggiunte dagli sviluppatori del tema per consentire ai proprietari del sito di personalizzare i temi tramite l’interfaccia utente senza dover modificare alcuna riga di codice e preoccuparsi di perdere le modifiche con futuri aggiornamenti del tema.

I temi possono anche modificare determinate impostazioni del sito personalizzabili; per ulteriori informazioni a riguardo, consulta l’argomento Impostazioni del sito personalizzabili.

Aggiungere impostazioni al tuo tema

L’aggiunta di impostazioni al tuo tema è leggermente diversa dall’aggiunta di codice CSS e JS, nel senso che non è possibile farlo tramite l’interfaccia utente.

Il modo per aggiungere impostazioni è creare un repository per il tuo tema e, nella cartella radice del tuo repository, creare un nuovo file settings.yaml (o settings.yml). In questo file utilizzerai il linguaggio YAML per definire le impostazioni del tuo tema.

Nota: Potresti trovare utile utilizzare la Theme CLI, che semplifica enormemente il processo di sviluppo.

Se hai familiarità con lo sviluppo di plugin, questo non dovrebbe essere nuovo per te: funziona principalmente allo stesso modo dell’aggiunta di impostazioni del sito al tuo plugin. Basta inserire del YAML valido nel file delle impostazioni e sarai pronto per partire.

Un’impostazione del tema valida deve avere un nome e un valore predefinito, questo è il minimo indispensabile e ha questo aspetto:

impostazione_semplice: true

Come probabilmente avrai intuito, questo creerà un’impostazione con il nome impostazione_semplice e avrà true come valore predefinito.

In modo simile, puoi aggiungere qualcosa del genere:

nome_sito: I miei forum
avatar_massimi: 7

E avrai due impostazioni in più, nome_sito che sarà un’impostazione di tipo stringa con “I miei forum” come valore predefinito, e avatar_massimi come impostazione di tipo intero con valore predefinito 7.

Puoi accedere alle tue impostazioni nel tuo codice JS in questo modo: settings.chiave_impostazione.

Finora abbiamo coperto il modo più semplice per definire le impostazioni. Nella prossima sezione approfondiremo i vari tipi di impostazioni e come puoi utilizzarle.

Tipi supportati

Ci sono 8 tipi di impostazioni:

1. integer
2. float
3. string
4. bool (per booleano)
5. list
6. enum
7. objects (sostituto di json_schema)
8. upload (per immagini)

E puoi specificare il tipo aggiungendo un attributo type alla tua impostazione in questo modo:

impostazione_float:
  type: float
  default: 3.14

Dovrei dire che non è sempre necessario impostare esplicitamente un attributo type perché Discourse è abbastanza intelligente da dedurre il tipo di impostazione dal valore predefinito dell’impostazione. Quindi puoi ridurre l’esempio sopra a questo:

impostazione_float:
  default: 3.14

Detto questo, hai bisogno di impostare un attributo di tipo quando lavori con impostazioni list e enum, altrimenti Discourse non le riconoscerà correttamente.

Impostazione Lista:

frutti_autorizzati:
  default: mele|arance
  type: list

Impostazione Enum:

frutto_preferito:
  default: arancia
  type: enum
  choices:
    - mela
    - banana

Nel caso in cui la differenza tra impostazioni lista ed enum non ti sia chiara: le impostazioni enum consentono agli utenti del tema di selezionare solo un valore da un insieme di valori definiti da te (vedi l’attributo choices).

D’altra parte, le impostazioni lista consentono agli utenti di creare la propria lista (ovvero un array) di valori. Possono aggiungere o rimuovere valori dalla lista predefinita dell’impostazione.
Puoi impostare la lista predefinita di valori per l’impostazione unendo i valori con un carattere barra verticale |. Vedi l’impostazione lista nell’esempio sopra.

Puoi vedere un caso d’uso reale per le impostazioni lista qui: Auto-Linkify Words.

Nota: Fai attenzione all’indentazione quando lavori con YAML perché YAML è molto rigido riguardo agli spazi e genererà un errore di sintassi se l’indentazione del tuo codice è errata.

Tipo objects

Il tipo di impostazione objects è un tipo speciale che ti consente di realizzare impostazioni avanzate con struttura e convalida personalizzate. Abbiamo una documentazione separata per questo tipo.

Descrizione delle impostazioni e localizzazioni

Puoi aggiungere testo descrittivo alla tua impostazione del tema e verrà visualizzato come etichetta direttamente sotto l’impostazione. Per farlo, aggiungi semplicemente un attributo description alla tua impostazione in questo modo:

frutti_autorizzati:
  default: mele|arance
  type: list
  description: "Questo testo verrà visualizzato sotto questa impostazione e spiega cosa fa l'impostazione!"

E otterrai questo:

Supporto per più lingue

Se conosci più di una lingua e desideri aggiungere il supporto per queste lingue al tuo tema, puoi farlo purché Discourse supporti dette lingue.

Innanzitutto, assicurati che la lingua che desideri supportare sia in questa lista:

Lista lingue

Codice				Nome
ar				اللغة العربية
bs_BA				bosanski jezik
ca				català
cs				čeština
da				dansk
de				Deutsch
el				ελληνικά
en				English
es				Español
et				eesti
fa_IR				فارسی
fi				suomi
fr				Français
gl				galego
he				עברית
id				Indonesian
it				Italiano
ja				日本語
ko				한국어
lv				latviešu valoda
nb_NO				Norsk bokmål
nl				Nederlands
pl_PL				język polski
pt				Português
pt_BR				Português (BR)
ro				limba română
ru				Русский
sk				slovenčina
sq				Shqip
sr				српски језик
sv				svenska
te				తెలुగు
th				ไทย
tr_TR				Türkçe
uk				українська мова
ur				اردو
vi				Việt Nam
zh_CN				中文
zh_TW				中文 (TW)

(Se non riesci a vedere la tua lingua nella lista, potresti voler dare un’occhiata a How to add a new language)

Quindi dovrai trovare il codice della tua lingua dalla lista sopra e utilizzare il codice della lingua come chiave sotto l’attributo description e la traduzione come valore per la chiave in questo modo:

frutti_autorizzati:
  default: mele|arance
  type: list
  description:
    en: Testo in inglese
    ar: نص باللغة العربية
    fr: Testo francese

E ora hai il supporto per 3 lingue: inglese, arabo e francese.

Attributi e opzioni aggiuntivi delle impostazioni

Attributi min e max

A volte potresti aver bisogno di specificare limiti che un valore di impostazione non può superare per impedire agli utenti di rompere accidentalmente il tema o potenzialmente l’intero sito.

Per specificare i limiti, aggiungi semplicemente un attributo min o max o entrambi alla tua impostazione in questo modo:

impostazione_intera:
  default: 10
  min: 5
  max: 100

Puoi specificare limiti per impostazioni di tipo integer, float e string. Per le impostazioni integer e float, il valore dell’impostazione stessa viene controllato rispetto ai limiti. E per le impostazioni string, la lunghezza del valore viene controllata rispetto ai limiti specificati.

Se il tuo utente tenta di inserire un valore che non rientra nell’intervallo consentito, vedrà un errore che gli dice quali sono i valori min e max.

Accesso alle impostazioni nel tuo JS/CSS/Handlebars

Le impostazioni del tema sono rese disponibili globalmente come variabile settings nei file JavaScript del tema. Ad esempio:

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  console.log("le impostazioni sono", settings);
});

Questo oggetto settings è utilizzabile normalmente anche all’interno dei tag <template> .gjs.

Impostazione delle variabili CSS

In CSS, verrà creata una variabile per ogni impostazione del tuo tema e ogni variabile avrà lo stesso nome dell’impostazione che rappresenta.

Quindi se avessi un’impostazione float chiamata dimensione_font_globale e un’impostazione stringa chiamata sfondo_sito, potresti fare qualcosa del genere nel CSS del tuo tema:

html {
  font-size: #{$global-font-size}px;
  background: $site-background;
}

Risoluzione dell’appartenenza ai gruppi

I componenti del tema a volte devono mostrare o nascondere una funzionalità in base al fatto che l’utente corrente appartenga a un gruppo configurato. Evita di controllare currentUser.groups per questo perché include solo i gruppi visibili all’utente e può perdere i gruppi nascosti.

Per le impostazioni lista basate su gruppi, aggiungi resolve_group_membership: true per risolvere il controllo lato server:

gruppi_autorizzati_pulsante_copia:
  default: "1|3"
  type: list
  list_type: group
  resolve_group_membership: true

Questa opzione è valida solo quando l’impostazione ha type: list e list_type: group. Quando è abilitata, l’oggetto settings frontend non include la lista originale dei gruppi. Invece, Discourse aggiunge un booleano con lo stesso nome dell’impostazione preceduto da user_in_:

// {theme}/javascripts/discourse/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  if (!settings.user_in_gruppi_autorizzati_pulsante_copia) {
    return;
  }

  // L'utente è in almeno uno dei gruppi selezionati.
});

Il booleano generato funziona anche con gruppi automatici come logged_in_users e anonymous_users.

Argomenti correlati

• Developing Discourse Themes & Theme Components

---

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

[mcwumbly (Dave McClure)]

@Osama

Tipo json_schema

Il tipo di impostazione JSON Schema è un tipo di impostazione nuovo e unico che ti consente di realizzare molte impostazioni complesse

Mi chiedo se dovremmo sostituire questa sezione con qualcosa su: Objects type for theme setting

Forse vogliamo anche un riferimento da questo documento a: Migrate Discourse theme settings

[pfaffman (Jay Pfaffman)]

@Discourse

Tipo json_schema

Il tipo JSON Schema è un nuovo e unico tipo di impostazione che consente di realizzare molte impostazioni complesse.

@mcwumbly

Mi chiedo se dovremmo sostituire questa sezione con qualcosa su: Tipo Oggetti per impostazione del tema

Sì. Ho perso quasi un’ora cercando di far funzionare i json_schemas. (Anche se ero a conoscenza del modo nuovo e migliorato per farlo!!)

@Osama, se non puoi aggiornarlo da solo, per favore chiedi a qualcuno che possa farlo. Grazie.

[Osama]

Mi dispiace che sia successo, ecco una PR per aggiornare la documentazione Replace references to `json_schema` with `objects` type documentation by OsamaSayegh · Pull Request #26 · discourse/discourse-developer-docs · GitHub

[gormus (Osman Görmüş)]

Come posso usare un’immagine definita come asset per essere utilizzata come valore predefinito per un campo di caricamento nelle impostazioni del tema?

Purtroppo, quanto segue non funziona. Mi chiedo se ci sia un metodo dedicato per questo. O anche se è effettivamente possibile?

Esiste un modo per ottenere l’URL dell’asset dinamicamente da utilizzare come valore predefinito?

// about.json
{
  "assets": {
    "box_default_image": "assets/box-default-image.png"
  }
}

# settings.yml

box_image:
  type: upload
  default: settings.theme_uploads.box_default_image

[Moin]

Hai provato la chiave da about.json? Qualcosa come

# settings.yml

box_image:
  type: upload
  default: "box_default_image"

[gormus (Osman Görmüş)]

@moin Funziona perfettamente! Grazie!