Quindi sei interessato a progettare il tuo tema per Discourse? Sei arrivato al posto giusto 
Questa guida si concentrerà principalmente sugli aspetti SCSS/CSS del lavoro con i temi in Discourse. Se sei anche esperto in JS/EmberJs/Handlebars, puoi approfondire ulteriormente consultando questa guida.
Descriverò il mio metodo personale per la progettazione e la creazione di temi in Discourse. Come per la maggior parte delle cose, esistono MOLTE modalità per implementare i propri design. Mi piace utilizzare molto gli strumenti di ispezione quando creo temi e mostrerò alcune volte come lo faccio in questo post.
Configurazione per la creazione di temi
Si prega di leggere la Guida per principianti all’uso dei temi Discourse, nonché la Struttura dei temi… prima di continuare. Una conoscenza approfondita non è necessaria in questo momento, ma questi articoli ti daranno un po’ più di familiarità prima di iniziare.
Per lavorare al meglio con la creazione di temi in Discourse, suggerisco di configurare quanto segue per offrire a te stesso il processo di progettazione più rapido e snello. Questi passaggi ti permetteranno di vedere le tue modifiche man mano che le apporti, senza dover ‘salvare’ e aggiornare dal pannello di amministrazione del sito Discourse.
È assolutamente possibile lavorare con questa guida utilizzando la console di amministrazione (purché tu abbia accesso di livello amministratore a un forum Discourse.)
- Installa Discourse Theme CLI e leggi quel argomento per capire cosa può fare.
- Recupera 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 che appare, clicca su Genera chiave API e copia la chiave generata per te (la useremo tra un attimo)
Esecuzione di Discourse Theme CLI
Con Discourse Theme CLI installato e la tua chiave API pronta, apri il tuo editor di testo preferito o la finestra del terminale e cambia la directory di lavoro in quella in cui desideri impostare la cartella del tema.
Una volta lì, esegui il seguente comando discourse_theme new your_theme_name e compila le richieste come segue:
-
Come vuoi chiamare il tuo tema? Scegli il nome del tema
-
Vuoi iniziare a monitorare questo tema? Sì
-
Qual è l’URL radice del tuo sito Discourse?
https://discourse.theme-creator.io/ -
Vuoi che il nome di questo sito venga memorizzato in…? Sì
-
Qual è la tua chiave API? Inserisci la chiave API recuperata da Theme Creator
-
Vuoi che questa chiave API venga memorizzata…? 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 funziona correttamente, dovresti ora 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 tema, quindi nella parte inferiore dell’area delle informazioni, clicca su Anteprima
Il Theme CLI sta anche monitorando eventuali modifiche nella directory appena creata e salverà, oltre ad aggiornare il tema su theme-creator con ogni modifica.
Primi passi
Discourse Theme CLI ha creato una struttura di base per il tema all’interno della cartella con il nome specificato nel comando eseguito in precedenza. Vengono generati molti file che non useremo, quindi procederemo a eliminare 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 git; non sarà necessario per questa guida.
La tua directory del tema dovrebbe ora apparire così:
Vale la pena notare che gli stili aggiunti a questi file verranno resi nei rispettivi casi d’uso. Gli stili in common.scss verranno applicati sia a desktop che a mobile, mentre gli stili in desktop.scss verranno applicati solo alla navigazione desktop e quelli in mobile.scss solo alle visualizzazioni mobile.
Hello World (a colori)
Discourse utilizza SCSS per lo stile, quindi per utilizzare al meglio gli stili, potresti voler familiarizzare con SASS, ma se non lo fai, potrai comunque seguire questa guida.
Ok, ora arriviamo a ciò che tutti stavano aspettando… LA CREAZIONE DI TEMI!
Al momento, il nostro about.json non ha ancora definito alcuno schema di colori, quindi incolla il seguente codice in quella sezione e 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 in atto, poiché questo è lo schema di colori predefinito utilizzato quando non è presente alcuno schema.
Panoramica del tema
Per avere qualcosa da implementare effettivamente in questa guida, ti guiderò nella creazione di un tema semplice basato su questa tavolozza di colori.
Modifica del colore di sfondo + colore del testo principale
Facciamo qualcosa di molto semplice. Procederemo a modificare il valore "Secondary" del nostro schema di colori corrente. Cambiamolo in "secondary": "EEF4F7" (questo modifica 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 effettuate semplicemente modificando i colori nello schema dei 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 comprendere 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 | Collegamenti, alcuni pulsanti, notifiche e colore di accento |
| quaternary | Collegamenti 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 | Utilizzato per indicare che un’azione è andata a buon fine |
| love | Il colore del pulsante Mi piace |
Ognuna di queste variabili è disponibile per l’uso all’interno dei nostri file SCSS come segue.
body {
background-color: var(--primary);
}
Sono state create anche altre versioni di ciascun colore per il nostro utilizzo. Cose come var(--primary-medium) o var(--primary-very-low) possono essere utilizzate per ottenere diverse tonalità dello stesso colore.
Cambiamo gli altri colori nel nostro schema di colori “Default” per abbinarlo 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 Style Guide mentre visualizzi l’anteprima del tuo tema su Theme Creator, quindi clicchi su Colori nel menu a sinistra.
La Styleguide è una sezione molto utile da consultare quando crei un tema personalizzato. Ogni Atom ti mostrerà come certi elementi di Discourse appariranno con i tuoi stili applicati.
Approfondire
Con la sezione precedente alle nostre spalle, penso che sia il momento di approfondire cosa può essere fatto in Discourse utilizzando solo SCSS. (Indizio: MOLTO!)
Stile dell’intestazione
Noterai che le nostre precedenti modifiche allo schema di colori hanno lasciato qualcosa a desiderare per quanto riguarda la nostra intestazione. Le icone sono appena visibili!
L’intestazione di Discourse include un contenitore (con un colore di sfondo) per ospitare il logo del sito, nonché le icone di navigazione a destra. Tutti questi possono essere personalizzati.
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 predefinita sulla scatola dell’intestazione, le darà un po’ più di altezza e stabilirà un bordo inferiore per darci una 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 sta andando bene, ma un occhio attento noterà che l’aumentata altezza dell’intestazione ci ha lasciato 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 sono i menu a tendina per filtro categoria/tag, seguiti dai collegamenti di navigazione, terminando con il pulsante Nuovo Argomento.
Menu a tendina Categoria / Tag
Facciamo alcune modifiche a quest’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 a ciascuno un raggio di bordo identico, nonché un colore di sfondo più chiaro.
Cliccando su uno di questi, si apre un menu a tendina.
Attualmente, ha anche angoli duri, quindi aggiungiamo alcuni stili per arrotondarli e cambiare il colore di sfondo in modo che sia 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 risulta nel seguente aspetto…
Se guardi attentamente, puoi vedere che le nostre modifiche hanno lasciato visibile un piccolo bordo nella parte superiore destra dell’area di ricerca.
Risolvi questo guardando nell’ispettore del tuo 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 tendina visibile, clicca con il tasto destro sull’area di ricerca e ‘Ispeziona’ l’elemento nel tuo browser.
Possiamo vedere che questo input si trova all’interno di un div con una classe di select-kit-filter.
Se guardiamo le regole applicate a questo selettore, possiamo vedere che attualmente ha un bordo superiore e inferiore, oltre a un po’ di padding applicato. Vogliamo cambiare solo lo stile 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 lo stile del contenitore di navigazione dovrebbe apparire così.
.navigation-container {
// Categoria + Tag Drop Down
.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;
}
}
}
}
}
Collegamenti di navigazione
Aggiungiamo alcuni stili per far apparire questi collegamenti di navigazione 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 si trovano all’interno di un UL con una classe di "nav nav-pills ..."
Tornando al 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 collegamenti con una classe attiva che sono figli di nav-pills. Questa modifica dovrebbe far apparire il nostro collegamento attivo così:
Questo 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 collegamenti 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 {
// ...altro codice
}
}
}
Ora, dobbiamo stilizzare l’effetto “hover” in modo che sia 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 apparire 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 hanno molte forme e dimensioni. Puoi vedere una selezione di essi nella Style Guide nella sezione Pulsanti.
Vorrei cambiare la maggior parte dei pulsanti in questo tema per renderli arrotondati con alcune personalizzazioni. Questo cambierà il pulsante + Nuovo Argomento, nonché altri pulsanti in tutto il sito.
Alla fine 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à apparire i nostri pulsanti così:
Ora che i nostri pulsanti sono stilizzati, vorrei evidenziare qualcosa riguardo allo stile dei pulsanti e perché è importante testare tutti i tuoi design.
Clicca su un Argomento nella tua anteprima del sito, quindi premi il pulsante rispondi su una risposta all’argomento, o dal pulsante di risposta in fondo al flusso dell’argomento. Vedrai che il nostro stile dei pulsanti ha influenzato alcune cose che potremmo non aver avuto in mente.
Non voglio che questi pulsanti di modifica del testo siano influenzati dal mio precedente stile. Questo richiede un po’ di SASS/CSS più complesso, ma possiamo far sì che il nostro codice :not() non influenzi questi pulsanti. 
Aggiungiamo questa riga di codice, davanti al nostro attuale target .btn. 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 molto bene… ma aspetta! Ora c’è questo strano ribelle che fa le cose a modo suo.
Ispezionandolo nel browser, vedo che questo pulsante ha una classe di .select-kit-header perché, cliccando su questa ingranaggio, appariranno più opzioni.
Ora che sappiamo che NON vogliamo prendere di mira questo pulsante, aggiungiamo più 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 lo stile deve essere molto specifico per influenzare correttamente gli elementi.
Ho anche notato che il nostro stile attuale influenza in modo goffo il pulsante di chiusura della finestra modale. Cliccando su qualsiasi cosa che apra una finestra modale, potresti vedere questo, o anche più facilmente, possiamo navigare alla sezione Modale della Style Guide.
Per risolvere questo problema, aggiungerò un altro target al nostro codice.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close)
Procediamo…
Vedo un altro pulsante che non sembra essere stato influenzato dal nostro codice. È il pulsante Tracking situato in fondo al flusso di un post dell’argomento.
Aggiungerò la seguente riga, dopo una virgola, al nostro attuale codice .btn.
: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 di stilizzare la parte superiore del nostro forum.
Dove andare da qui
Questa guida era intesa a toccare superficialmente come puoi personalizzare il tuo tema per Discourse. Spero che tu abbia ora maggiore comprensione su come prendere di mira le aree dell’app per le tue personalizzazioni.
Ricorda MOLTE cose possono essere personalizzate utilizzando solo SCSS. Se desideri approfondire ulteriormente il tuo sviluppo, ti consiglio di leggere gli articoli collegati nella parte superiore di questo post.
Sentiti libero di fare domande e sarò lieto di provare ad aiutarti o indicarti la direzione giusta.
Questo documento è sotto controllo versione - suggerisci modifiche su github.