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:
integerfloatstringbool(per booleano)listenumobjects(sostituto dijson_schema)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.
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
Questo documento è sotto controllo versione - suggerisci modifiche su github.