Discourse offre la possibilità ai temi di avere “impostazioni” che possono essere aggiunte dagli sviluppatori di temi per consentire ai proprietari del sito di personalizzare i temi tramite l’interfaccia utente, senza dover modificare una sola riga di codice e senza preoccuparsi di perdere le proprie modifiche con i futuri aggiornamenti del tema.
I temi possono anche modificare determinate impostazioni di sito tematizzabili; per ulteriori informazioni al riguardo, consulta l’argomento Impostazioni di sito tematizzabili.
Aggiunta di impostazioni al tuo tema
L’aggiunta di impostazioni al tuo tema è leggermente diversa dall’aggiunta di codice CSS e JS, nel senso che non esiste un modo per farlo tramite l’interfaccia utente.
Il modo per aggiungere impostazioni è creare un repository per il tuo tema e, nella cartella principale 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 fare uso della Theme CLI, che semplifica enormemente il processo di sviluppo.
Ora, se sei familiare con lo sviluppo di plugin, questo non dovrebbe essere un concetto nuovo per te: funziona in gran parte allo stesso modo dell’aggiunta di impostazioni di sito al tuo plugin. Basta inserire dello YAML valido nel tuo file di impostazioni e sarai a posto.
Un’impostazione del tema valida deve avere un nome e un valore predefinito; è il minimo indispensabile e ha questo aspetto:
simple_setting: true
Come probabilmente puoi intuire, questo creerà un’impostazione con il nome simple_setting e avrà true come suo valore predefinito.
Allo stesso modo, puoi aggiungere qualcosa come questo:
site_name: My Forums
max_avatars: 7
E avrai due impostazioni in più: site_name, che sarà un’impostazione di stringa con “My Forums” come valore predefinito, e max_avatars come impostazione di tipo intero con valore predefinito di 7.
Puoi accedere alle tue impostazioni nel tuo codice JS in questo modo: settings.your_setting_key.
Quindi, fino a questo punto abbiamo coperto il modo più semplice per definire le impostazioni. Nella prossima sezione, esamineremo un po’ più a fondo i vari tipi di impostazioni e come puoi usarle.
Tipi supportati
Esistono 9 tipi di impostazioni:
integerfloatstringbool(per booleano)listenumobjects(sostituto dijson_schema)upload(per immagini)icon(per un’icona singola dal set di icone di Discourse)
E puoi specificare il tipo aggiungendo un attributo type alla tua impostazione in questo modo:
float_setting:
type: float
default: 3.14
Dovrei dire che non devi sempre impostare esplicitamente un attributo type, perché Discourse è abbastanza intelligente da dedurre il tipo di impostazione dal valore predefinito dell’impostazione stessa. Quindi puoi ridurre l’esempio sopra a questo:
float_setting:
default: 3.14
Detto questo, hai bisogno di impostare un attributo di tipo quando lavori con le impostazioni list, enum** e **icon`, altrimenti Discourse non le riconoscerà correttamente.
Impostazione List:
whitelisted_fruits:
default: apples|oranges
type: list
Impostazione Enum:
favorite_fruit:
default: orange
type: enum
choices:
- apple
- banana
Nel caso in cui la differenza tra le impostazioni list e enum non ti sia chiara: le impostazioni enum consentono ai tuoi 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 list consentono ai tuoi utenti di creare la propria lista (ovvero un array) di valori. Possono aggiungere o rimuovere elementi dalla lista di valori predefinita dell’impostazione.
Puoi impostare la lista di valori predefinita per l’impostazione unendo i valori con un carattere barra verticale |. Vedi l’impostazione list nell’esempio sopra.
Puoi vedere un caso d’uso reale per le impostazioni list qui: Auto-Linkify Words.
Impostazione Icon:
banner_icon:
default: bullhorn
type: icon
Le impostazioni icon offrono ai proprietari del sito un selettore di icone ricercabile e il valore è il nome dell’icona. Discourse aggiunge l’icona selezionata alla sprite sheet, quindi puoi renderizzarla nel tuo tema senza doverla registrare separatamente.
Tipo objects
Il tipo di impostazione objects è un tipo speciale che ti consente di realizzare impostazioni avanzate con struttura e validazioni personalizzate. Abbiamo una documentazione separata per questo tipo.
Descrizione e localizzazioni delle impostazioni
Puoi aggiungere testo di descrizione alla tua impostazione del tema e verrà mostrato come etichetta direttamente sotto l’impostazione. Per farlo, basta aggiungere un attributo description alla tua impostazione in questo modo:
whitelisted_fruits:
default: apples|oranges
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 quelle lingue al tuo tema, puoi farlo senza problemi, a condizione che Discourse supporti dette lingue.
Prima di tutto, assicurati che la lingua che desideri supportare sia in questo elenco:
Elenco 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 nell’elenco, potresti voler dare un’occhiata a How to add a new language)
Poi dovrai trovare il codice della tua lingua dall’elenco sopra e usare il codice della lingua come chiave sotto l’attributo description e la traduzione come valore per la chiave in questo modo:
whitelisted_fruits:
default: apples|oranges
type: list
description:
en: Testo in inglese
ar: نص باللغة العربية
fr: Testo in francese
E ora hai il supporto per 3 lingue: inglese, arabo e francese.
Attributi e opzioni aggiuntive delle impostazioni
Attributi Min e max
A volte potresti aver bisogno di specificare dei limiti che un valore dell’impostazione non può superare per impedire ai tuoi utenti di rompere accidentalmente il tema o, in alcuni casi, l’intero sito.
Per specificare dei limiti, basta aggiungere un attributo min o max o entrambi alla tua impostazione in questo modo:
integer_setting:
default: 10
min: 5
max: 100
Puoi specificare limiti per le impostazioni di tipo integer, float e string. Per le impostazioni integer e float, il valore dell’impostazione stessa viene confrontato con i limiti. E per le impostazioni string, la lunghezza del valore viene confrontata con i limiti specificati.
Se il tuo utente tenta di inserire un valore che non rientra nell’intervallo consentito, vedrà un errore che gli indica quali sono i valori min e max.
Accesso alle impostazioni nel tuo JS/CSS/Handlebars
Le impostazioni del tema sono rese globalmente disponibili 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("settings are", settings);
});
Questo oggetto settings è anche utilizzabile normalmente all’interno dei tag <template> .gjs.
Impostazione di variabili CSS
In CSS, verrà creata una variabile per ogni impostazione del tuo tema e ciascuna variabile avrà lo stesso nome dell’impostazione che rappresenta.
Quindi, se avevi un’impostazione float chiamata global_font_size e un’impostazione string chiamata site_background, potresti fare qualcosa come questo nel tuo CSS del tema:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Risoluzione dell’appartenenza ai gruppi
I componenti del tema a volte hanno bisogno di mostrare o nascondere una funzionalità in base a se l’utente corrente appartiene 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 list basate su gruppi, aggiungi resolve_group_membership: true per risolvere il controllo lato server:
copy_button_allowed_groups:
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 del frontend non include l’elenco 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_copy_button_allowed_groups) {
return;
}
// L'utente appartiene ad almeno uno dei gruppi selezionati.
});
Il booleano generato funziona anche con i gruppi automatici come logged_in_users e anonymous_users. Le impostazioni del tema di tipo oggetto possono usare la stessa opzione sulle proprietà type: groups. Consulta objects type for theme settings per i dettagli.
Argomenti correlati
Questo documento è sottoposto a controllo di versione - suggerisci modifiche su github.