L'obiettivo
A meno che non si abbia l'ufficio su Venere, dove un giorno dura 5.832 ore, chiunque debba sviluppare un sito web oggi sa che dovrà fare uso di risorse esterne, siano esse proprie o di terze parti.
Certo non se ne può abusare, pena il degrado delle performance del sito web, ma volente o nolente, qualche script Javascript per la comunicazione asincrona oppure un foglio di stile CSS che arricchisca l'esperienza utente, dovremo pur usarlo... o no?
In questo articolo faremo un esempio concreto e reale, riguardante proprio il sito di HTML Crusco.
Il sito è stato progettato nativamente su Joomla 5 partendo dal template di default Cassiopeia, leggerissimo, accessibile e senza troppi fronzoli, proprio come piace a me. Una perfetta tela bianca sulla quale disegnare.
L'obiettivo è utilizzare Animate.css, una libreria cross-browser di animazioni CSS.
Il problema
Embè, dove sta il problema? Apri il file del template e ci schiaffi il link alla libreria... che ce vo'? Ce metto due minuti! ~ Il cuggino di turno
Il cuggino "smanettone" di turno ti fa la modifica in due minuti, non c'è nessun problema!
In realtà il problema c'è, ed è anche bello grosso: le modifiche apportate direttamente ai file del template hanno vita breve, perché saranno sovrascritte al primo aggiornamento.
Sicuramente Cuggini & Co. sarebbero capaci di rifare la modifica a ogni aggiornamento (avranno mica l'ufficio su Venere?) ma tu, che sei abituato a ottimizzare i tempi e vuoi lavorare in maniera professionale, sappi che da Joomla 4.1 sono state implementate delle soluzioni sia per evitare la sovrascrittura delle modifiche durante gli aggiornamenti, sia per caricare librerie esterne rispettando il pattern architetturale di Joomla.
Vediamole insieme.
I child template
Il child template (d'ora in poi child) eredita tutto dal template genitore.
Inizialmente è costituito solo dal file templateDetails.xml
Questa situazione iniziale ci indica che il child utilizza per default tutti i files del template da cui ha ereditato.
Se vogliamo fare una modifica a un file del template, è sufficiente copiare il file dal genitore al child ed effettuare la modifica sul file copiato.
Questo evita la sovrascrittura delle modifiche durante gli update.
Per creare il child dobbiamo accedere all'amministrazione di Joomla nell'area Sistema ⟶ Template sito, selezionare il template dal quale ereditare (nel nostro esempio Cassiopeia), premere il pulsante Crea template derivato, digitare il nome del nuovo template e confermare.
In Sistema ⟶ Template sito, selezionare il template genitore dal quale creare il child template.
Il pulsante "Crea template derivato"
Digitare il nome del child template e confermare.
Il child template appena creato, appare nella lista dei template del sito.
La struttura di cartelle file del child template.
Nell'ultima immagine potete notare la struttura di cartelle e file del child appena creato e la sola presenza del file templateDetails.xml
Nella cartella /media/templates/site/cassiopeia_htmlcrusco andranno tutti gli asset che dovremo utilizzare nel nostro child: css, images, js e scss.
Per il nostro obiettivo, la cartella che ci interessa è css.
In questa andremo a copiare il file animate.min.css che è la libreria per le animazioni.
Potete scaricarla dal repository su GitHub.
Se non volete avere la libreria in locale ma preferite usare il corrispettivo CDN, potete saltare il download e la copia.
Vuoi saperne di più sui child template?
Ti consigliamo di leggere Sweet child o' mine... A deep dive into Joomla Child Templates su Joomla! Magazine
I web asset
I web asset permettono a un sito web Joomla di caricare e usare librerie Javascript e CSS rispettando il pattern architetturale del framework Joomla.
Questo, oltre a fornire un incremento nella velocità di caricamento delle pagine e nella leggibilità e manutenzione del codice, ci consente di specificare e gestire facilmente le dipendenze richieste dalle librerie più complesse.
Nel nostro esempio faremo uso dei web asset per caricare e usare nel nostro child la libreria Animate.css.
La prima cosa che dobbiamo fare è registrare l'asset.
I template registrano i loro asset specificandoli nel file joomla.asset.json
Potete trovarlo nella cartella del template che state utilizzando, nel nostro caso /templates/cassiopeia/joomla.asset.json
Giusto?
No, perché noi abbiamo creato il nostro child per i motivi che ora sapete, e quindi dobbiamo utilizzare la cartella del child.
Lo so, il file in quella cartella non c'è, perché il child per default utilizza gli stessi asset del template genitore.
Se vogliamo utilizzare altri asset, dobbiamo creare il nostro file nella cartella del child.
Potete prendere quello del template genitore /templates/cassiopeia/joomla.asset.json, copiarlo nel child /templates/cassiopeia_htmlcrusco/ e pulirlo da tutti gli asset presenti.
Finita la pulizia dovreste avere qualcosa di questo tipo:
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "cassiopeia",
"version": "4.0.0",
"description": "This file contains details of the assets used by Cassiopeia HTML Crusco.",
"license": "GPL-2.0-or-later",
"assets": []
}
Ora aggiungiamo la definizione per il nostro asset:
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "cassiopeia",
"version": "4.0.0",
"description": "This file contains details of the assets used by Cassiopeia HTML Crusco.",
"license": "GPL-2.0-or-later",
"assets": [
{
"name": "animate",
"type": "style",
"uri": "animate.min.css"
}
]
}
Dove name è l'identificativo della libreria, che utilizzeremo tra poco.
type è il tipo di asset, nel nostro caso "style".
uri è l'indirizzo dove trovare il file della libreria:animate.min.css se avete copiato la libreria in locale;https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.cs se preferite usare il CDN.
Con questa operazione il nostro asset viene registrato nel WebAssetRegistry, ma non ancora allegato alle pagine durante il loro rendering.
Per fare questo dobbiamo usare l'asset, cioè comunicare al WebAssetManager di includerlo nelle pagine quando queste vengono caricate.
Possiamo farlo nel file index.php del template: lo copiamo dal template genitore cassiopeia /templates/cassiopeia/index.php al nostro child cassiopeia_htmlcrusco /templates/cassiopeia_htmlcrusco/
Ora possiamo modificarlo aggiungendo l'uso del nostro asset a quelli già presenti.
Per identificare il nostro asset utilizziamo il nome "animate", che abbiamo definito prima nel file joomla.asset.json:
$wa->usePreset('template.cassiopeia.' . ($this->direction === 'rtl' ? 'rtl' : 'ltr'))
->useStyle('template.active.language')
->registerAndUseStyle($assetColorName, 'global/' . $paramsColorName . '.css')
->useStyle('template.user')
->useScript('template.user')
->useStyle('animate')
->addInlineStyle(":root {
--hue: 214;
--template-bg-light: #f0f4fb;
--template-text-dark: #495057;
--template-text-light: #ffffff;
--template-link-color: var(--link-color);
--template-special-color: #001B4C;
$fontStyles
}");
Nel codice sopra, $wa è l'istanza del WebAssetManager, presente in tutti i template progettati per Joomla 4 e Joomla 5.
Se per qualche ragione non dovesse essere presente, potete crearla voi con $wa = $this->getWebAssetManager(); e poi utilizzare l'asset come già mostrato prima:$wa->useStyle('animate');
Conclusioni
In questo articolo abbiamo imparato che su Venere le giornate lavorative non finiscono mai, che i child template sono una manna dal cielo per chi deve modificare i file di template e che, grazie ai web asset, esiste un modo pulito e professionale di aggiungere librerie Javascript e CSS al nostro (child) template preferito!
Ci tengo a precisare che con il mio esempio abbiamo solo sfiorato le potenzialità dei web asset.
Magari riprenderò il discorso con un eventuale prossimo articolo, chi lo sa...
Per chi volesse approfondire il discorso sui web asset e sul loro utilizzo per altri scopi, quali ad esempio inline script, inline style e web component, può iniziare leggendo la documentazione ufficiale di Joomla!
Che il level up sia con voi!