User Documentation
Download
Avvia

Cassiopeia templateDetails.xml

Lato e scopo

Puoi vedere un esempio di file templateDetails.xml elencato in Sistema → Template sito → Dettagli e file di Cassiopeia. Puoi anche modificarlo lì, se hai un buon motivo per farlo. Altrimenti, lascialo stare! Ogni template ha un file di questo tipo e un template derivato inizialmente consiste in una struttura di file contenente solo questo unico file.

Il file templateDetails.xml contiene i dati di cui Joomla! ha bisogno per gestire e mostrare il template. Questo include i meta-dati usati per fornire informazioni sul template, le posizioni delle cartelle e dei file, le posizioni dei moduli del template e le opzioni di configurazione selezionabili dall'utente. Il contenuto del file templateDetails.xml varia da template a template.

Cassiopeia templateDetails.xml

I file in formato xml hanno una struttura ben definita. Un file xml deve avere la sintassi corretta altrimenti non funzionerà!

Formato XML

La prima riga di ogni templateDetails.xml deve iniziare con la definizione del doctype XML.

La riga successiva indica a Joomla! che i dati in questo file riguardano un'estensione di template per il sito. Tutti i dati del template sono contenuti tra i tag di apertura e di chiusura.

<extension type="template" client="site">
...
</extension>

Metadati

La prima sezione dei dati del template di solito definisce informazioni sul template, ad esempio: nomi, date, informazioni di contatto, copyright, numero di versione e descrizione.

<extension version="3.1" type="template" client="site">
    <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>

Nota che un template che può avere template derivati ha il valore inheritable impostato a 1. I template derivati hanno questo valore impostato a 0. Questo dato viene usato nell'elenco Template: Template (Sito) come mostrato di seguito.

site templates list

La descrizione contiene una chiave di linguaggio e non il testo effettivo della descrizione. La chiave viene sostituita dal testo ottenuto da un file di lingua in fase di esecuzione. I file di lingua sono definiti nella sezione linguaggio del file templateDetails.xml.

templates edit style form

Cartelle e file

Le cartelle e i file per il template Cassiopeia sono memorizzati in due posizioni separate. I file php e correlati sono memorizzati nella cartella site/templates. I file media (css, immagini, js e scss) sono memorizzati nella cartella site/media. Queste posizioni sono definite nel file xml come segue:

    <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>
    <media destination="templates/site/cassiopeia" folder="media">
        <folder>js</folder>
        <folder>css</folder>
        <folder>scss</folder>
        <folder>images</folder>
    </media>

Questo è lo schema riscontrabile in tutti i moderni template di Joomla 4 e 5. La struttura è visibile nel modulo Template: Personalizza (Cassiopeia):

templates customise cassiopeia page

Posizioni dei moduli

Le posizioni dei moduli disponibili sono definite come segue:

    <positions>
        <position>topbar</position>
        <position>below-top</position>
        <position>menu</position>
        <position>search</position>
        <position>banner</position>
        <position>top-a</position>
        <position>top-b</position>
        <position>main-top</position>
        <position>main-bottom</position>
        <position>breadcrumbs</position>
        <position>sidebar-left</position>
        <position>sidebar-right</position>
        <position>bottom-a</position>
        <position>bottom-b</position>
        <position>footer</position>
        <position>debug</position>
    </positions>

Ogni tag crea una posizione del modulo che è disponibile nella lista delle posizioni in un modulo di modifica del modulo. Il formato semplice della lista delle posizioni consente di personalizzarla facilmente. Ad esempio, per aggiungere una nuova posizione del modulo alla lista in un template derivato, basta aggiungere un nuovo tag all'interno del tag con un nome univoco usando solo lettere minuscole senza spazi. Tieni presente che questo aggiunge solo la posizione ai moduli di modifica dei moduli ed è necessario uno sviluppo aggiuntivo in altri file del template per renderizzare la nuova posizione sul frontend.

Cassiopeia ha già abbastanza posizioni del template! Se pensi di averne bisogno di una in più probabilmente ti sbagli. Ricorda che qualsiasi numero di moduli può essere assegnato a una singola posizione e ordinato nella pagina della lista dei moduli. Posizioni disponibili:

Cassiopeia template positions diagram

Puoi anche vedere le posizioni dei moduli in qualsiasi template: da Sistema → Template del sito seleziona il pulsante Opzioni nella barra degli strumenti. Nel modulo delle opzioni imposta il campo Anteprima posizioni modulo su Abilitato. Salva e chiudi. Vai sul tuo sito e aggiungi ?tp=1 alla fine di qualsiasi url (oppure &tp=1 se è già presente un ? nell'url). Joomla mostrerà tutte le posizioni del template disponibili, anche quelle non ancora utilizzate:

Cassiopeia template positions

Lingue

I file di lingua consentono la traduzione del testo statico nel template. Il file tpl_cassiopeia.ini contiene le traduzioni chiave-testo per il testo che sarà visualizzato dall'utente. Il file tpl_cassiopeia.sys.ini contiene le traduzioni chiave-testo per il testo che sarà visto dall'amministratore.

    <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>

I file di lingua per la lingua predefinita inglese GB sono memorizzati in site/language/en-GB/. Altre lingue verrebbero memorizzate in modo analogo in file con il codice ISO della lingua appropriato, ad esempio fr-FR per il francese in Francia o de-DE per il tedesco in Germania (che potrebbe essere diverso dal tedesco svizzero e dal tedesco austriaco).

Opzioni

Un template può offrire opzioni di visualizzazione che possono essere scelte dall'Amministratore nel modulo Template: modifica stile. Ad esempio, la scheda Avanzate del template Cassiopeia consente a un Amministratore di cambiare il Marchio, aggiungere un Logo, clicca uno Schema di caratteri e altro ancora.

templates edit style form advanced tab

Le opzioni del template sono definite all'interno di una struttura che crea campi all'interno di fieldset. Ogni fieldset appare come una scheda nel modulo di modifica. Questa è la struttura che crea la scheda Avanzate mostrata sopra.

    <config>
        <fields name="params">
            <fieldset name="advanced">
                <field
                    name="brand"
                    type="radio"
                    label="TPL_CASSIOPEIA_BRAND_LABEL"
                    default="1"
                    layout="joomla.form.field.radio.switcher"
                    filter="boolean"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>
                ...
            </fieldset>
        </fields>
    </config>

Le singole opzioni sono definite con il tag <field>. Ogni <fieldset>, e ogni parametro <field> all'interno di un <fieldset>, richiede un nome univoco definito da un attributo name. Questo nome definisce il parametro stesso ed è utilizzato per passare le impostazioni ai file del frontend. Ogni parametro contiene anche un attributo label e un attributo description. Il testo dell'etichetta appare insieme al parametro nella schermata delle impostazioni per identificare a cosa serve l'impostazione e informazioni più dettagliate possono essere incluse nella descrizione.

Un campo parametro può essere praticamente qualsiasi tipo di input di modulo con le opzioni corrispondenti. Questo viene selezionato tramite l'attributo type. Eventuali opzioni necessarie, come pulsanti radio o scelte di selezione, sono definite nei tag <option>. I nomi delle classi CSS possono essere definiti con l'attributo class e un valore predefinito può essere definito utilizzando l'attributo default.

Di seguito sono riportate le definizioni delle opzioni nel template Cassiopeia predefinito. In questo esempio, tutte le Etichette, le Descrizioni e le Opzioni utilizzano definizioni di stringhe di lingua dai file di lingua definiti nella sezione precedente, nonché alcune dal core di Joomla!, in modo da poter essere tradotte in diverse lingue secondo necessità.

    <config>
        <fields name="params">
            <fieldset name="advanced">
                <field
                    name="brand"
                    type="radio"
                    label="TPL_CASSIOPEIA_BRAND_LABEL"
                    default="1"
                    layout="joomla.form.field.radio.switcher"
                    filter="boolean"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>

                <field
                    name="logoFile"
                    type="media"
                    default=""
                    label="TPL_CASSIOPEIA_LOGO_LABEL"
                    showon="brand:1"
                />

                <field
                    name="siteTitle"
                    type="text"
                    default=""
                    label="TPL_CASSIOPEIA_TITLE"
                    filter="string"
                    showon="brand:1"
                />

                <field
                    name="siteDescription"
                    type="text"
                    default=""
                    label="TPL_CASSIOPEIA_TAGLINE_LABEL"
                    description="TPL_CASSIOPEIA_TAGLINE_DESC"
                    filter="string"
                    showon="brand:1"
                />

                <field
                    name="useFontScheme"
                    type="groupedlist"
                    label="TPL_CASSIOPEIA_FONT_LABEL"
                    default="0"
                    >
                    <option value="0">JNONE</option>
                    <group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
                        <option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
                    </group>
                    <group label="TPL_CASSIOPEIA_FONT_GROUP_WEB">
                        <option value="https://fonts.googleapis.com/css2?family=Fira+Sans:wght@100;300;400;700&amp;display=swap">Fira Sans (web)</option>
                        <option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&amp;family=Roboto:wght@100;300;400;700&amp;display=swap">Roboto + Noto Sans (web)</option>
                    </group>
                </field>

                <field
                    name="noteFontScheme"
                    type="note"
                    description="TPL_CASSIOPEIA_FONT_NOTE_TEXT"
                    class="alert alert-warning"
                />

                <field
                    name="colorName"
                    type="filelist"
                    label="TPL_CASSIOPEIA_COLOR_NAME_LABEL"
                    default="colors_standard"
                    fileFilter="^custom.+[^min]\.css$"
                    exclude="^colors.+"
                    stripext="true"
                    hide_none="true"
                    hide_default="true"
                    directory="media/templates/site/cassiopeia/css/global/"
                    validate="options"
                    >
                    <option value="colors_standard">TPL_CASSIOPEIA_COLOR_NAME_STANDARD</option>
                    <option value="colors_alternative">TPL_CASSIOPEIA_COLOR_NAME_ALTERNATIVE</option>
                </field>

                <field
                    name="fluidContainer"
                    type="radio"
                    layout="joomla.form.field.radio.switcher"
                    default="0"
                    label="TPL_CASSIOPEIA_FLUID_LABEL"
                    >
                    <option value="0">TPL_CASSIOPEIA_STATIC</option>
                    <option value="1">TPL_CASSIOPEIA_FLUID</option>
                </field>

                <field
                    name="stickyHeader"
                    type="radio"
                    label="TPL_CASSIOPEIA_STICKY_LABEL"
                    layout="joomla.form.field.radio.switcher"
                    default="0"
                    filter="integer"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>

                <field
                    name="backTop"
                    type="radio"
                    label="TPL_CASSIOPEIA_BACKTOTOP_LABEL"
                    layout="joomla.form.field.radio.switcher"
                    default="0"
                    filter="integer"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>
            </fieldset>
        </fields>
    </config>

In questo esempio, il tag <fieldset name="advanced"> racchiude tutti i parametri e utilizza l'attributo name per creare la scheda Avanzate nell'interfaccia. Tutto ciò che serve per creare un'altra scheda nell'interfaccia è un altro tag <fieldset> con un attributo name diverso. Tenendo presente questo, è relativamente semplice creare tutte le schede e i parametri aggiuntivi necessari in un template.

Un potenziale utilizzo di parametri aggiuntivi è negli override o nei layout sia per template principali che per template derivati.

Sommario

Questo è il file templateDetails.xml utilizzato da Cassiopeia:

<?xml version="1.0" encoding="utf-8"?>
<extension type="template" client="site">
    <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>
    <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>
    <media destination="templates/site/cassiopeia" folder="media">
        <folder>js</folder>
        <folder>css</folder>
        <folder>scss</folder>
        <folder>images</folder>
    </media>
    <positions>
        <position>topbar</position>
        <position>below-top</position>
        <position>menu</position>
        <position>search</position>
        <position>banner</position>
        <position>top-a</position>
        <position>top-b</position>
        <position>main-top</position>
        <position>main-bottom</position>
        <position>breadcrumbs</position>
        <position>sidebar-left</position>
        <position>sidebar-right</position>
        <position>bottom-a</position>
        <position>bottom-b</position>
        <position>footer</position>
        <position>debug</position>
    </positions>
    <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>
    <config>
        <fields name="params">
            <fieldset name="advanced">
                <field
                    name="brand"
                    type="radio"
                    label="TPL_CASSIOPEIA_BRAND_LABEL"
                    default="1"
                    layout="joomla.form.field.radio.switcher"
                    filter="boolean"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>

                <field
                    name="logoFile"
                    type="media"
                    default=""
                    label="TPL_CASSIOPEIA_LOGO_LABEL"
                    showon="brand:1"
                />

                <field
                    name="siteTitle"
                    type="text"
                    default=""
                    label="TPL_CASSIOPEIA_TITLE"
                    filter="string"
                    showon="brand:1"
                />

                <field
                    name="siteDescription"
                    type="text"
                    default=""
                    label="TPL_CASSIOPEIA_TAGLINE_LABEL"
                    description="TPL_CASSIOPEIA_TAGLINE_DESC"
                    filter="string"
                    showon="brand:1"
                />

                <field
                    name="useFontScheme"
                    type="groupedlist"
                    label="TPL_CASSIOPEIA_FONT_LABEL"
                    default="0"
                    >
                    <option value="0">JNONE</option>
                    <group label="TPL_CASSIOPEIA_FONT_GROUP_LOCAL">
                        <option value="media/templates/site/cassiopeia/css/global/fonts-local_roboto.css">Roboto (local)</option>
                    </group>
                    <group label="TPL_CASSIOPEIA_FONT_GROUP_WEB">
                        <option value="https://fonts.googleapis.com/css2?family=Fira+Sans:wght@100;300;400;700&amp;display=swap">Fira Sans (web)</option>
                        <option value="https://fonts.googleapis.com/css2?family=Noto+Sans:wght@100;300;400;700&amp;family=Roboto:wght@100;300;400;700&amp;display=swap">Roboto + Noto Sans (web)</option>
                    </group>
                </field>

                <field
                    name="noteFontScheme"
                    type="note"
                    description="TPL_CASSIOPEIA_FONT_NOTE_TEXT"
                    class="alert alert-warning"
                />

                <field
                    name="colorName"
                    type="filelist"
                    label="TPL_CASSIOPEIA_COLOR_NAME_LABEL"
                    default="colors_standard"
                    fileFilter="^custom.+[^min]\.css$"
                    exclude="^colors.+"
                    stripext="true"
                    hide_none="true"
                    hide_default="true"
                    directory="media/templates/site/cassiopeia/css/global/"
                    validate="options"
                    >
                    <option value="colors_standard">TPL_CASSIOPEIA_COLOR_NAME_STANDARD</option>
                    <option value="colors_alternative">TPL_CASSIOPEIA_COLOR_NAME_ALTERNATIVE</option>
                </field>

                <field
                    name="fluidContainer"
                    type="radio"
                    layout="joomla.form.field.radio.switcher"
                    default="0"
                    label="TPL_CASSIOPEIA_FLUID_LABEL"
                    >
                    <option value="0">TPL_CASSIOPEIA_STATIC</option>
                    <option value="1">TPL_CASSIOPEIA_FLUID</option>
                </field>

                <field
                    name="stickyHeader"
                    type="radio"
                    label="TPL_CASSIOPEIA_STICKY_LABEL"
                    layout="joomla.form.field.radio.switcher"
                    default="0"
                    filter="integer"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>

                <field
                    name="backTop"
                    type="radio"
                    label="TPL_CASSIOPEIA_BACKTOTOP_LABEL"
                    layout="joomla.form.field.radio.switcher"
                    default="0"
                    filter="integer"
                    >
                    <option value="0">JNO</option>
                    <option value="1">JYES</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>