Sviluppare un modulo per Joomla 1.5 seguendo il pattern MVC

0

scritto da Federico Capoano

In questo articolo vedremo come sviluppare un semplice modulo che utilizza il pattern di sviluppo MVC (Model View Controller), che permette di separare il codice della struttura dei dati, logica del business, e presentazione.

In cosa consiste il pattern MVC?

Semplificando al minimo il concetto, il pattern MVC permette di ottenere un’architettura che separa il codice nel modo seguente:

  • da una parte il codice che gestisce (recupera, salva, cancella) le informazioni del database (Model)
  • da una parte il codice che gestisce la presentazione dei dati (View)
  • da una parte il codice che gestisce il modo in cui i due livelli precedenti interagiscono, quindi recupero informazioni dal database, calcoli e così via (Controller).

Questo metodo di sviluppo ci da il vantaggio di poter effettuare cambiamenti ad uno dei tre livelli senza rischiare di compromettere gli altri due.

Tutto questo per gli overrides

I moduli di Joomla 1.5 in realtà seguono il pattern MVC solo in parte ed unicamente con lo scopo di ottenere dei moduli che dispongano di “Overrides”, così facendo sarà possibile tenere le modifiche di presentazione (modifiche grafiche) separate dal codice originale del modulo.

Spiegherò questo concetto più avanti nell’articolo

I files contenuti in un modulo di Joomla 1.5

 
mod_helloworld.zip
    /mod_helloworld
        /tmpl
            default.php      (layout)
            index.html        (file index.html vuoto)
        helper.php        (un file "helper" contenente la logica)
        mod_helloworld.php  (il file principale del modulo)
        mod_helloworld.xml  (il file XML di installazione)
        index.html          (file index.html vuoto)
        it-IT.mod_helloworld.ini  (file di lingua italiana)
        en-GB.mod_helloworld.ini  (file di lingua inglese)
 

index.html

Questi due file html vuoti servono per impedire a curiosi malintenzionati di visualizzare la lista dei file contenuti nella directory del modulo, qualora la configurazione del server lo permetta.

helper.php

Questo file contiene la logica del modulo. In questo caso la classe contiene solamente una funzione che server determinare se la scritta “Hello World” deve essere formattata usando un tag <strong>, <em>, <span> oppure nessun tag.
Se avessi voluto sviluppare un modulo più complesso, avrei aggiunto altri metodi a questa classe.

 
<?php
/**
* Mod_HelloWorld Helper
* http://www.joomlashow.it
*/
 
// no direct access
defined('_JEXEC') or die('Accesso ristretto');
 
// la classe helper del nostro modulo
class modHelloWorldHelper
{
    /**
    * Restituisce un tag di formattazione <strong>, <em> o <span>
    */
    function getFormattingTag(&$params, $type = 'open'){
        $tag = $params->get('formatting');
        $close = '';
 
        if(!$tag)
            return '';
 
        if($type != 'open') $close = '/';
 
        return '<'.$close.$tag.'>';
    }
 
}
 

mod_helloworld.php

Questo è il file che contiene le istruzioni che recuperano le informazioni (variabili) da passare alla “view” (tmpl/default.php) e che effettua il controllo sulla presenza di override nella cartella del template in uso, grazie all’istruzione:

 
require(JModuleHelper::getLayoutPath('mod_helloworld'));
 

nel caso in cui nessun override venisse trovato nella cartella del template in uso, Joomla userà quello predefinito del modulo.

 
<?php
/**
* Mod_HelloWorld Helper
* http://www.joomlashow.it
*/
 
// no direct access
defined('_JEXEC') or die('Accesso ristretto');
 
// Includere il file helper.php
require_once (dirname(__FILE__).DS.'helper.php');
 
// definire alcuni parametri nel caso non siano stati già definiti
$params->def('heading', 1);
$params->def('formatting', 0);
 
// recuperiamo il Tag di formattazione
$f_open  = modHelloWorldHelper::getFormattingTag($params);
$f_close = modHelloWorldHelper::getFormattingTag($params, 'close');
 
// attiviamo la funzionalità degli override per il nostro modulo
require(JModuleHelper::getLayoutPath('mod_helloworld'));
 

La “View” (tmpl/default.php)

Nella cartella /tmpl del modulo è presente la “view”, ovvero il file che contiene la presentazione del modulo. Quest’ultimo file può essere sovrascritto con la funzionalità degli override di Joomla che spiegherò in dettaglio in seguito.

 
<?php // no direct access
 
// La nostra "View"
 
defined('_JEXEC') or die('Accesso ristretto'); ?>
<div class="helloworld<?php echo $params->get('moduleclass_sfx'); ?>">
    <?php if($params->get('heading') && $params->get('heading_text') != ''): ?>
    <h3>
        <?php echo $params->get('heading_text'); ?>
    </h3>
    <?php endif; ?>
    <p>
        <?php echo $f_open . JText::_('Hello World') . $f_close; ?>
    </p>
</div>
 

mod_helloworld.xml

Il file mod_helloworld.xml è necessario per l’installazione dei file del modulo e della lingua. Inoltre permette di specificare i parametri in uso.

 
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
  <name>Hello_World</name>
  <author>Federico Capoano</author>
  <creationDate>November 2009</creationDate>
  <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
  <authorEmail>nospam@nospam.com</authorEmail>
  <authorUrl>www.joomlashow.it</authorUrl>
  <version>1.0</version>
  <description>Risultato dell’articolo "Sviluppare un modulo Joomla 1.5 seguendo il pattern MVC" pubblicato su joomlashow.it</description>
 
    <files>
    <filename module="mod_helloworld">mod_helloworld.php</filename>
    <filename>mod_helloworld.xml</filename>
    <filename>helper.php</filename>
    <filename>index.html</filename>
    <filename>tmpl/default.php</filename>
    <filename>tmpl/index.html</filename>
  </files>
 
  <languages>
        <language tag="it-IT">it-IT.mod_helloworld.ini</language>
        <language tag="en-GB">en-GB.mod_helloworld.ini</language>
    </languages>
 
  <params>
    <param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />
    <param name="@spacer" type="spacer" default="" label="" description="" />
 
    <param name="heading" type="radio" default="1" label="PARAMHEADING" description="PARAMHEADING">
      <option value="0">NO</option>
      <option value="1">YES</option>
    </param>
 
    <param name="heading_text" type="text" default="" label="PARAMHEADINGTEXT" description="PARAMHEADINGTEXT" />
 
    <param name="formatting" type="list" default="0" label="PARAMFORMATTING" description="PARAMFORMATTING">
      <option value="strong">strong</option>
      <option value="em">em</option>
      <option value="span">span</option>
      <option value="0">NOFORMATTING</option>
    </param>
  </params>
 
  <params group="advanced">
        <param name="cache" type="list" default="1" label="Caching" description="Select whether to cache the content of this module">
      <option value="0">NEVER</option>
      <option value="1">YES</option>
    </param>
  </params>
</install>
 

Spiegazione sintetica dei tag dell’xml:

  • <install version=”1.5″ type=”module">:</strong> questo tag indica all’installer di joomla 1.5 che l’archivio zip contiene un modulo</li>
    <li><strong><name>:</strong> nome del modulo</li>
    <li><strong><author>:</strong> nome dell’autore del modulo</li>
    <li><strong><creationDate>:</strong> data di creazione del modulo, appare nel backend</li>
    <li><strong><copyright>:</strong> copyright, qui volutamente omesso perchè non importante</li>
    <li><strong><license>:</strong> licenza con cui viene distribuito il plugin, tag opzionale</li>
    <li><strong><authorEmail>:</strong> data creazione del modulo, appare nel backend</li>
    <li><strong><authorUrl>:</strong> sito dell’autore, appare nel modulo</li>
    <li><strong><version>:</strong> versione del plugin, appare nel modulo</li>
    <li><strong><description>:</strong> descrizione del modulo, appare al momento dell’installazione e nella configurazione del modulo</li>
    <li><strong><files>:</strong> contiene altri tag che definiscono i files del modulo, serve all’installer di Joomla per copiare i files dall’archivio zip al server</li>
    <li><strong><filename module="mod_helloworld">mod_helloworld.php</filename>:</strong> indica che il file principale del modulo è mod_helloworld.php</li>
    <li><strong><languages>:</strong> nel caso avessi previsto l’internazionalizzazione del plugin avrei dovuto specificare qui i file INI che contengono le traduzioni per le varie lingue</li>
    <li><strong><params>, <params group="advanced">:</strong> parametri del plugin, spiegherò questo gruppo di tag più avanti nell’articolo</li>
    </ul>
    <h3 class="contentheading contents”>it-IT.mod_helloworld.ini ed en-GB.mod_helloworld.ini

    Questi due files contengono le traduzioni del modulo.

     
    # file lingua italiana
    # mod_helloworld
    # http://www.joomlashow.it
     
    HELLO WORLD=Ciao Mondo
    PARAMHEADING=Mostra intestazione
    PARAMHEADINGTEXT=Testo intestazione
    PARAMFORMATTING=Tag di formattazione
    NOFORMATTING=Nessuna formattazione
    NEVER=Mai
    NO=No
    YES=S&igrave;
     
     
    # english language file
    # mod_helloworld
    # http://www.joomlashow.it
     
    HELLO WORLD=Hello World
    PARAMHEADING=Show heading
    PARAMHEADINGTEXT=Show heading text
    PARAMFORMATTING=Formatting Tag
    NOFORMATTING=No Formatting
    NEVER=Never
    NO=No
    YES=Yes
     

    Per fare in modo che una stringa contenuta nell’xml venga tradotta nella configurazione del modulo, basta scriverla in maiuscolo, ad esempio:

     
    <param name="heading_text" type="text" default="" label="PARAMHEADINGTEXT" description="PARAMHEADINGTEXT" />
     

    la stringa “PARAMHEADINGTEXT” verrà tradotta nelle due lingue secondo il valore contenuto nei nostri due .ini, quindi in lingua italiana con “Testo intestazione” ed in lingua inglese con “Show heading text”

    per tradurre una stringa nel codice php si utilizzano i due metodi statici JText::_() e JText::sprintf, ad esempio:

     
    JText::_('Hello world');
     

    La stringa “Hello world”, verrà tradotta rispettivamente in italiano ed in inglese con “Ciao Mondo” ed “Hello world”.

    Rendere alcune opzioni gestibili da backend: i parametri

    Per aggiungere dei parametri al modulo basta inserire dei tag <param> all’interno dei gruppi <params> o <params group=”advanced"></strong>.</p>
    <p>Generalmente nel gruppo dei parametri avanzati si inseriscono i parametri che potrebbero confondere o spaventare gli utenti meno esperti. Questi parametri infatti vengono visualizzati solamente dopo il click sulla scritta <strong>"Parametri avanzati"</strong>.</p>
    <p style="text-align: center;”>Parametri Modulo & Parametri Avanzati

    Un parametro è strutturato solitamente nel seguente modo:

     
    <param
        name="nomeparametro"
        type="text"
        default="testo di default"
        label="Nome visualizzato nel backend"
        description="Descrizione che appare nel tooltip."
    />
     

    Può essere strutturato in quest’altro modo se contiene delle opzioni:

     
    <param name="nomeparametro" type="list" default="valore di default" label="Nome visualizzato nel backend" description="Descrizione che appare nel tooltip.">
        <option value="0">Disattivato</option>
        <option value="1">Attivato</option>
    </param>
     

    Un parametro può essere dei seguenti tipi:

    • text: da come risultato un box di testo;
    • textarea da come risultato una textarea ed è possibile specificare gli attributi rows e col;
    • list da come risultato una select ed è possibile specificare le option;
    • radio da come risultato dei radio ed è possibile specificare le option;
    • spacer da come risultato una riga vuota che serve da spaziatore;

    Recuperare un parametro nel codice php

    Per recuperare il valore di un parametro in mod_helloworld.php bisogna utilizzare il seguente metodo:

     
    $variabile = $params->get('nostroparametro');
     

    Dove $variabile è la variabile in cui si salva il contenuto del parametro, in questo caso chiamato ‘nostroparametro’.

    Tradurre un modulo in più lingue: aggiungere file di lingua

    I file di lingua precedentemente menzionati:

    • it-IT.mod_helloworld.ini
    • en-GB.mod_helloworld.ini

    verranno copiati dall’installer di Joomla rispettivamente in:

     
    /language
        /it-IT
            it-IT.mod_helloworld.ini
        /en-GB
            en-GB.mod_helloworld.ini
     

    Questo meccanismo è gestito dalla sezione <languages> del file xml:

     
        <languages>
            <language tag="it-IT">it-IT.mod_helloworld.ini</language>
            <language tag="en-GB">en-GB.mod_helloworld.ini</language>
        </languages>
     

    Qualora volessimo supportare un’altra lingua, ad esempio lo spagnolo, bisognerà semplicemente creare un nuovo file .ini contenente la traduzione spagnola delle stringhe e chiamarlo:

    es-ES.mod_helloworld.ini

    per poi aggiungere la seguente istruzione nel file mod_helloworld.xml:

    <language tag=”es-ES">es-ES.mod_helloworld.ini</language></strong></p>
    <pre class="php”> 
    <languages>
    <language tag=“it-IT”>it-IT.mod_helloworld.ini</language>
    <language tag=“en-GB”>en-GB.mod_helloworld.ini</language>
    <language tag=“es-ES”>es-ES.mod_helloworld.ini</language>
    </languages>
     

    Installazione del modulo

    Per installare il modulo creiamo un archivio zip con la struttura presentata all’inizio dell’articolo:

     
    mod_helloworld.zip
        /mod_helloworld
            /tmpl
                default.php      (layout)
                index.html        (file index.html vuoto)
            helper.php        (un file "helper" contenente la logica)
            mod_helloworld.php  (il file principale del modulo)
            mod_helloworld.xml  (il file XML di installazione)
            index.html          (file index.html vuoto)
            it-IT.mod_helloworld.ini  (file di lingua italiana)
            en-GB.mod_helloworld.ini  (file di lingua inglese)
     

    Chiamiamo questo archivio mod_helloworld.zip (il nome qui non ha importanza, potete scegliere qualsiasi altro nome preferite).
    Apriamo il backend del nostro sito Joomla alla pagina di installazione delle estensioni andando su “Estensioni” -> “Installa/Disinstalla” dal menu superiore.

    Gestione Estensioni, installazione modulo

    Selezioniamo il nostro archivio zip e clicchiamo su “Carica file e installa”.
    Riceveremo quindi un messaggio di conferma e il testo contenuto nel tag description del nostro file XML.

    Installazione modulo eseguita correttamente

    Apriamo la configurazione del modulo andando in “Estensioni -> Gestione moduli” e quindi cliccando su “Hello_world”.
    Modifichiamo i parametri a nostro piacimento, attiviamo il modulo, pubblichiamolo in una posizione disponibile nel nostro template e salviamo.

    Configurazione modulo

    Il nostro modulo sarà quindi visibile sul nostro sito!

    Prova, ciao mondo

    Override del modulo

    Ora che abbiamo terminato di sviluppare il modulo testiamo che l’override funzioni correttamente.

    Copiamo i files della cartella “/tmpl” del modulo nella cartella “html/mod_helloworld” del template in uso.

    L’override deve essere posizionato secondo la struttura seguente:

     
    templates/
        nostrotemplate_in_uso/
            html/
                mod_helloworld/
                    index.html
                    default.php
     

    Modifichiamo quindi il file default.php appena copiato nella cartella del template.
    Ad esempio nel modo seguente:

     
    <?php // no direct access
    defined('_JEXEC') or die('Restricted access'); ?>
    <div class="custom_helloworld<?php echo $params->get('moduleclass_sfx'); ?>">
        <?php if($params->get('heading') && $params->get('heading_text') != ''): ?>
        <h1>
            <?php echo $params->get('heading_text'); ?>
        </h1>
        <?php endif; ?>
        <blockquote>
            <?php echo $f_open . JText::_('Hello World') . $f_close; ?>
        </blockquote>
    </div>
     

    Salviamo e controlliamo che le modifiche del nostro override vengano visualizzate al posto della View di default.

    Codice HTML

    Bene, tutto liscio.
    Non mi rimane che fare un breve cenno sulla funzionalità di Caching dei moduli.

    Caching, se opportuno

    Il caching dei moduli viene gestito semplicemente dal parametro “cache”. Davvero semplice, non trovate?
    Il caching viene gestito direttamente dal framework di Joomla, evitando allo sviluppatore del modulo di scrivere codice ulteriore.

    C’è però da fare una precisazione: effettuare il caching di un modulo che cambia il suo contenuto costantemente a seconda di vari fattori può causare risultati inaspettati.

    Spiegherò questo concetto con un esempio:

    Supponiamo che il nostro modulo mostri un saluto all’utente loggato e che il caching per il modulo sia attivo.
    Supponiamo che un utente chiamato “Alessandro” effettui il login e visualizzi quindi il saluto “Ciao Alessandro”, il pezzettino di html contenente il saluto verrà salvato nella cache per essere visualizzato alla prossima richiesta.
    Supponiamo che subito dopo un altro utente chiamato “Marco” effettui il login, cosa succederebbe? L’utente Marco dovrebbe visualizzare “Ciao Marco” ed invece visualizzerà il risultato salvato nella cache precedentemente, cioè “Ciao Alessandro”.

    Se state sviluppando un modulo che potrebbe essere affetto da questo problema la soluzione migliore è lasciare solamente l’opzione “Never” per il parametro caching:

     
        <param name="cache" type="list" default="1" label="Caching" description="Select whether to cache the content of this module">
          <option value="0">NEVER</option>
        </param>
     

    Conclusione

    Ora, oltre che essere in grado di creare semplici moduli personalizzzati per i vostri siti, dovreste essere in grado di modificare l’aspetto grafico dei moduli esistenti tenendo le modifiche separate dai file originali in modo da non compromettere l’aggiornabilità del vostro sito Joomla.

    Qui potrete scaricare il modulo helloworld: mod_helloworld.zip

    Fonte : Qua

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *