Layout dei template

Struttura dei file di layout

In un template, ogni estensione che genera output html inserisce il codice di output in un file di template all'interno della struttura di file dell'estensione, spesso in una cartella denominata tmpl. Alcuni esempi:

• /modules/mod_login/tmpl/default.php
• /modules/mod_login/tmpl/default_logout.php
• /components/com_content/tmpl/article/default.php
• /plugins/content/vote/tmpl/vote.php

In un override del template, viene creato un file con lo stesso nome all'interno della struttura di file del template e questo viene usato al posto del file nella struttura di file dell'estensione. Esempi corrispondenti:

• /templates/cassiopeia/html/mod_login/default.php
• /templates/cassiopeia/html/mod_login/default_logout.php
• /templates/cassiopeia/html/com_content/article/default.php
• /templates/cassiopeia/html/plg_content_vote/vote.php

Questo consente di personalizzare l'output secondo le proprie esigenze. Tuttavia, non è possibile scegliere se usare o meno l'override. Viene sempre usato.

In un layout alternativo del template, viene creato un file con un nome diverso dall'originale ma nella stessa cartella del template. Il nuovo nome non deve contenere un carattere di sottolineatura. Occorre inoltre creare ogni file che condivide la prima parte del nome originale. Un esempio:

• /templates/cassiopeia/html/mod_login/expires.php
• /templates/cassiopeia/html/mod_login/expires_logout.php

Diventa quindi possibile scegliere se usare il layout predefinito originale o il layout alternativo. La scelta viene effettuata nel modulo di modifica del modulo o del componente (scheda Avanzate per i moduli, scheda Opzioni per gli Articoli). Si noti che non tutte le estensioni consentono override o layout alternativi.

Attenzione: i plugin non forniscono un meccanismo per selezionare layout alternativi.

Layout alternativi dei moduli

Creare un layout alternativo per un modulo è simile a creare un override del template per un modulo. In entrambi i casi, viene creata una cartella chiamata templates/.../html/. Ad esempio, la cartella per un override del template o un layout alternativo di "mod_login" per il template cassiopeia sarebbe templates/cassiopeia/html/mod_login/.

Ci sono due differenze importanti tra un override del template e un layout alternativo. La prima è il nome del file. Per l'override del template, il file dovrebbe essere chiamato default.php per corrispondere al nome del file di base. Per un layout alternativo, si usa un nome diverso. L'unica regola è che il nome del file non deve contenere caratteri di sottolineatura.

La seconda differenza importante è che, a differenza dei file di override del template che vengono usati automaticamente ogni volta che il modulo viene mostrato usando il template con l'override, un file di layout alternativo viene usato solo se viene selezionato come parametro nelle impostazioni dei parametri del modulo.

Un esempio pratico - mod_login

• Andare su Sistema → Template del sito → Cassiopeia Dettagli e file
• Selezionare la scheda Crea override.
• Dalla lista Moduli selezionare la voce mod_login.
• Nella scheda Editor, selezionare html → mod_login per vedere le copie appena create dei template di output di mod_login.
• Rinominare default.php con un altro nome senza sottolineatura, expires.php in questo esempio.
• Rinominare default_logout.php in expires_logout.php.

Ora si hanno due file con esattamente lo stesso contenuto degli originali. Modificare il contenuto di expires_logout.php per aggiungere un messaggio che informi l'utente a che ora la sessione scadrà dopo ogni caricamento di pagina.

Alla riga 16, immediatamente sotto le istruzioni use esistenti, aggiungere quanto segue:

use Joomla\CMS\Factory;

date_default_timezone_set('Europe/London');
$config = Factory::getContainer()->get('config');
$lifetime = $config->get('lifetime', 0);
$time = time() + $lifetime * 60;
$endTime = date('H:i:s', $time); // time() returns a time in seconds already

E alla riga 36, immediatamente dopo la riga che contiene un'istruzione endif, aggiungi questo codice:

<p class="text-center">
Your session will expire at <br><?php echo $endTime; ?>
</p>

Chiudi i file di Cassiopeia. Seleziona Contenuti → Moduli sito e apri il modulo Login. Nella scheda Avanzate, voce Layout, troverai una scelta tra -- Dal modulo -- / Default e -- Dal template cassiopeia -- / expires.

Un modo in cui potresti usare questa funzione è avere due moduli di accesso, uno con accesso Pubblico e l'altro con accesso Super Utenti. In quest'ultimo seleziona l'opzione expires e solo i Super Utenti vedranno il promemoria sulla scadenza della sessione.

È importante capire che, se specificato nella schermata dei parametri del modulo, un layout alternativo per un modulo verrà utilizzato per quel modulo indipendentemente dal template usato per mostrare la pagina in cui il modulo è presente. È quindi responsabilità dell'amministratore assicurarsi che il file di layout funzioni come desiderato in tutti i template in cui questo modulo potrebbe essere mostrato.

Traduzione

Puoi tradurre il nome del file usando le Sostituzioni lingua. Prova la procedura seguente:

• Seleziona Sistema → Pannello di gestione → Sostituzioni lingua
• Seleziona la tua lingua e il lato Amministratore.
• Seleziona il pulsante Nuovo e compila il modulo. In questo esempio la chiave di lingua è TPL_CASSIOPEIA_MOD_LOGIN_LAYOUT_EXPIRES e il testo potrebbe essere Login / Logout con tempo di scadenza
• Salva e chiudi e torna al modulo Login.

Il campo del modulo di selezione del layout con expires tradotto:

Layout alternativi dei componenti

I layout alternativi dei componenti funzionano in modo simile ai layout dei moduli. Un file viene posizionato nella stessa cartella in cui si inserirebbe un file di override del template. Ad esempio, per creare un layout alternativo per un articolo per il template "cassiopeia", dovresti inserire un file nella cartella templates/cassiopeia/html/com_content/article/. Come per i layout dei moduli, il file non deve avere lo stesso nome del file principale e non deve contenere trattini bassi nel nome. Inoltre, non dovrebbe esserci un file XML con lo stesso nome in questa cartella. (Ne parleremo più avanti nella sezione Layout alternativi delle voci di menu.)

Puoi impostare un valore globale per i layout dei componenti nella finestra Opzioni del componente. Ad esempio, nella finestra Articoli: opzioni, è presente un parametro Scegli un layout come mostrato di seguito:

Come per i layout dei moduli, i layout dei componenti vengono mostrati come opzioni dei parametri nella schermata di modifica del singolo componente. Ad esempio, per un articolo, il parametro compare nella scheda Articoli: modifica opzioni come mostrato di seguito.

Come per gli altri parametri, l'impostazione Usa generale utilizzerà l'impostazione del parametro Opzioni. L'impostazione Predefinito del componente utilizzerà il layout predefinito del componente. I layout alternativi che hai creato per template diversi sono mostrati sotto ciascuna intestazione di template.

I nomi dei file possono essere tradotti. La riga seguente:

    TPL_CASSIOPEIA_COM_CONTENT_ARTICLE_LAYOUT_MYLAYOUT="Title Only No XML"

tradurrà un file chiamato "mylayout.php" come "Title Only No XML".

Puoi avere più di un file per un layout. Il file iniziale deve essere nominato senza trattini bassi e gli eventuali file aggiuntivi devono avere trattini bassi.

I layout alternativi dei componenti possono essere usati con articoli, contatti o newsfeed.

I layout alternativi dei componenti vengono utilizzati solo quando sono soddisfatte due condizioni: (1) sono specificati nei parametri del componente; e (2) non esiste una voce di menu per questo specifico componente. Ad esempio, se hai una o più voci di menu di tipo "Articolo singolo" impostate per un determinato articolo, il layout alternativo per quell'articolo non verrà utilizzato. Verrà invece utilizzato il layout specificato nella voce di menu. Questo è coerente con il modo generale in cui funzionano i parametri dei componenti, dove il più specifico (in questo caso una voce di menu per un articolo singolo) sovrascrive il meno specifico (in questo caso, i parametri dell'articolo).

Layout alternativi delle categorie

I layout alternativi delle categorie funzionano come i layout dei componenti. Le regole per specificare i file di layout sono le stesse. L'unica differenza è che la cartella è la cartella della categoria, non quella del componente. Ad esempio, un layout alternativo per una categoria di contatti per cassiopeia andrebbe nella cartella templates/cassiopeia/html/com_contact/category.

Puoi impostare i layout delle categorie globalmente, nella schermata Opzioni di ciascun componente. Di seguito un esempio dal modulo Contatti: Opzioni / Categoria:

I layout alternativi delle categorie compaiono quando aggiungi o modifichi una categoria nel modulo Componente: modifica categoria / Opzioni, come mostrato di seguito.

I layout alternativi delle categorie possono essere usati per articoli, banner, contatti e newsfeed.

Come per i layout dei componenti, un layout di categoria verrà utilizzato solo se:

1. è selezionato nei parametri globali o di categoria.
2. non esiste una voce di menu specifica per la categoria.

Se è impostata una voce di menu specifica per una determinata categoria, verrà utilizzato il layout selezionato nel menu anziché il layout alternativo della categoria.

Blog e lista delle categorie di articoli

Per gli articoli sono disponibili due layout di categoria del core: Blog e Lista. Ciascuno di questi layout appare nel modulo Articoli: Opzioni, scheda Categoria, sotto l'intestazione "Dal componente". Anche i layout alternativi appaiono nella lista, consentendo di selezionare Blog, Lista o un layout di template alternativo come layout predefinito della categoria, sia globalmente sia quando si modifica una singola categoria di articoli.

Questo significa che, come per le altre opzioni di layout, puoi controllare se i link delle categorie di articoli usano il layout blog o quello a lista. È importante capire che, come per gli altri parametri di layout, questa opzione avrà effetto solo quando non esiste una voce di menu a categoria singola per la categoria.

Voci di menu alternative

Le voci di menu alternative presentano una differenza importante rispetto alle altre. Per creare un layout alternativo per una voce di menu, devi includere un file XML il cui nome corrisponda al file di layout iniziale. Ad esempio, per creare una voce di menu alternativa chiamata "myarticle" per un articolo nel template cassiopeia, dovresti creare due file nella cartella templates/cassiopeia/html/com_content/article chiamati myarticle.php e myarticle.xml. Se volessi includere ulteriori file di layout, aggiungeresti questi file con trattini bassi nei nomi dei file.

Il file XML usa lo stesso formato dei file XML delle voci di menu del core. Questo ti consente non solo di creare un layout personalizzato per questa voce di menu, ma anche di creare parametri personalizzati. Ad esempio, potresti nascondere alcuni parametri o aggiungerne di nuovi.

Le voci di menu alternative compaiono quando selezioni un tipo di voce di menu, come mostrato di seguito.

Le voci di menu alternative vengono usate e funzionano allo stesso modo delle voci di menu standard. Poiché sono già basate su layout personalizzati, gli override del template non si applicano alle voci di menu alternative.

Come indicato sopra, i layout delle voci di menu hanno priorità sui layout alternativi dei componenti o delle categorie.

La traduzione delle voci di menu alternative avviene tramite i seguenti tag nei file XML. Il formato è "TPL_"<nome template>_<componente>_<vista>_<nome voce di menu>_<tipo di tag>. Ad esempio, queste righe tradurranno il titolo, l'opzione e la descrizione per una voce di menu alternativa chiamata "catmenuitem".

    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="cassiopeia Custom Category Layout"
    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="cassiopeia Custom"
    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for cassiopeia custom category layout."

Queste stringhe devono essere aggiunte a administrator/language/overrides/en-GB.override.ini, ma puoi usare il modulo Sostituzioni lingua descritto sopra.

Il file catmenuitem.xml inizierebbe con:

<?xml version="1.0" encoding="utf-8"?>
<metadata>
   <layout title="TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
      <help
         key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
      />
      <message>
         <![CDATA[TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
      </message>
   </layout>

Controllare il template per le voci di menu alternative

Come discusso sopra, la presenza di un file XML trasforma un layout alternativo in una voce di menu. Il formato del file XML è lo stesso dei file XML delle voci di menu del core. Con questo file XML, è possibile aggiungere i parametri che si desidera includere per questa voce di menu. Possono essere gli stessi di una delle voci di menu del core, oppure è possibile omettere parametri del core o aggiungerne di nuovi. Da notare che se si aggiungono nuovi parametri, questi potranno essere usati nel file di layout ma non verranno usati nei file di modello o vista del core.

È anche possibile sovrascrivere le impostazioni dei parametri del core. Un esempio di questo è controllare con quali template può essere mostrato il layout di una voce di menu alternativa. In alcuni casi, si potrebbe voler permettere a una voce di menu personalizzata di essere mostrata con qualsiasi template del sito. In altri casi, si potrebbe voler limitare il layout di quella voce di menu a un template specifico. In questa situazione, basterebbe aggiungere il seguente parametro al file XML della voce di menu:

<fields>
  <field
    name="template_style_id"
    type="templatestyle"
    label="COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"
    description="COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"
    filter="int"
    template="cassiopeia"
    class="inputbox">
  </field>
 </fields>

Questo sovrascriverà il parametro del core template_style_id. Impostando il template a "cassiopeia" in questo caso si limiterà l'utente a selezionare solo gli stili di template per il template "cassiopeia".

Ulteriori informazioni

• Nozioni di base sui template
• Cartelle e file del template Cassiopeia
• Personalizzazione del template Cassiopeia
• Override dei template
• Layout dei template
• Template Cassiopeia semplificato - Un caso di studio - un semplice template basato su Cassiopeia