Discourse offre la possibilità ai temi di avere “impostazioni” che possono essere aggiunte dagli sviluppatori di temi per consentire ai proprietari dei siti di personalizzare i temi tramite l’interfaccia utente, senza dover modificare alcuna riga di codice e preoccuparsi di perdere le modifiche con i 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 qualcosa di nuovo per te: funziona principalmente allo stesso modo dell’aggiunta di impostazioni del sito al tuo plugin. Basta inserire del YAML valido nel tuo file delle impostazioni e sarai pronto a procedere.
Un’impostazione del tema valida deve avere un nome e un valore predefinito, questo è il minimo indispensabile e ha questo aspetto:
simple_setting: true
Come probabilmente hai capito, questo creerà un’impostazione con il nome simple_setting e avrà true come valore predefinito.
In modo simile, puoi aggiungere qualcosa del genere:
site_name: My Forums
max_avatars: 7
E avrai due impostazioni in più, site_name che sarà un’impostazione di tipo 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.
Finora abbiamo coperto il modo più semplice per definire le impostazioni. Nella prossima sezione esploreremo più a fondo i vari tipi di impostazioni e come puoi utilizzarle.
Tipi supportati
Esistono 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:
float_setting:
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:
float_setting:
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:
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 impostazioni lista ed enum non ti sia chiara: le impostazioni enum consentono agli utenti del tuo tema di selezionare solo un valore da un insieme di valori da te definiti (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 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 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à mostrato come etichetta direttamente sotto l’impostazione. Per farlo, aggiungi semplicemente 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 queste lingue al tuo tema, puoi farlo assolutamente, 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 trovare 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 utilizzare 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 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 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, aggiungi semplicemente 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 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 è 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. Per 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 è anche utilizzabile normalmente 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 global_font_size e un’impostazione stringa chiamata site_background, potresti fare qualcosa del genere nel CSS del tuo tema:
html {
font-size: #{$global-font-size}px;
background: $site-background;
}
Risoluzione dell’appartenenza al gruppo
I componenti del tema a volte hanno bisogno di 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 di tipo lista 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 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_copy_button_allowed_groups) {
return;
}
// L'utente è in almeno uno dei gruppi selezionati.
});
Il booleano generato funziona anche con gruppi automatici come logged_in_users e anonymous_users. Le impostazioni del tema di tipo oggetto possono utilizzare la stessa opzione su proprietà type: groups. Vedi tipo oggetti per impostazioni del tema per i dettagli.
Argomenti correlati
Questo documento è sotto controllo di versione - suggerisci modifiche su github.