Come creare un child template Joomla installabile

In pratica: puoi cambiare font, colori, stili e layout, e le tue modifiche resteranno intatte anche quando il template padre viene aggiornato.

In questa guida utilizzeremo Cassiopeia, il template predefinito di Joomla 5 e 6, come punto di partenza. È la scelta ideale perché:

• È mantenuto attivamente dal team ufficiale di Joomla
• È costruito su Bootstrap 5, un framework CSS moderno e affidabile
• Segue gli standard di accessibilità e performance
• Ha una struttura pulita e ben documentata

Al termine di questa guida avremmo un child template funzionante chiamato "cassiopeia_mtfonts", con il supporto per i font locali Titillium Web.

Prerequisiti

Prima di iniziare, dobbiamo avere a disposizione:

1. Accesso all'amministrazione Joomla con profilo Super User
2. Il pacchetto di installazione di Joomla
3. I file del font Titillium Web in formato .woff2

Struttura delle cartelle

Prima di tutto dobbiamo creare sul nostro computer la struttura di file e cartelle che formerà il nostro child template.

Crea questa struttura di directory:

    cassiopeia_mtfonts/
    ├── media/
    │   ├── css/
    │   │   ├── user.css
    │   │   └── fonts-local_titillium.css
    │   ├── fonts/
    │   │   └── Titillium_Web/
    │   └── images/
    ├── language/
    │   └── it-IT/
    │       ├── tpl_cassiopeia_mtfonts.ini
    │       └── tpl_cassiopeia_mtfonts.sys.ini
    └── templateDetails.xml

Cosa contiene ciascuna cartella e perché:

cassiopeia_mtfonts/
  È la cartella radice del template. Il nome deve seguire obbligatoriamente il formato "cassiopeia_[nomedeltuotema]". Joomla riconosce il prefisso "cassiopeia_" per sapere che si tratta di un child del template Cassiopeia.

media/css/
  Contiene i fogli di stile CSS. Abbiamo scelto di dividere le istruzioni in due file separati: "user.css" per le personalizzazioni generali (colori, spaziature, layout) e "fonts-local_titillium.css" dedicato esclusivamente alla dichiarazione dei font. Questa separazione non è obbligatoria, ma rende il codice più ordinato e facile da mantenere nel tempo.

media/fonts/Titillium_Web/
  Qui andranno i file del font (.woff2) che scaricheremo nel passo successivo.

media/images/
  Cartella per le immagini di anteprima del template (le vedremo nell'apposita sezione).

language/it-IT/
  Contiene i file di traduzione del template. I due file .ini servono per definire il nome e la descrizione del tema che appariranno nell'area di amministrazione.

templateDetails.xml
  Il file più importante: dice a Joomla tutto quello che deve sapere sul template (nome, autore, file inclusi, parametri). Lo configureremo in dettaglio.

Preparare il font locale

Invece di caricare i font da Google Fonts (che richiede una connessione esterna e può sollevare questioni di privacy legate al GDPR), utilizzeremo i font in hosting locale, ovvero caricati direttamente sul nostro server.

Come scaricare i file del font:

1. Andiamo sul sito: https://gwfh.mranftl.com/fonts (google-webfonts-helper, uno strumento gratuito per scaricare font di Google in formato locale)

2. Nella barra di ricerca a sinistra, digitare "Titillium". Il font apparirà subito nell'elenco.

3. Configurare il pacchetto da scaricare seguendo queste impostazioni:

   SEZIONE "Select charsets":
   Lasciare selezionato il charset predefinito (latin).

  SEZIONE "Select styles":
Selezionare i seguenti stili:   

• regular (testo normale)
• italic (corsivo)
• 700 (grassetto)
• 700italic (grassetto corsivo)

Questi quattro stili coprono la maggior parte delle situazioni tipografiche di un sito web.

   SEZIONE "Copy CSS":
   - Selezionare l'opzione "Modern Browsers"
   - Nel campo "Customize folder prefix (optional)" inserisiamo questo percorso:
     ../fonts/Titillium_Web/
     (indica a Joomla dove trovare i file del font relativamente al file CSS)
   - Selezionare tutto il codice CSS generato e incollarlo nel file "fonts-local_titillium.css"

    - Aggiungere alla fine del file anche questo blocco:

       :root {
            --cassiopeia-font-family-body: "Titillium Web", sans-serif;
            --cassiopeia-font-family-headings: "Titillium Web", sans-serif;
            --cassiopeia-font-weight-headings: 700;
            --cassiopeia-font-weight-normal: 400;
        }

   SEZIONE "Download files":
   Cliccare sull'archivio .zip per scaricarlo.

4. Decomprimere l'archivio e copiare tutti i file .woff2 nella cartella:
   cassiopeia_mtfonts/media/fonts/Titillium_Web/

Configurare templateDetails.xml

Il file templateDetails.xml contiene i dati necessari a Joomla! per gestire e visualizzare il template.
Questi includono i metadati utilizzati per fornire informazioni sul template, i percorsi delle cartelle e dei file, le posizioni dei moduli del template e le opzioni di configurazione selezionabili dall'utente.

Per il nostro child template, partiremo dal templateDetails.xml originale di Cassiopeia. Lo troviamo decomprimendo il pacchetto di installazione di Joomla e navigando in:
installation/templates/cassiopeia/templateDetails.xml

Facciamo copia di tutto il contenuto di quel file nel nostro 'templateDetails.xml', poi apportiamo le seguenti modifiche.

--- MODIFICA 1: Metadata ---

Trovare il blocco:

  <name>cassiopeia</name>
    <version>1.0</version>
    <creationDate>2017-02</creationDate>
    <author>Joomla! Project</author>
    <authorEmail>Questo indirizzo email è protetto dagli spambots. È necessario abilitare JavaScript per vederlo.</authorEmail>
    <copyright>(C) 2017 Open Source Matters, Inc.</copyright>
    <description>TPL_CASSIOPEIA_XML_DESCRIPTION</description>
    <inheritable>1</inheritable>

E sostituirlo con:

  <name>CASSIOPEIA_MTFONTS</name>
    <version>1.0</version>
    <creationDate>Data</creationDate>
    <author>Autore</author>
    <authorEmail>Email</authorEmail>
    <copyright>(C) 2017 Open Source Matters, Inc.</copyright>
    <description>TPL_CASSIOPEIA_MTFONTS_XML_DESCRIPTION</description>
    <inheritable>0</inheritable>
    <parent>cassiopeia</parent>

Personalizzare i campi Data, Autore ed Email con i propri dati.

Cosa significano i campi più importanti:
- <name>: Il nome interno del template. Lo scriviamo in maiuscolo per convenzione.
- <description>: Il valore è una "chiave di traduzione" (come TPL_CASSIOPEIA_MTFONTS_XML_DESCRIPTION) che verrà risolta dai file di lingua che creeremo nel passo 4.
- <inheritable>0</inheritable>: Imposta il template come non ereditabile a sua volta (un child non può avere altri child).
- <parent>cassiopeia</parent>: Questo tag è FONDAMENTALE. Indica a Joomla che questo template è figlio di Cassiopeia, e quindi deve ereditarne tutte le funzionalità.

--- MODIFICA 2: Cartelle e file ---

Trovare il blocco:

   <files>
        <filename>component.php</filename>
        <filename>error.php</filename>
        <filename>index.php</filename>
        <filename>joomla.asset.json</filename>
        <filename>offline.php</filename>
        <filename>templateDetails.xml</filename>
        <folder>html</folder>
    </files>

E sostituirlo con:

   <files>
        <filename>templateDetails.xml</filename>
        <folder>html</folder>
        <folder>language</folder>
    </files>

Perché questa differenza? Il template padre (Cassiopeia) gestisce già tutti i file PHP principali (index.php, error.php, ecc.). Nel child template dobbiamo dichiarare solo i file che aggiungiamo o sovrascriviamo noi. In questo caso, solo il 'templateDetails.xml', una eventuale cartella 'html' per gli override, e la cartella 'language' per le traduzioni.

--- MODIFICA 3: File media (CSS, font, immagini) ---

Trovare il blocco:

   <media destination="templates/site/cassiopeia" folder="media">
        <folder>js</folder>
        <folder>css</folder>
        <folder>scss</folder>
        <folder>images</folder>
    </media>

E sostituirlo con:

   <media destination="templates/site/cassiopeia_mtfonts" folder="media">
        <folder>css</folder>
        <folder>fonts</folder>
        <folder>images</folder>
    </media>

Nota che la destinazione ora è "cassiopeia_mtfonts" e non più "cassiopeia". Abbiamo anche rimosso le cartelle "js" e "scss" perché non le utilizziamo, e aggiunto la cartella "fonts".

--- MODIFICA 4: File di lingua ---

Trovare il blocco:

  <languages folder="language">
        <language tag="en-GB">en-GB/tpl_cassiopeia.ini</language>
        <language tag="en-GB">en-GB/tpl_cassiopeia.sys.ini</language>
    </languages>

E sostituirlo con:

   <languages folder="language">
        <language tag="it-IT">it-IT/tpl_cassiopeia_mtfonts.ini</language>
        <language tag="it-IT">it-IT/tpl_cassiopeia_mtfonts.sys.ini</language>
    </languages>

Abbiamo cambiato la lingua da en-GB a it-IT e i nomi dei file in quelli del nostro template.

--- MODIFICA 5: Opzioni ---

Nel file templateDetails.xml di Cassiopeia troveremmo una sezione con le opzioni dei font disponibili nel pannello di amministrazione. Cerchiamo il blocco:

   <group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
        <option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
    </group>

E lo sostituiamo con:

   <group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
        <option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
        <option value="media/templates/site/cassiopeia_mtfonts/css/fonts-local_titillium.css">Titillium Web (local)</option>
    </group>

Abbiamo semplicemente aggiunto una nuova voce all'elenco esistente, puntando al nostro file CSS del font. 
In questo modo "Titillium Web (local)" apparirà come opzione selezionabile nel pannello Avanzate del template.

Creare i file di lingua

I file di lingua servono per tradurre le "chiavi" che abbiamo usato nel templateDetails.xml (come TPL_CASSIOPEIA_MTFONTS_XML_DESCRIPTION) nei testi leggibili che appariranno nell'interfaccia di Joomla.

Apriamo entrambi i file .ini nella cartella language/it-IT/ e inseriamo in ciascuno le stesse due righe:

    CASSIOPEIA_MTFONTS="Cassiopeia MTFONTS"
    TPL_CASSIOPEIA_MTFONTS_XML_DESCRIPTION="MTFONTS - Child template di Cassiopeia installabile"

Qual è la differenza tra i due file?

- tpl_cassiopeia_mtfonts.ini
  Viene caricato quando il template è attivo e viene usato nel frontend e nel backend del sito durante il normale utilizzo.

- tpl_cassiopeia_mtfonts.sys.ini
  Viene caricato da Joomla durante l'installazione del template e nei menu di gestione dell'estensione. Joomla legge questo file ancora prima che il template sia installato.

Immagini di anteprima

Joomla mostra due immagini per rappresentare visivamente il template nel pannello di amministrazione (Sistema → Template del sito):

- template_preview.png   dimensioni consigliate: 800×600 px
  È l'anteprima grande che appare aprendo i dettagli del template.

- template_thumbnail.png   dimensioni: 200×150 px
  È la miniatura che appare nella lista dei template.

Entrambe le immagini vanno inserite nella cartella media/images/.

In questa fase, poiché il sito non è ancora configurato e non possiamo fare uno screenshot reale, si consiglia di copiare temporaneamente le immagini di anteprima originali di Cassiopeia. 
Le troviamo nel pacchetto Joomla in: installation/templates/cassiopeia/images/

Dopo aver installato il template e configurato il tuo sito, possiamo fare uno screenshot, ridimensionarlo alle misure indicate e sostituire queste immagini temporanee.

Creare il pacchetto ZIP

Una volta completati tutti i file, dobbiamo impacchettare la cartella del template in un archivio .zip da installare su Joomla.

Come creare lo zip:
1. Entra nella cartella "cassiopeia_mtfonts/"
2. Seleziona TUTTO il contenuto (non la cartella stessa, ma ciò che c'è dentro)
3. Crea un archivio .zip

Installare il template e impostarlo come predefinito

Ora installiamo il template su Joomla come si fa per una qualsiasi estensione di Joomla.
Dopo averlo installato lo impostiamo come predefinito e assegnarlo alle pagini desiderate.

Verifiche finali

Una volta installato e impostato come predefinito, è arrivato il momento di attivare il font e verificare che tutto funzioni.

Come attivare Titillium Web:
1. Andare su Sistema → Template → Stili template sito
2. Cliccare su "cassiopeia_mtfonts - Predefinito"
3. Andare alla scheda "Avanzate"
4. Nel campo "Schema caratteri", selezionare "Titillium Web (local)" dal menu a tendina
5. Cliccare "Salva e Chiudi"

Conclusione

Abbiamo creato con successo un child template Joomla funzionante con font locali personalizzati. 
Da qui in poi si possono personalizzare ulteriormente il template aggiungendo altre personalizzazioni CSS nel file user.css, creare override di layout nella cartella html/, e aggiungere altri font o stili seguendo lo stesso schema.
In una guida successiva vedremmo come aggiungere altre posizioni sul tema child, e aggiungere delle extra opzioni gestibili direttamente dal pannello di controllo del template.

Buon Joomla!