Sviluppare un modulo per Joomla 1.5 seguendo il pattern MVC

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 , , 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">: questo tag indica all’installer di joomla 1.5 che l’archivio zip contiene un modulo</li>
<li><name>: nome del modulo</li>
<li><author>: nome dell’autore del modulo</li>
<li><creationDate>: data di creazione del modulo, appare nel backend</li>
<li><copyright>: copyright, qui volutamente omesso perchè non importante</li>
<li><license>: licenza con cui viene distribuito il plugin, tag opzionale</li>
<li><authorEmail>: data creazione del modulo, appare nel backend</li>
<li><authorUrl>: sito dell’autore, appare nel modulo</li>
<li><version>: versione del plugin, appare nel modulo</li>
<li><description>: descrizione del modulo, appare al momento dell’installazione e nella configurazione del modulo</li>
<li><files>: 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><filename module="mod_helloworld">mod_helloworld.php</filename>: indica che il file principale del modulo è mod_helloworld.php</li>
<li><languages>: 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><params>, <params group="advanced">: 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ì

# 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">.
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 "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>
<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.

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.

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.

Il nostro modulo sarà quindi visibile sul nostro sito!

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.

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

Continue Reading

Previous Convertire vecchie estensioni a Joomla 1.5
Next Guida per creare template per Joomla