Creare e sviluppare un tema

Un tema è una cartella di file di testo — template, sezioni, snippet, CSS — che Riseact pubblica come versioni immutabili. Le organizzazioni installano una versione e decidono quando passare a una più recente.

Serve un account Partner. Se non l'hai ancora, segui la guida iniziale.

Installare la CLI

Scarica la versione per il tuo sistema operativo dalla pagina delle release, estrai l'archivio e metti l'eseguibile in una cartella del tuo PATH.

Poi autenticati:

riseact auth login

Partire da un tema esistente

riseact theme init

Clona un tema di partenza e ti chiede i dati del manifest.json: nome, identificativo, versione, autore. Crea una cartella con il nome dell'identificativo che hai scelto: è lì che lavorerai. Cosa contengono le sottocartelle è nella struttura di un tema.

L'identificativo è definitivo

È la chiave con cui Riseact riconosce che una nuova versione appartiene allo stesso tema, e non si può cambiare. Il comando ti avverte se è già occupato da qualcun altro.

Se il tema esiste già e vuoi ripartire da una versione pubblicata:

riseact theme pull -p ./cartella-vuota

Ti chiede quale tuo tema e quale versione, e scarica i file di quella versione.

Sviluppare con l'anteprima dal vivo

cd il-tuo-tema
riseact theme dev

Alla prima esecuzione il comando ti chiede su quale organizzazione lavorare e installa lì il tema. Poi stampa due indirizzi: l'anteprima pubblica e l'editor visuale nel pannello.

Il tema non viene pubblicato: resta nella libreria dell'organizzazione, e il sito che i donatori vedono non cambia. Alla chiusura con Ctrl+C non viene cancellato niente — la prossima volta che lanci theme dev nella stessa cartella riprendi da dove eri.

Serve un'organizzazione su cui lavorare. Se non ne hai, creane una di sviluppo dal tuo profilo partner: è gratuita e non tocca dati reali.

La sincronizzazione va nei due sensi

Finché theme dev è in esecuzione la cartella e il tema restano allineati in entrambe le direzioni:

• salvi un file → viene caricato subito, ti basta ricaricare la pagina di anteprima
• modifichi qualcosa dall'editor visuale e salvi → il file corrispondente viene aggiornato nella tua cartella

Il secondo verso è quello utile davvero. I colori, i testi e la composizione delle pagine si scelgono meglio nell'editor visuale che a mano in un JSON: componi la homepage trascinando le sezioni, e templates/homepage.json nella tua cartella si aggiorna da sé. Quel file è poi quello che finisce nella release e definisce come si presenta il tema appena installato.

All'avvio il comando riallinea le due parti prima di mettersi in ascolto, quindi ritrovi anche le modifiche fatte dall'editor visuale mentre non stavi lavorando.

note

In caso di conflitto vince la modifica più recente. Se lo stesso file è cambiato da entrambe le parti mentre theme dev era spento, viene tenuta la copia sul server e il nome del file viene stampato a schermo.

Il comando salva lo stato della sessione in .riseact/dev.json dentro la cartella del tema: quale tema e quale organizzazione stai usando. Aggiungi .riseact/ al tuo .gitignore e non spedirlo a nessuno — cancellandolo, il prossimo theme dev ricomincia da un tema nuovo.

Cancellare file

La rimozione di un file viene propagata solo mentre theme dev è in esecuzione. Se cancelli una sezione a comando spento, al riavvio viene riscaricata dal server: per il comando un file sparito dal disco e un file nuovo sul server sono indistinguibili, e riscaricarlo è l'unico errore rimediabile dei due.

Escludere file dal caricamento

Un tema contiene spesso strumenti di build che non devono finire su Riseact. Elencali in un file .riseactignore nella radice del tema, con la stessa sintassi di .gitignore:

node_modules
package.json
package-lock.json
yarn.lock
tailwind.config.js
riseact.yml

Le regole valgono sia per il pacchetto sia per la sincronizzazione durante theme dev. .git, node_modules e .riseact sono esclusi comunque, anche senza il file.

danger

Includi sempre riseact.yml: è il file dove la CLI salva le tue credenziali, e senza questa riga verrebbe caricato come file del tema.

L'output compilato invece serve. Se usi Tailwind, assets/main.css va caricato: è il file che il sito legge davvero.

Pubblicare una versione

Quando il tema è pronto, alza la versione nel manifest.json e pubblica:

riseact theme release

Il comando apre il tuo editor per scrivere il changelog della versione. Lo leggeranno le organizzazioni prima di decidere se aggiornare, quindi scrivilo per loro: cosa cambia, non come.

Se preferisci non usare la CLI, riseact theme package prepara lo zip che puoi caricare dall'area Partner: le regole di validazione sono le stesse.

L'editor viene scelto in questo ordine: $VISUAL, $EDITOR, la chiave editor nel file di configurazione, git config core.editor, e infine nano. Salvare un messaggio vuoto annulla la pubblicazione.

Regole di versionamento

La versione va scritta come MAJOR.MINOR.PATCH — per esempio 1.4.0 — e ogni pubblicazione deve avere una versione superiore alla precedente. Non sono ammessi suffissi come 1.4.0-beta.

Una pubblicazione viene rifiutata quando:

• la versione è già stata pubblicata per quel tema
• la versione è inferiore all'ultima pubblicata
• il changelog è vuoto
• un file non compila, o il blocco {% schema %} di una sezione non è JSON valido

Nel caso di errori nei file, la risposta elenca tutti i problemi trovati con il percorso di ciascuno, e nessuna versione viene creata. È il controllo che ti evita di pubblicare un tema che si romperebbe sui siti dei clienti.

Le versioni sono immutabili

Una volta pubblicata, una versione non si modifica più. Per correggere qualcosa si pubblica una versione nuova. Questo è ciò che permette a un'organizzazione di sapere esattamente quali file ha, e a noi di dirle cosa cambierebbe aggiornando.

Cosa vede l'organizzazione

Nel pannello, alla voce Temi, ogni tema installato ha un pulsante Versione tema. Da lì l'organizzazione può:

• scegliere una versione dall'elenco e leggerne il changelog
• vedere quali file, se ne ha modificati, verrebbero sovrascritti aggiornando
• aggiornare il tema, oppure installare quella versione come tema separato

L'aggiornamento va solo in avanti. Per tornare a una versione precedente si installa come tema nuovo, senza toccare il sito pubblicato.

Cosa l'aggiornamento conserva

Questa distinzione è la cosa più importante da capire quando si progetta un tema.

file	all'aggiornamento
sections/, snippets/, layout/, assets/, config/settings_schema.json, templates/**/*.html	sostituiti dalla nuova versione
config/settings_data.json	conservato; le impostazioni nuove vengono aggiunte con il loro valore predefinito
templates/**/*.json	conservati; i template nuovi della versione vengono aggiunti

In pratica: il codice del tema è tuo, le scelte fatte dall'organizzazione sono sue. Se modifichi l'HTML di una sezione, la modifica arriva a tutti. Se aggiungi una sezione alla homepage del tuo templates/homepage.json, quella non arriva a chi ha già il tema installato — la composizione della pagina appartiene all'organizzazione. Arriverà solo a chi lo installerà da zero.

caution

Se rinomini o rimuovi una sezione, i template delle organizzazioni che la usano continueranno a referenziarla e la pagina mostrerà un errore al posto della sezione. Mantieni i nomi delle sezioni stabili, oppure lasciale in piedi anche quando ne aggiungi una nuova.

Distribuire il tema

Le versioni che pubblichi arrivano subito alle organizzazioni che hanno già il tuo tema. Per farlo installare a chi non lo ha, dalla pagina del tema nell'area Partner scegli:

• Le mie organizzazioni — tutte quelle che amministri lo trovano nel loro store dei temi. Nessuna approvazione: sono clienti tuoi.
• Invia per l'approvazione — per comparire nello store dei temi, visibile a tutte le organizzazioni Riseact. Lo esaminiamo noi e ti rispondiamo per email.

I dettagli sono in Area partner → Temi.

Riferimento per i template

Come si scrivono i file del tema — variabili disponibili, oggetti, tag, filtri, schema delle sezioni — è documentato nelle pagine di questa sezione, a partire dalla panoramica del motore dei temi.