Personalizzare l'output di un modulo Joomla! con Module Chrome

Personalizzare l'output di un modulo Joomla! con Module Chrome
Personalizzare l'output di un modulo Joomla! con Module Chrome

Cosa si intende con il termine Module Chrome? Sostanzialmente ci si riferisce ai diversi tipi di output, con relativo codice html prodotto dal core di Joomla!, per quanto riguarda la presentazione dei contenuti presenti in un determinato modulo.

Una volta inserito lo snippet di codice nel file index.php, che richiama un modulo in una determinata posizione, il CMS prevede diverse visualizzazioni per esso. Questi stili sono:

Il Module Chrome, è utilizzato per presentare i contenuti di un modulo con bordi, bordi arrotondati, titoli di colore diverso o differenti grandezze di font. Ricorderai bene il vecchio template predefinito Rhuk Milkyway. Esso prevedeva bordi arrotondati con lo stile "rounded".

Module Chrome con con bordi arrotondati
Module Chrome Joomla! con con bordi arrotondati

Affinchè le diverse visualizzazioni del Module Chrome entrino in azione, è necessario che nello statement che richiama il modulo sia presente l'attributo style.

In un articolo precedente è stato ampiamente trattato l'argomento inerente gli .

Si veda il seguente statement di esempio, da inserire nel file index.php. Esso richiama un modulo nella posizione left - precedentemente scritta nel file templateDetails.xml:

<jdoc:include type="modules" name="left" style="Nome-Stile"  />

Notare bene che il codice appena riportato mostrerà lo stesso output per tutti i moduli presenti nella posizione left. In altri termini, se si vuole visualizzare a video più di un modulo all'interno della stessa colonna con output differente per ognuno di essi, è necessario "istanziare" tante posizioni quanti sono i moduli. Esempio:

<jdoc:include type="module" name="user1" style="Nome-Stile1" />
<jdoc:include type="module" name="user2" style="Nome-Stile2" />

Creare il file modules.php

Per definire la personalizzazione del Module Chrome nel template in uso, è necessario creare un file chiamato modules.php. Tale file deve trovarsi all'interno della cartella chiamata "html". Il suo percorso completo è:

root-joomla/templates/Template_Attivo/html/modules.php

In tale file deve essere definita una funzione dal nome modChrome_NomeStile dove NomeStile verrà sostituito dal nome vero e proprio dello stile che si vorrà dare al modulo. Questa funzione necessita di tre argomenti:

  1. $modules;
  2. $params;
  3. $attribs

come mostrato nel frammento di codice riportato di seguito:

<?php function modChrome_NomeStile( $module, &$params, &$attribs ) 
{
/* Output del modulo */
}
?>

All' interno della funzione "modChrome" è possibile fare uso di una qualsiasi proprietà disponibile per i Moduli (per esempio i campi della tabella #_modules del database Joomla! sul server), ma è necessario, se non obbligatorio, inserire determinati parametri.

La funzione "modChrome" è una normalissima funzione PHP. E' possibile inserire qualsiasi procedura regolare di codice. Un esempio potrebbe essere quello di utilizzare una istruzione "if" per controllare il valore di "$module ->showtitle" per vedere se deve essere visualizzato o meno il titolo:

<?php
if ($module->showtitle) 
{
echo '<h2>' .$module->title .'</h2>';}
?>

Accedere ai parametri del modulo

Ai parametri del Modulo si accede usando l'oggetto $params. Per esempio, è possibile assegnare un suffisso di classe direttamente dal backend di Joomla! Tale suffisso viene memorizzato nei parametri per il modulo come "moduleclass_sfx". Per creare un elemento <div> con una classe determinata dal suffisso del modulo, si deve scrivere:

<div class="<?php echo $params->get( 'moduleclass_sfx' ); ?>">
<!-- contenuti -->
</div>

Attributi personalizzati per il module chrome

E' anche possibile passare altri tipi di attributi nella funzione PHP del Module Chrome, utilizzando lo stesso statement <jdoc:include />. Tali ulteriori attributi possono comprendere qualsiasi codice per la personalizzazione del modulo, i quali sono memorizzati nell' array "$attribs". Si prenda come esempio la funzione:

<?php
function modChrome_NomeStile( $module, &$params, &$attribs ) {
if (isset( $attribs['headerLevel'] ))
{
$headerLevel = $attribs['headerLevel'];
} else {
$headerLevel = 3;
}

if (isset( $attribs['background'] ))     
{
$background = $attribs['background'];
} else {
$background = 'blue';
}
echo '<div class="' .$params->get( 'moduleclass_sfx' ) .'" >';
if ($module->showtitle) 
{
echo '<h' .$headerLevel .'>' .$module->title .'</h' .$headerLevel .'>';
}
echo '<div class="' .$background .'">';
echo $module->content;
echo '</div>';
echo '</div>';
}
?>

Ci sarebbe da impostare, stando alla funzione appena riportata, il valore per lo sfondo e per il font-size del titolo (headerLevel). Se questi valori non sono impostati, gli attributi predefiniti saranno "blu" e "3", rispettivamente.

Passare gli attributi al Module Chrome attraverso lo statement <jdoc:include />

<jdoc:include /> Statement:
<jdoc:include type="modules" name="user1" style="NomeStile" />
<div> 
<h3><!--Titolo Modulo--></h3> 
<div class="blue"> <!--Contenuti--> </div> 
</div>
<jdoc:include /> Statement:

<jdoc:include type="modules" name="user1" style="NomeStile" background="green" />
<div> 
<h3><!--Titolo Modulo--></h3> 
<div class="green"> <!--Contenuti--> </div> 
</div>
<jdoc:include /> Statement:
<jdoc:include type="modules" name="user1" style="NomeStile" headerLevel="1" background="yellow" />
<div> 
<h1><!--Titolo Modulo--></h1> 
<div class="yellow"> <!--Contenuti--> </div> 
</div>

Analizzando bene questo codice, possiamo vedere la versatilità dei moduli e di come è possibile ottenere una personalizzazione estrema nel nostro sito.