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 alcuna riga di codice e preoccuparsi di perdere le proprie 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 principale del 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 sei familiare con lo sviluppo di plugin, questo non dovrebbe essere nuovo per te: funziona sostanzialmente 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 iniziare.
Un’impostazione del tema valida deve avere un nome e un valore predefinito; questo è il minimo indispensabile e appare così:
impostazione_semplice: true
Come probabilmente hai capito, 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 di 7.
Puoi accedere alle tue impostazioni nel codice JS in questo modo: settings.chiave_impostazione.
Fino a questo punto abbiamo coperto il modo più semplice per definire le impostazioni. Nella prossima sezione entreremo più nel dettaglio sui vari tipi di impostazioni e su come puoi utilizzarle.
Tipi supportati
Esistono 9 tipi di impostazioni:
integer(intero)float(virgola mobile)string(stringa)bool(per booleano)list(lista)enum(enumerazione)objects(sostituto dijson_schema)upload(per immagini)icon(per un singolo icona dal set di icone di Discourse)
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 stessa. Quindi puoi ridurre l’esempio sopra a questo:
impostazione_float:
default: 3.14
```\n
Detto questo, è _necessario_ impostare un attributo di tipo quando si lavora con impostazioni **`list`**, **`enum`** e **`icon`**, altrimenti Discourse non le riconoscerà correttamente.
**Impostazione Lista:**
```yaml
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 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 (cioè 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 il 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.
Impostazione Icona:
icona_banner:
default: bullhorn
type: icon
Le impostazioni icona forniscono 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 registrarla separatamente.
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 un testo descrittivo alla tua impostazione del tema e verrà visualizzato come etichetta direttamente sotto l’impostazione. Per farlo, basta aggiungere 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 quelle 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 vedi la tua lingua nella lista, potresti voler dare un’occhiata a How to add a new language)
Poi dovrai trovare il codice della tua lingua dalla lista sopra e usare 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 aggiuntive per le 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 forse l’intero sito.
Per specificare i limiti, basta aggiungere 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 un 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_pulsante_copia_autorizzati:
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_pulsante_copia_autorizzati) {
return;
}
// L'utente è in 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 utilizzare la stessa opzione su proprietà di tipo groups. Vedi tipo oggetti per le impostazioni del tema per i dettagli.
Argomenti correlati
Questo documento è sottoposto a controllo versione - suggerisci modifiche su github.