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

: Scritto da extrowebsite; Pubblicato: 16 Febbraio 2021; Creato: 16 Febbraio 2021; Ultima modifica: 11 Settembre 2021

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:

raw / none: output "grezzo" dei contenuti del modulo, senza nessun elemento html che li contiene. La visualizzazione è la medesima;
table: output del modulo inserito in una tabella;
horz: output del modulo presentato come tabella inserita, a sua volta, in un'altra tabella;
xhtml: output del modulo racchiuso in un elemento div;
rounded: output del modulo racchiuso in div annidati, con possibilità di poter avere angoli arrotondati;
outline: output del modulo racchiuso all'interno di bordi tratteggiati, all'interno del quale è possibile leggere il nome dato al modulo.

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 Jdoc statement di Joomla!.

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:

$modules;
$params;
$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.

$module -> content;
$module -> showtitle;
$module -> title

$module -> title restituirà il titolo del modulo
$module -> content restituirà il contenuto del modulo
$module -> showtitle è una variabile Booleana, vero falso. Sarà soddisfatta la condizione quando il titolo sarà mostrato; falsa, il contrario

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.