Come creare un modulo per Joomla?

Dopo aver trattato a fondo il tema della realizzazione di template per Joomla, torniamo a parlare di questo CMS per mostrarti il procedimento da seguire per la creazione di un modulo.

Quello che realizzeremo in questo articolo, sarà un modulo molto semplice ma che fornirà comunque le basi e la tecnica per creare lavori anche più complessi.

Nello specifico il nostro modulo mostrerà la data e l’ora attuali con diverse possibilità di configurazione.

Sei hai già curiosato nelle cartelle di un modulo di Joomla ed hai avuto l’impressione che si tratti di qualcosa di incomprensibile, ti sbagli. In realtà non è difficile come sembra. Basta capire i meccanismi che ne regolano il funzionamento.

Torniamo al modulo mod_time, che come detto serivrà a mostrare la data e l’ora attuale.

Il risultato finale è mostrato nella seguente immagine:

Sarà possibile personalizzare il testo prima della data, il testo prima dell’ora, il formato della data e se mostrare o meno l’ora.

La struttura della directory

Iniziamo a creare la cartella mod_time. Il formato standard del nome di una cartella di un modulo di Joomla è sempre mod_nomeModulo. Al suo interno creiamo la cartella tmpl. La cartella principale conterrà i seguenti files:

  • index.html: un file vuoto che previene la visualizzazione del contenuto della cartella;
  • mod_time.xml: il file di installazione del modulo, molto simile a quello che abbiamo visto negli articoli sulla realizzazione di template per Joomla;
  • mod_time.php: tecnicamente chiamato il punto di ingresso del modulo, è il file principale che viene caricato per attivare e mostrare il modulo;
  • helper.php: in questo file possiamo creare una serie di strumenti necessari a far funzionare il nostro modulo. Nella fattispecie svilupperemo due semplici metodi che ci restituiranno l’ora e la data secondo il formato scelto nelle impostazioni.

La cartella tmpl conterrà i seguenti files:

  • index.html: sempre il file vuoto che previene la visualizzazione del contenuto della cartella;
  • default.php: il file che definisce il template del modulo come abbiamo già visto nell’articolo: “Come convertire un layout xhtml in template Joomla“.

Quella mostrata nell’immagine sopra è la struttura di base di un modulo. Chiaramente, nel caso di moduli più complessi, è possibile che vi siano altri files.

Creare il file di installazione di un modulo Joomla

Iniziamo ora a scrivere il file di installazione mod_time.xml.

La prima parte, come nel caso dei template, contiene informazioni generali:

<?xml  version="1.0" encoding="utf-8"?>
<install type="module"  version="1.5.0">
    <name>Modulo_Time</name>
    <author>Maurizio Tarchini</author>
    <creationDate>Maggio 2010</creationDate>
    <copyright>Copyright (C) 2010</copyright>
    <license>https://www.gnu.org/licenses/gpl-2.0.html  GNU/GPL</license>
    <authorEmail>info@mtxweb.ch</authorEmail>
    <authorUrl>www.yourinspirationweb.com</authorUrl>
    <version>1.0.0</version>
    <description>Questo modulo visualizza data e  ora</description>

Di seguito dobbiamo indicare la posizione dei vari files, ad eccezione del file di installazione che stiamo scrivendo. Nota che vi è una sintassi particolare per definire quale sia il punto di ingresso del modulo:

<files>
    <filename  module="mod_time">mod_time.php</filename>
    <filename>helper.php</filename>
    <filename>index.html</filename>
    <filename>tmpl/index.html</filename>
    <filename>tmpl/default.php</filename>
</files>

Come vedi dobbiamo indicare il punto di ingresso con la sintassi:

<filename  mudule="nome_modulo">mod_modulo.php</filename>

Ed ora scriveremo la parte relativa ai parametri di configurazione del modulo che vanno dichiarati proprio nel file di installazione. La procedura è abbastanza semplice, basta dire a Joomla che tipo di campo form desideriamo. Ad esempio il primo campo (testo prima della data) è un campo di tipo text e lo dichiareremo in questo modo:

<param  name="testo_prima_della_data" type="text" default="La data odierna"  label="Testo prima della data" description="Inserisci il testo  visualizzato prima della data" />

Con name impostiamo il nome che ci permetterà di recuperare il valore del parametro (vedremo in seguito come), mentre type funziona come nei normali campi form (ad eccezione del tipo “select” che dovremo indicare con “list”).

Gli altri parametri sono mostrati nella seguente immagine:

L’elenco completo dei parametri si presenterà così:

<params>
    <param  name="testo_prima_della_data" type="text" default="La data odierna"  label="Testo prima della data" description="Inserisci il testo  visualizzato prima della data" />
    <param name="testo_prima_dell_ora" type="text" default="Sono le ore"  label="Testo prima dell'ora" description="Inserisci il testo  visualizzato prima dell'ora" />
    <param name="ora" type="radio" default="1" label="Mostra l'ora"  description="Mostra/Nasconde l'ora">
        <option value="0">No</option>
        <option value="1">Si</option>
    </param>
    <param  name="formato" type="list" default="0" label="Scegli il formato della  data">
        <option value="0">12.3.08</option>
        <option value="1">12 marzo 2008</option>
        <option value="2">Domenica 12 marzo 2008</option>
    </param>
</params>

Attenzione, la sintassi è un tantino rigida. Quando il tag param non prevede opzioni (text, textarea) non va chiuso; va però inserita una barra alla fine come è il caso per i tag (X)HTML che non prevedono chiusura.

Quando invece prevedono opzioni (radio, list), queste vanno indicate con il tag option e il tag param va infine chiuso.

Ed ecco come dovrebbe apparire il file di installazione:

<?xml  version="1.0" encoding="utf-8"?>
<install type="module"  version="1.5.0">
    <name>Modulo_Time</name>
    <author>Maurizio Tarchini</author>
    <creationDate>Maggio 2010</creationDate>
    <copyright>Copyright (C) 2010</copyright>
    <license>https://www.gnu.org/licenses/gpl-2.0.html  GNU/GPL</license>
    <authorEmail>info@mtxweb.ch</authorEmail>
    <authorUrl>www.mtxweb.ch</authorUrl>
    <version>1.0.0</version>
    <description>Questo modulo visualizza data e  ora</description>
    <files>
        <filename module="mod_time">mod_time.php</filename>
        <filename>helper.php</filename>
        <filename>index.html</filename>
        <filename>tmpl/index.html</filename>
        <filename>tmpl/default.php</filename>
    </files>
    <params>
        <param name="testo_prima_della_data" type="text" default="La data  odierna" label="Testo prima della data" description="Inserisci il testo  visualizzato prima della data" />
        <param name="testo_prima_dell_ora" type="text" default="Sono le ore"  label="Testo prima dell'ora" description="Inserisci il testo  visualizzato prima dell'ora" />
        <param name="ora" type="radio" default="1" label="Mostra l'ora"  description="Mostra/Nasconde l'ora">
            <option value="0">No</option>
            <option value="1">Si</option>
        </param>
        <param  name="formato" type="list" default="0" label="Scegli il formato della  data">
            <option value="0">12.3.08</option>
            <option value="1">12 marzo 2008</option>
            <option value="2">Domenica 12 marzo 2008</option>
        </param>
    </params>
</install>

Come vedi è molto semplice aggiungere delle opzioni ad un modulo. Non dobbiamo preoccuparci né di creare i form e neppure di come o dove verranno salvati i dati. Quanto a recuperarli, come vedremo più avanti, è altrettanto semplice.

Passiamo ora a sviluppare il file hepler.php.

Una cassetta degli attrezzi per il nostro modulo

Tutto quello che ci potrà servire per costruire/elaborare i dati necessari al nostro modulo, lo svilupperemo all’interno del file helper.php. Nel nostro caso si tratta di cose molto semplici, ma immaginate moduli più complessi con interrogazioni al database ad esempio. In questo modo teniamo tutte le procedure di “preparazione dei dati”  al di fuori del punto di ingresso del modulo.

I nostri attrezzi saranno due metodi che ritornano la data e l’ora. Quello che ritorna la data dovrà tenere conto di come è impostato il parametro del formato (potrà essere 0, 1 o 2).

Iniziamo dunque a scrivere il file helper.php:

<?php
defined('_JEXEC')  or die('Restricted access');

class modTime
{
    function getDate($param)
    {
        switch($param)
        {
            case 0:
            $date =  strftime("%d.%m.%y");
            break;

            case 1:
            $date =  strftime("%d %B %Y");
            break;

            case 2:
            $date =  strftime("%A %d %B %Y");
            break;
        }
        return $date;
    }

    function getHour()
    {
        return date("H:i");
    }
}
?>

La prima riga serve a prevenire accessi diretti. Semplicemente verifica se la costante _JEXEC (che viene valorizzata da Joomla) è definita, in caso contrario blocca l’esecuzione dello script.

Il primo metodo restituisce la data nel formato corrispondente al parametro passato, mentre il secondo metodo restituisce semplicemente l’ora.

Vediamo ora come realizzare il file mod_time.php

Sviluppare il punto di ingresso

In questo file dovremo includere il file helper.php, recuperare i valori che ci servono ed infine richiamare il file del template (che non abbiamo ancora creato).

<?php
defined('_JEXEC')  or die('Restricted access');
require_once  (dirname(__FILE__).DS.'helper.php');

$date =  modTime::getDate($params->get('formato'));
$hour =  modTime::getHour();

require(JModuleHelper::getLayoutPath('mod_time'));
?>

Come sempre, alla prima riga inseriamo il codice che evita l’accesso diretto allo script.

In seguito includiamo il nostro helper.php e quindi lo utilizziamo.

Ricaviamo la data grazie al metodo getDate del file helper.php, passando come argomento il valore impostato nel parametro del formato data. Come avrai intuito, per recuperare il valore dei parametri di configurazione del modulo si fa capo al metodo get() passando semplicemente come argomento il nome del parametro. Dunque:

$params->get('formato')

restituirà 0 o 1 o 2 permettendo così al metodo getDate di restituire la data nel formato impostato.

Valorizziamo così le variabili $date e $hour che in pratica sono gli unici dati che ci servono; possiamo dunque passare ad includere il file del template del modulo, che però dobbiamo ancora realizzare.

Il file del template

Nella cartella tmpl creiamo il file default.php. Anche questo file dovrà iniziare con il codice che impedisce l’accesso diretto. In seguito definiremo un div nel quale scrivere il nostro risultato.

<?php
defined('_JEXEC') or die('Restricted  access');
?>

<div id="time_module">
<?php echo  $params->get('testo_prima_della_data') . ' <strong>' . $date .  '</strong>'; ?>
<br />

<?php if($params->get('ora'))
    {
        echo $params->get('testo_prima_dell_ora') . ' <strong>' .  $hour . '</strong>';
    }
?>
</div>

Come vedi recuperiamo il testo da scrivere prima della data sempre utilizzando il metodo get(), in seguito scriviamo la variabile $date che abbiamo valorizzato nel file mod_time.php grazie al metodo getDate.

In seguito verifico il valore del parametro “ora” se impostato su 1 (TRUE), scrivo il valore del parametro testo_prima_dell_ora e della variabile $hour precedentemente valorizzata nel file mod_time.php.

Pronto per l’installazione?

Ora non ci rimane altro da fare che zippare la cartella mod_time. Dal pannello amministrativo di Joomla andiamo su Estensioni – Installa/Disinstalla e quindi carichiamo il pacchetto. Una volta installato, attiviamolo e configuriamolo dalla gestione moduli.

Download

Conclusione

In questo articolo abbiamo creato un modulo per Joomla molto semplice, tuttavia abbiamo toccato tutti gli aspetti che occorre conoscere se vogliamo realizzare questo tipo di script.
In realtà abbiamo anche visto (senza mai nominarlo) un esempio del paradigma MVC sul quale Joomla, come la maggior parte delle grandi applicazioni, è basato.
Ora… manca solo la guida sulla realizzazione dei componenti. Ok, ci faccio un pensierino. Intanto dimmi: hai già sviluppato-modificato un modulo? Hai già avuto necessità di un modulo ma non lo hai trovato e ti avrebbe dunque fatto comodo saperlo sviluppare?

Tag: ,

L'autore

Maurizio è sposato con la triade PHP - MySql - Apache e, non pago, ha un'amante chiamata jQuery. Ha un blog dove cerca di descrivere nei minimi particolari sia la moglie che l'amante. La sua vera specialità è la realizzazione di gestionali complessi anche se non rifiuta mai un sito web. +

Sito web dell'autore | Altri articoli scritti da

Articoli correlati

Potresti essere interessato anche ai seguenti articoli:

21 commenti

Trackback e pingback

Non ci sono trackback e pingback disponibili per questo articolo