Quindi sei interessato a progettare il tuo tema per Discourse? Sei capitato nel posto giusto 
Questa guida sarà più focalizzata sugli aspetti SCSS/CSS della creazione di temi in Discourse. Se hai anche conoscenze in JS/EmberJs/Handlebars, puoi approfondire ulteriormente consultando questa guida.
Ti descriverò il mio metodo personale per la progettazione e la tematizzazione in Discourse. Come per molte altre cose, ci sono TANTISSIMI modi per implementare i propri design. Mi piace usare molto gli strumenti di ispezione quando creo temi e ti mostrerò alcune volte come lo faccio in questo post.
Preparazione per la Tematizzazione
Ti preghiamo di leggere Guida per principianti all’uso dei temi Discourse, nonché la Struttura dei temi… prima di continuare. Non è necessaria una conoscenza approfondita a questo punto, ma questi articoli ti daranno un po’ più di familiarità prima di iniziare.
Per lavorare al meglio con la tematizzazione in Discourse, suggerisco di configurarsi con i seguenti strumenti per offrirti il processo di design più rapido e snello possibile. Questi passaggi ti permetteranno di vedere le modifiche mentre le apporti, senza dover cliccare su ‘Salva’ e aggiornare dal pannello di amministrazione di un sito Discourse.
È assolutamente possibile seguire questa guida utilizzando la console di amministrazione (a patto di avere accesso di livello amministratore a un forum Discourse.)
- Installa Discourse Theme CLI e leggi quell’argomento per capire cosa può fare.
- Ottieni una Chiave API da https://discourse.theme-creator.io/
- Accedi con il tuo account Meta
- Clicca su I miei temi
- Clicca su Chiave API
- Nella finestra modale popup, clicca su Genera chiave API e copia la chiave generata per te (la useremo tra poco)
Esecuzione della Discourse Theme CLI
Con la Discourse Theme CLI installata e la tua Chiave API pronta, apri il tuo editor di testo o finestra di terminale preferito e cambia la directory di lavoro nella posizione in cui desideri che venga impostata la cartella del tuo tema.
Una volta lì, esegui il seguente comando discourse_theme new your_theme_name e compila i prompt come segue:
-
Come vuoi chiamare il tuo tema? Scegli il nome del tuo tema
-
Vuoi iniziare a monitorare questo tema? Sì
-
Qual è l’URL radice del tuo sito Discourse?
https://discourse.theme-creator.io/ -
Vuoi che questo nome del sito venga salvato in…? Sì
-
Qual è la tua Chiave API? Inserisci la chiave API che hai ottenuto da theme creator
-
Vuoi che questa chiave API venga salvata…? Sì
-
Scegli Crea e sincronizza con un nuovo tema quando richiesto
-
Scegli Non fare nulla quando richiesto riguardo ai componenti del tema figlio
Se tutto ha funzionato correttamente, ora dovresti essere in grado di navigare su I miei temi su https://discourse.theme-creator.io/ e vedere il tuo nuovo tema nell’elenco dei temi a sinistra.
Per visualizzare queste modifiche in tempo reale, clicca sul nome del tuo tema, quindi nella parte inferiore dell’area informazioni, clicca su Anteprima
La Theme CLI ora monitora anche eventuali modifiche nella directory appena creata e salverà, nonché aggiornerà il tema su theme-creator con ogni modifica.
Primi Passi
La Discourse Theme CLI ha creato una struttura per il tema all’interno della cartella con il nome specificato nel comando eseguito in precedenza. Vengono generati molti file che non useremo, quindi andremo avanti ed elimineremo tutto tranne quanto segue:
common/common.scss
desktop/desktop.scss
mobile/mobile.scss
about.json
All’interno della directory, esegui anche rm -rf .git per rimuovere il tracciamento delle versioni di git, non sarà necessario per questa guida.
La directory del tuo tema dovrebbe ora sembrare così:
Vale la pena notare che gli stili che aggiungiamo a questi file verranno renderizzati nel rispettivo caso d’uso. Gli stili in common.scss verranno applicati a desktop + mobile, mentre gli stili in desktop.scss verranno applicati solo alla navigazione desktop e quelli in mobile.scss si applicheranno solo alle viste mobili.
Hello World (in colore)
Discourse utilizza SCSS per la sua stilizzazione, quindi per sfruttare al meglio gli stili, potresti voler familiarizzare con SASS, ma se non lo fai, potrai comunque seguire questa guida.
Ok, ora arriviamo a ciò per cui tutti stavano aspettando… LA TEMATIZZAZIONE!
Al momento, il nostro about.json non ha ancora schemi di colore definiti, quindi incolla il seguente codice in quella sezione e poi salva.
{
"name": "my theme",
"about_url": null,
"license_url": null,
"assets": {},
"color_schemes": {
"Default": {
"primary": "222222",
"secondary": "ffffff",
"tertiary": "0088cc",
"quaternary": "e45735",
"header_background": "ffffff",
"header_primary": "333333",
"highlight": "ffff4d",
"danger": "e45735",
"success": "009900",
"love": "fa6c8d"
}
}
}
Se hai il browser aperto, non avresti visto alcun cambiamento, perché questo è lo schema di colori predefinito utilizzato quando non è presente alcuno schema.
Panoramica del Tema
Per avere qualcosa di concreto da implementare in questa guida, ti guiderò nella creazione di un tema semplice basato su questa palette di colori.
Modifica del Colore di SFondo + Colore del Testo Primario
Facciamo qualcosa di molto semplice. Andremo avanti e modificheremo il valore "Secondary" del nostro schema di colori attuale. Cambiamolo in "secondary": "EEF4F7" (questo cambia il colore di sfondo). Cambiamo anche il valore "primary" in "203243".
Con solo quella riga, abbiamo già cambiato l’aspetto e la sensazione del nostro forum. Molte personalizzazioni possono essere fatte semplicemente modificando i colori nello schema di colori.
Utilizzo dello Schema di Colori
Tutte le seguenti chiavi sono definite nel file about.json sotto il nome corrispondente dello schema di colori. Queste descrizioni sono un buon riferimento per aiutarti a capire qual è lo scopo principale di ogni nome di variabile:
| Colore | Descrizione |
|---|---|
| primary | La maggior parte del testo, delle icone e dei bordi |
| secondary | Il colore di sfondo principale e il colore del testo di alcuni pulsanti |
| tertiary | Link, alcuni pulsanti, notifiche e colore di accento |
| quaternary | Link di navigazione |
| header_background | Colore di sfondo dell’intestazione del sito |
| header_primary | Testo e icone nell’intestazione del sito |
| highlight | Il colore di sfondo degli elementi evidenziati nella pagina, come post e argomenti |
| danger | Colore di evidenziazione per azioni come l’eliminazione di post e argomenti |
| success | Usato per indicare che un’azione è stata completata con successo |
| love | Il colore del pulsante Mi piace |
Ognuna di queste variabili è disponibile per noi da usare all’interno dei nostri file SCSS come segue.
body {
background-color: var(--primary);
}
Vengono create anche altre versioni di ciascun colore per essere utilizzate. Cose come var(--primary-medium) o var(--primary-very-low) possono essere usate per ottenere tonalità diverse dello stesso colore.
Cambiamo gli altri colori nel nostro schema di colori “Default” per corrispondere a questo:
"Default": {
"primary": "203243",
"secondary": "EEF4F7",
"tertiary": "416376",
"quaternary": "5E99B9",
"header_background": "FaFaFa",
"header_primary": "EEF4F7",
"highlight": "86BDDB",
"danger": "8F393E",
"success": "70DB82",
"love": "FC94CB"
}
Puoi vedere tutte le variabili disponibili per l’uso nei tuoi file SCSS se clicchi sul link Guida agli stili mentre visualizzi l’anteprima del tuo tema su theme creator, poi cliccando su Colori nel menu a sinistra.
La Guida agli stili è una sezione molto utile da consultare quando si crea un tema personalizzato. Ogni Atomo ti mostrerà come appariranno determinati elementi di Discourse con i tuoi stili applicati.
Approfondimenti
Con la sezione precedente alle spalle, penso che sia il momento di approfondire un po’ cosa si può fare in Discourse usando solo SCSS. (Indizio: MOLTE COSE!)
Stilizzazione dell’Intestazione
Noterai che le nostre modifiche precedenti allo schema di colori hanno lasciato qualcosa a desiderare nella nostra intestazione. Le icone sono a malapena visibili!
L’intestazione di Discourse include un contenitore (con un colore di sfondo) per contenere il logo del sito, nonché le icone di navigazione a destra. Tutte queste possono essere personalizzate.
La classe target per personalizzare l’intestazione è .d-header.
Nel nostro file common/common.scss, aggiungiamo quanto segue:
.d-header {
box-shadow: none;
border-bottom: 1px solid var(--primary-low-mid);
height: 5em;
}
Questo rimuoverà l’ombra della casella predefinita sull’intestazione, le darà un po’ più di altezza, nonché impostare un bordo inferiore per darci un po’ di separazione.
Per le icone – All’interno delle parentesi SCSS di .d-header, aggiungiamo questo codice annidato.
.d-header {
// ...codice precedente
.d-icon {
color: var(--primary-low-mid);
}
}
Questo sembra buono, ma un occhio attento noterà che l’aumento dell’altezza dell’intestazione ci ha dato meno spazio tra essa e il resto degli elementi del forum Discourse!
Lo spazio tra l’area principale e l’intestazione è controllato dal target #main-outlet. Aumentiamo leggermente questo spazio aggiungendo quanto segue alla fine del tuo file common/common.scss.
#main-outlet {
padding-top: 6.5em;
}
Contenitore di Navigazione
Il contenitore di navigazione include le seguenti parti.
L’area più a sinistra è costituita dai menu a discesa per il filtro di categoria/tag, seguiti dai link di navigazione, terminati dal pulsante Nuovo Argomento.
Menu a Discesa Categoria / Tag
Facciamo alcune modifiche a questa area. Per farlo, aggiungi quanto segue al tuo file common.scss.
.navigation-container {
.select-kit.combo-box {
.select-kit-header {
border-radius: 0.9em;
background-color: var(--header_background);
}
}
}
Qui prendiamo di mira .select-kit-header per dare loro ciascuno un border-radius identico, nonché un colore di sfondo più chiaro.
Cliccando su uno di questi, si apre un menu a discesa.
Attualmente, ha anche angoli spigolosi, quindi aggiungiamo alcuni stili per arrotondarli e cambiare il colore di sfondo per essere lo stesso dell’intestazione.
.navigation-container {
.select-kit.combo-box {
// ...codice precedente
&.category-drop,
&.tag-drop {
.select-kit-body {
border-radius: 0.9em;
background-color: var(--header_background);
.select-kit-collection {
background-color: var(--header_background);
border-top-left-radius: 0px;
border-top-right-radius: 0px;
}
}
}
}
}
Questo si traduce nel seguente aspetto…
Se guardi da vicino, puoi vedere che le nostre modifiche hanno lasciato visibile un piccolo bordo in alto a destra dell’area di ricerca.
Correggiamolo guardando nell’ispettore del nostro browser. Questo è sempre uno strumento super utile per imparare quali classi/ID dobbiamo prendere di mira per applicare correttamente gli stili.
Con il menu a discesa visibile, fai clic con il tasto destro sull’area di ricerca e ‘Ispetta’ l’elemento nel tuo browser.
Possiamo vedere che questo input si trova all’interno di un div con una classe select-kit-filter.
Se guardiamo le regole applicate a questo selettore, possiamo vedere che attualmente ha un bordo superiore e inferiore, nonché un po’ di padding applicato. Vogliamo cambiare solo la stilizzazione del bordo superiore.
Aggiungi il seguente codice annidato nello scss .select-kit-body di prima.
.select-kit.combo-box.category-drop,
.select-kit.combo-box.tag-drop {
.select-kit-body {
// ...codice precedente
.select-kit-filter {
border-top: 0px;
}
}
}
Con questo, il nostro codice per stilizzare il contenitore di navigazione dovrebbe sembrare così.
.navigation-container {
// Menu a discesa Categoria + Tag
.select-kit.combo-box {
.select-kit-header {
border-radius: 0.9em;
background-color: var(--header_background);
}
&.category-drop,
&.tag-drop {
.select-kit-body {
border-radius: 0.9em;
background-color: var(--header_background);
.select-kit-collection {
background-color: var(--header_background);
border-top-left-radius: 0px;
border-top-right-radius: 0px;
}
.select-kit-filter {
border-top: 0px;
}
}
}
}
}
Link di Navigazione
Aggiungiamo alcuni stili per far sì che questi link di navigazione sembrino simili a questo:
Usiamo di nuovo il nostro ispettore per scoprire cosa dovremmo prendere di mira qui.
Possiamo vedere che i nostri elementi di navigazione sono all’interno di un UL con una classe "nav nav-pills ..."
Tornando nel nostro file common.scss, sotto la sezione precedente, ma ancora annidato all’interno di navigation-container aggiungiamo quanto segue:
.nav-pills {
& > li a {
&.active {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--tertiary);
}
}
}
Questa modifica prenderà di mira solo i nostri link con la classe active che sono figli di nav-pills. Questa modifica dovrebbe far sembrare il nostro link attivo così:
Va bene, ma vorrei che il bordo inferiore si estendesse solo fino al testo. Per fare questo, sopra la riga &.active {, aggiungiamo quanto segue, che influenzerà tutti i link A all’interno dei tag <li> di navigazione.
// ...altro codice
.nav-pills {
& > li a {
padding: 0;
margin-right: 20px;
color: var(--tertiary-high);
border-bottom: 4px solid transparent;
&.active {
// ...più codice
}
}
}
Ora, dobbiamo stilizzare l’effetto “hover” per essere lo stesso dell’effetto “active”.
Sotto il nostro precedente &.active aggiungiamo
&:hover {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--primary);
}
Quindi tutto il nostro codice di navigazione dovrebbe ora sembrare così:
// Nav Pills
.nav-pills {
& > li a {
padding: 0;
margin-right: 20px;
color: var(--tertiary-high);
border-bottom: 4px solid transparent;
&.active {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--tertiary);
}
&:hover {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--primary);
}
}
}
Pulsanti
I pulsanti in Discourse vengono in molte forme e dimensioni. Puoi visualizzare una varietà di essi nella Guida agli stili nella sezione Pulsanti.
Vorrei cambiare la maggior parte dei pulsanti in questo tema per essere arrotondati con alcune stilizzazioni personalizzate. Questo cambierà il pulsante + Nuovo Argomento, nonché altri pulsanti in tutto il sito.
Nella parte inferiore del nostro file common.scss, aggiungiamo quanto segue:
.btn {
background-color: var(--header_background);
color: var(--primary);
border-radius: 1.2em;
border: 1px solid var(--primary-low-mid);
.d-icon {
color: var(--primary);
}
&:hover {
background-color: var(--quaternary-low);
color: var(--primary);
.d-icon {
color: var(--primary);
}
}
&.btn-default,
&.btn-primary {
padding: 10px 12px;
}
}
Questo farà sembrare i nostri pulsanti così:
Ora che i nostri pulsanti sono stilizzati, vorrei sottolineare qualcosa sulla stilizzazione dei pulsanti e perché è importante testare tutti i tuoi design.
Vai avanti e clicca su un Argomento nella tua anteprima del sito, poi premi il pulsante rispondi su una risposta all’argomento, o dal pulsante di risposta in fondo al flusso dell’argomento. Vedrai che la nostra stilizzazione dei pulsanti ha influenzato alcune cose che forse non avevamo in mente.
Non voglio che questi pulsanti di modifica del testo siano influenzati dalla mia precedente stilizzazione. Questo richiede un po’ di SASS/CSS più complesso, ma possiamo far sì che il nostro codice non influenzi questi pulsanti con :not(). 
Aggiungiamo questa riga di codice, davanti al nostro target .btn attuale. Questo dirà ai nostri stili di applicarsi solo ai pulsanti che non sono figli di .d-editor-button-bar.
:not(.d-editor-button-bar) > .btn
Ok, ha funzionato benissimo… ma aspetta! Ora c’è questo strano ribelle che fa di testa sua.
Ispettandolo nel browser, posso vedere che questo pulsante ha una classe .select-kit-header perché cliccando su questa ingranaggio, verranno mostrate più opzioni.
Ora che sappiamo che non vogliamo prendere di mira questo pulsante, aggiungiamo un po’ più di funzionalità :not() al nostro codice.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header)
Questo selezionerà tutti i pulsanti che NON sono figli di .d-editor-button-bar e non hanno la classe .single-select-header. So che è un po’ confuso, ma all’interno di Discourse ci sono molte parti in movimento, quindi a volte la stilizzazione deve essere molto specifica per influenzare correttamente gli elementi.
Ho anche notato che la nostra attuale stilizzazione influenza in modo goffo il pulsante di chiusura della modale. Cliccando su qualsiasi cosa che apra una modale potresti vederlo, o ancora più facile, possiamo navigare alla sezione modali della Guida agli stili.
Per correggere questo, aggiungerò un altro target al nostro codice.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close)
Passiamo oltre…
Vedo un altro pulsante che non sembra essere stato influenzato dal nostro codice. È il pulsante Monitoraggio situato in fondo a un flusso di post dell’argomento.
Aggiungerò la seguente riga, dopo una virgola, al nostro codice .btn attuale.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close),
.topic-notifications-button > .select-kit > .btn
Questo prenderà di mira correttamente il pulsante che appare in questa sezione e, per ora, abbiamo finito con la stilizzazione della parte superiore del nostro forum.
Dove andare da qui
Questa guida era destinata a sfiorare la superficie di come puoi personalizzare il tuo tema per Discourse. Spero che ora tu abbia una maggiore comprensione di come prendere di mira aree dell’app per le tue personalizzazioni.
Ricorda Molte cose possono essere personalizzate usando solo SCSS. Se vuoi approfondire ulteriormente lo sviluppo, ti consiglio di leggere gli articoli collegati in cima a questo post.
Sentiti libero di fare qualsiasi domanda e sarò lieto di aiutarti o indirizzarti nella direzione giusta.
Questo documento è versionato - suggerisci modifiche su github.