I moduli Joomla! e il loro posizionamento

Tutti, o perlomeno tutti coloro che si occupano di sviluppo Joomla!, conoscono come inserire una posizione per i moduli all'interno di un template tramite jdoc:include, o come inserire un modulo all'interno di un articolo ricorrendo al plugin di sistema Load Module; quello che è meno noto è come variare dinamicamente le posizioni e come caricare, sempre dinamicamente, i moduli all'interno di componenti terzi. 

Al solito non ci occuperemo di rispiegare ciò che tutti sanno ed è gia ben documentato, ma cercheremo di individuare nuove strade da percorrere.

Il template di Joomla: posizioni dei moduli dinamiche

I template di Joomla! permettono di definire delle posizioni in cui caricare determinati tipi di estensioni, ovviamente i componenti, e ciò su cui ci focalizzeremo: i moduli.  

Le posizioni, dei moduli, che si intendono usare debbono essere dichiarate nel file xml di definizione del template, templateDetails.xml, nella sezione positions affinché possano essere visualizzate all'interno della 'Gestione moduli' di Joomla!.

Infatti quando pubblichiamo un modulo sul sito le posizioni del nostro template disponibili per la pubblicazione sono prese da questa sezione del file di configurazione.

Notate che non è necessario che le posizioni definite nel file xml siano tutte usate nel template, è però necessario che nel file xml siano indicate tutte le posizioni in cui si vuole pubblicare un modulo: ciò permette pertanto di creare posizioni virtuali o dinamiche.

Ma che intendiamo con posizione virtuale o dinamiche? Facciamo un passo indietro e vediamo, velocemente e solo per quanto di nostro interesse, come Joomla! gestisce il suo template. Per prima cosa carica il template e ne esegue il codice php contenuto, dopo di che analizza il codice prodotto dalla esecuzione alla ricerca dei propri place holder jdoc:include e provvede alla sostituzione di questi con il contenuto previsto per la rispettiva posizione.

Che il processo funzioni in questo modo modo è facilmente desumibile dall'osservazione di quasi tutti i templates, nei quali non sono rari frammenti di codice come il seguente:

<?php if ($this->countModules('position-x')) : ?>
   <div class="position-x">
      <jdoc:include type="modules" name="position-x" style="xhtml" />
   </div>
<?php endif; ?>
 

Codice dal quale si capisce che php a 'decidere' quali moduli caricare o meno.

Il fatto che il codice php contenuto nel template sia eseguito prima dell'inserimento del codice dei moduli fa sì che con del codice opportuno sia possibile definire dinamicamente le posizioni dei moduli.

Guardate, ad esempio, il seguente frammento di codice: 

<?php for($x=0; $x<10; $x++) : ?>
  <?php if ($this->countModules("position-{$x}")) : ?>
    <div class="position-<?php echo $x; ?>">
      <jdoc:include type="modules" name="position-<?php echo $x; ?>" style="xhtml" />
    </div>
  <?php endif; ?>
<?php endfor; ?>
 

Che cosa fa? stampa dieci posizioni di moduli (position-x ove x varia da 0 a 9), previa verifica dell'esistenza della pubblicazione di un modulo nella rispettiva posizione.

Ovviamente è necessario inserire le nuove dieci posizioni in templateDetails.xml per poter assegnare dei moduli a ciascuna delle stesse.

Caricare i moduli nelle pagine interne o in pagine specifiche dei componenti.

Naturalmente è anche possibile condizionare la pubblicazione dei moduli a determinate circostanze quali il trovarsi in una precisa pagina all'interno di un componente. 

Questo risolve un problema che spesso è sentito nell'ambito di Joomla! e che non sempre è di immediata  soluzione. Tramite la gestione dei moduli è possibile assegnare uno o più moduli a determinate voci di menù, ad esempio pubblicare l'elenco delle categorie di VirtueMart solo nelle pagine del negozio, ma se volessimo che l'elenco delle categorie non apparisse quando VirtueMart sta visualizzando il dettaglio del prodotto, non avremmo modo di farlo tramite la gestione standard di joomla, in quanto tutte le pagine generate da VirtueMart fanno capo alla medesima voce di menù (parametro Itemid nella query string):

<?php if( (JRequest::getVar('option')=='com_virtuemart') &amp;&amp; (JRequest::getVar('view') != 'productdetails' ) ): ?>  
  <jdoc:include type="modules" name="vm-categories" />
<?php endif; ?>
 

Nota: dato che allo stato attuale VirtueMart è compatibile solo con Joomla! 2.5 il codice sopra indicato usa la classe JRequest, deprecata in Joomla! 3. Nel caso si scriva codice per quest'ultima piattaforma è consigliato fare ricorso a JInput.

Variando le condizioni della if è possibile adattare il codice a qualsiasi componente e a qualsiasi situazione.

Gestione dei moduli Joomla! nei componenti

Vediamo ora come sia possibile inserire dinamicamente un modulo all'interno di un componente. La direttiva jdoc:include è processata all'interno del template principale di Joomla!, ma, per il flusso di processo sopra spiegato, non è utilizzabile all'interno dei templates dei componenti, ne , tanto meno all'interno del codice dei componenti stessi.

Come esempio prenderemo il caso in cui si voglia inserire un modulo in una precisa posizione di un template di un componente, questo per due motivi:

1. è il caso più comune e la cui soluzione è più richiesta;
2. ci consente di fornire una soluzione alternativa ma anche complementare a quella vista sopra.

Supponiamo, tornando al nostro VirtueMart, di voler inserire un modulo HTML Personalizzato (Custom HTML) all'interno della citata pagina di dettaglio del prodotto per permettere al nostro cliente di apporre delle note a fianco del prezzo del prodotto; ovviamente noi siamo capaci di inserire il codice HTML direttamente nel template, ma il nostro scopo è che il cliente sia autonomo nella gestione.

Per prima cosa creeremo un modulo HTML Personalizzato a cui assegneremo il titolo 'DescrizionePerPrezzo', il modulo deve essere pubblicato, ma possiamo non assegnarlo ad una posizione specifica oppure scegliere di non assegnarlo ad alcuna voce di menù.

Effettueremo ora un override del layout default_showprices.php nella view productdetails, e, nel punto prescelto, inseriremo il seguente codice: 

<?php
  jimport('joomla.application.module.helper');
  $mod = JModuleHelper::getModule('custom', 'DescrizionePerPrezzo');
  echo JModuleHelper::renderModule($mod);
?> 
 

Il contenuto del modulo sarà pubblicato ove voluto.

Notate la sintassi del metodo statico JModuleHelper::getModule(): il primo parametro è il tipo del modulo (senza il prefisso mod_), il secondo è il titolo dello stesso. Questa è la sintassi preferibile da usare, in quanto consente di individuare con precisione il modulo da pubblicare. Di norma, all'interno dei templates, non è necessario importare la classe JModuleHelper.

Il codice sopra indicato si presta all'utilizzo con qualsiasi modulo, non solo con quelli specifici di Joomla!, ma anche con quelli appartenenti a componenti di terze parti, purché scritti nel rispetto delle specifiche di programmazione del nostro CMS. Il tipo del modulo da usare come primo parametro del metodo è rintracciabile nella tabella #__extension, e, come detto, va scritto senza il prefisso 'mod_'.

Siamo giunti alla fine di questo articolo che ha inteso affrontare alcuni aspetti poco noti dell'uso dei moduli in Joomla! Sicuramente ora saprete che è possibile inserire moduli specifici in pagine specifiche del vostro sito, con ben poche limitazioni, se però non siete in grado di implementare il sistema da soli, ricordatevi che noi siamo a vostra disposizione.

Buon lavoro a tutti,

marco maria leoni