ℹ️ Il ruolo di questo file è duplice: in primis funge da documentazione per coloro che hanno creato sviluppato il sito ma hanno altresì scarsissima memoria. In secondo luogo vuole essere, anche e soprattutto, una sorta di guida per chi a prescindere dalle proprie competenze vorrebbe capirci qualcosa ed è curioso di cosa tiene in piedi il “frontend” del sito del Mirandola 2. Per questa duplice natura - e nell'ottica del principio scout del Trapasso Nozioni - si è cercato di usare un linguaggio chiaro e spiegare cose che per alcuni possono essere ovvie pur sapendo che d'altra parte per forza di cose questo non potrà bastare a capire tutto tutto. Sicuramente è meglio di niente; se vorrete leggerlo, buona caccia!
Il frontend è la parte di un sito web che è visibile dall'utente. Nel nostro caso è stata costruita usando Nuxt and Tailwind. Quest'ultimo è un framework CSS utilizzato insieme alla libreria Daisy UI per semplificare la parte di design del sito. Nuxt è invece un framework JavaScript che permette di costruite siti statici utilizzando Vue.js.
I siti statici, come quelli creati con framework come Nuxt, sono siti web precompilati in pagine HTML, CSS e JavaScript che non richiedono un server attivo per generare i contenuti al momento della richiesta dell’utente. A differenza dei siti tradizionali dinamici, che generano le pagine in tempo reale, i siti statici vengono generati in anticipo, permettendo una distribuzione più semplice e una performance più elevata.
Di seguito si può vedere l'architettura del sito.
In questa repository è presente e qui documentato il frontend, mentre il Middleware 📤 si può trovare qui.
Per far partire il local server:
npm install
npm run devPushando le modifiche su Github, il sito verrà automaticamente aggiornato.
Premessa: Questo paragrafo vuole essere d'aiuto per chiunque voglia modificare il sito senza avere particolari rudimenti su Nuxt o Vue. Logicamente non si è potuto inserire tutto lo scibile sull'argomento; perciò si rimanda il lettore alla documentazione ufficiale nel caso si volessero fare modifiche più profonde al sito.
I contenuti del sito sono renderizzati a partire da file presenti in due fonti:
- la cartella
contentospita le pagine in formato Markdown. Le pagine i cui file iniziano per _ o per . sono pagine particolari con funzioni specifiche. - la cartella
pagesospita tutte le pagine in formato Vue oltre che il template standard standard delle pagine al punto precedente.
I contenuti nella carta "In primo piano" presente nella home sono invece modificabili dal file content/_home.md.
I singoli articoli della sezioni blog sono anch'esse pagine Markdown, presenti nella cartella content/blog
Essendo il Markdown un linguaggio estremamente comodo, si è preferito usare il più possibile la cartella content, lasciando nei file Vue solamente cioò che era troppo complesso per essere scritto in Markdown. Questi ultimi file vanno esclusi dal contenuto generato dinamicamente modificando il file di configurazione (documentazione) (solo per le nuove pagine Vue create).
Si noti infine che le immagini si trovano nella cartella public. Si è cercato di mettere qui solo le immagini principali, compresse il più possibile, tenendo sempre a mente il fatto che la maggioranza di esse nonché i file esterni, è meglio non caricarli su GitHub (sebbene non ci sia un hard-limit allo spazio di archiviazione, Github nasce per il codice) favorendo altri cloud (Google Photos, One Drive, Google Drive, Cloudlfare Files etc.). Quando vengono linkate le immagini interne nella varie pagine, il percorso deve essere relativo al contenuto della cartella /public, non a /.
Le pagine in Markdown nella cartella content ammettono la sintassi MDC, ovvero un markdown "potenziato" che sfrutta componenti a blocchi.
I blocchi possono essere utilizzati usando la seguente sintassi (Più info nella documentazione ufficiale).
::<titolo>{<parametri>}
<contentuto>
::I componenti si trovano nella cartella /components/content e attualmente sono i seguenti.
Due componenti da usare insieme, permettono di visualizzare tante carte testuali in modalità galleria. Come si può vedere nell'esempio, il blocco cards contiene le single card.
::cards
:::card{title="La Legge" color="lc" big}
Il lupetto pensa agli altri come a se stesso.
Il lupetto vive con gioia e lealtà insieme al branco.
:::
:::card{title="Il Motto" color="lc"}
Del Nostro Meglio
:::
::I parametri di card sono:
title: stringa, opzionale, sarà visualizzato come il titolo della cartacolor: stringa, opzionale (lg|eg|rs|cc), rappresenta il colore della carta. Altrimenti sarà di colore neutro.big: boolean, opzionale. Se vero, la carta sarà grande il doppio su certi schermi
:tableOfContentsFa apparire un indice della pagina nella parte destra della pagina sui dispositivi non mobili, al centro altrimenti. Per far sì che sia a larghezza intera su tutti i dispositivi, è neccessario il parametro opzionale notaside sia true.
:Fig{src='/img/misc/img.jpg' desc='La descrizione dell'immagine' float=1 alt='Immagine di esempio'}Mostra un'immagine formattata usando la grafica del sito. I parametri sono:
srcstring | Object, mandatory: source dell'immagine, interna in public o esternadescstring | Object, optional: descrizione che appare sotto all'immaginealtstring, optional: testo alternativo per migliorare l'accessibilità (cos'è?)floatnumber, optional: regola come apparirà l'immagine:0la farà apparire centrata e a larghezza ampia,1(default) la farà diventare float a sinistra,2float a destra.
Le proprietà src e desc possono anche avere più immagini, in modo da creare un carosello. La sintassi deve essere la seguente:
:Fig{:src='["/path0.jpg", "/path1.jpg"]' :desc='["Caption Img 0", "Caption Img 1"]' }::quoted
...e quando Hathi, l'elefante selvaggio che vive cento anni e più, vide affiorare una lunga e sottile cresta di Roccia Azzurrina, proprio nel bel mezzo della corrente, capì che quella era la roccia della pace ed immediatamente alzò la proboscide e proclamò la "tregua dell'acqua".
::Il blocco quoted permette di creare una citazione.
:staff{staff='L' coca}Parametri:
staff: stringa, indica quale staff mostrare [L | C | E | G | N | CF | CC | CJ | *] (rispettivamente, lupetti, coccinelle, esploratori, guide, noviziato, clan-fuoco, coca (altri incarichi), capi gruppo, tutti).coca: booleano, opzionale. Se vero, mostra solo i capi in CoCa.
Il blocco mostra tutti i capi di una certa staff. I capi sono inseriti in formato .csv nel file /content/_capi.csv rispettando la formattazione presentata in calce.
Mostra il testo di un link all'interno di un bottone e con un'icona scelta fra queste.
::Lnk{href="https://example.com" icon="checklist"}
Testo del Bottone
::Nei blog post come nelle pagine markdown, esiste una sezione chiamata front matter, utile a inserire proprietà e metadati. (documentazione ufficiale).
Per quanto riguarda le pagine, il front-matter supportato è il seguente.
---
title: "Titolo della pagina"
image: path/img.jpg
overlap_hero: false #lasciare falso a meno di non voler sovrapporre leggermente il contenuto all'immagine di hero.
---Per i singoli post presenti nella cartella content/blog, invece:
---
title: "Titolo"
img: 'path/cover.jpg'
category: 'cc' # lc | eg | rs | cc
date: 2023-10-15
---Il menu è gestito nel file app.vue, e in particolare nel dizionario presente nello script setup.
Esempio:
{
"Home": "/",
"Chi Siamo": {
"L'Associazione": "/associazione",
"Il Gruppo": "/gruppo",
}
}I capi sono inseriti in formato .csv nel file /content/_capi.csv rispettando la formattazione presentata nell'esempio seguente.
nome,nomeCaccia,ruolo,staff,coca,desc,img,order
Baden Powell,Impeesa,Fondatore dello Scoutismo|Capo Reparto,CC|E,1,Impeesa ovvero l'animale che si sposta furtivamente di notte,bp.jpg,0
- Da notare come il
nomeCacciaindichi non il nome Totem ma bensì il personaggio interpretato dai capi in LC. Viene mostrato al posto del nome vero se e solo sestaff == {L, C}ecoca==true. - Se nel campo
ruoloè presente una|, il contenuto antecedente verrà mostrato quandostaff == *, il contenuto successivo negli altri casi. - Separare i doppi incarichi con un
|nel campostaff. I valori possibili sono gli stessi riportati in precedenza. - Il campo
imgè il percorso relativo della foto del capo che si deve trovare nella cartella/public/img/staff(se il percorso della foto è/public/img/staff/capo.jpg, il campo deve esserecapo.jpg). - Il campo
orderè facoltativo. Se presente, in tutte le visualizzazione ``staff != *`, sovrascrive l'ordine delle righe, andando a posizionare i capi della singola staff secondo l'ordine crescente. Utile solo in caso di doppi servizi.
Gestire le immagini è complicato sia per una questione di privacy sia per una questione di storage. L'attuale soluzione prevede che tutte le immagini di archivio siano caricate esternamente, in particolare sul OneDrive fornito al gruppo dall'associazione; tranne per ciò che riguarda le poche immagini presenti sul sito come immagini di copertina o simili, che per una questione di latenza si è preferito procedere diversamente. Queste caricate su GitHub. Tuttavia per evitare che queste finiscano nella git commit history (da evitare sia per motivi di best practice informatiche sia per motivi interni nostri), sono caricate come oggetti di Git LFS.
git lfs track public/img/**/*.jpg
git add ...
git commit -m "Added images"
git push origin mainIl sito è ospitato gratuitamente su Netlify.