Scrivete il vostro modulo

Containers

I moduli sono i contenuti della colonna laterale e i widget. Spesso questi lavorano al di fuori del contenuto esistente nei database. Un esempio potrebbe essere un modulo Ultimi Articoli con una lista dei più recenti articoli aggiunti. In questo capitolo potrete vedere come ottenere il massimo vantaggio da Joomla! sfruttando la struttura di Joomla! contenuta nella cartella libraries/joomla. Joomla! usa oggetti orientati al PHP tanto che quelli che trovate nella cartella libraries/joomla sono file di classi. Includendo queste nel vostro programma lasciate che Joomla! svolga il lavoro pesante per voi.

Joomla! programma per convenzione. Si presuppone che voi strutturerete il vostro programma e nominerete i file e le classi in un certo modo. Questo è un settore dove non si vuole essere troppo creativi.

I moduli di backend sono contenuti nella cartella administrator/modules e i moduli di frontend sono nella cartella moduli. All'interno di queste cartelle, ciascun modulo ha una sua cartella che inizia per mod_.

L'esempio su cui lavoreremo è la Lista Contatti che nell'esempio sarà usata per visualizzare un lista di ramificazioni. Il codice nel file allegato alla fine di questo tutorial. Questo è simile a ciò che il modulo sarà sul frontend:

contact-list-acontact-list-a

Nel backend sarete in grado di selezionare la categoria e come visualizzare molti contatti. (L'immagine del backend usata in questo tutorial è il template amministrativo Hathor).

contact-list-bcontact-list-b

Ci sono sei file principali, alcuni in sottocartelle, nella cartella module/mod_contact_list. Oltre a questi file, ogni cartella dovrebbe contenere un file fittizio index.html.

Percorso File Proposito
modules/mod_contact_list mod_contact_list.xml Definire il modulo e i parametri
modules/mod_contact_list mod_contact_list.php Elaborazione del file principale - il controller
modules/mod_contact_list helper.php Funzioni di supporto per ottenere i dati - il modello
modules/mod_contact_list/tmpl default.php Il codice HTML per la visualizzazione del modulo - la vista
modules/mod_contact_list/language/en-GB en-GB_mod_contact_list.ini File di lingua Inglese
modules/mod_contact_list/language/en-GB en-GB_mod_contact_list.sys.ini File di lingua Inglese per le stringhe di sistema

mod_contact_list.xml

Il file mod_contact_list.xml definisce il modulo, e su quale versione di Joomla! funziona, i file che utilizza e i parametri che sono stati usati. Questo file è necessario per il modulo che deve essere installato. Questa è la prima parte del file che dà una descrizione di base del modulo:

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" version="1.7" client="site" method="upgrade">
   <name>MOD_CONTACT_LIST</name>
   <author>Andrea Tarr</author>
	<creationDate>November 2011</creationDate>
	<copyright>Copyright (C) 2011 Tarr Consulting. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later</license>
	<authorEmail>atarr@tarrconsulting.com</authorEmail>
	<authorUrl>www.tarrconsulting.com</authorUrl>
   <version>1.0</version>
   <description>MOD_CONTACT_LIST_XML_DESCRIPTION</description>

Il tag <extension> definisce il tipo di modulo, la versione minima di Joomla! e se questo modulo è un modulo di frontend (0) o di backend (1). Il metodo "upgrade" indica se viene trovata una cartella del modulo con lo stesso nome, si presume essere una versione precedente dello stesso programma che può essere aggiornato. Se si utilizza "install", qualsiasi cartella duplicata impedirà l'installazione. I tag <name> e <description> sono stringhe di linguaggio che saranno tradotte nel file di lingua. I file di lingua saranno spiegati più avanti in questo tutorial.

La parte successiva elenca i file. Durante l'installazione, questi sono i file che saranno copiati. Se avete file extra nel file zip che state installando, saranno ignorati. Se nella lista del vostro file zip un file non c'è, il modulo non verrà installato.

    <files>
        <filename>mod_contact_list.xml</filename>
        <filename module="mod_contact_list">mod_contact_list.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>

Il file principale chiamante comunica con l'attributo del modulo. Il tag <folder> copierà tutti i file e le sotto-cartelle in quella cartella.

La prossima sessione definisce i parametri che vedete sulla colonna destra nel backend. Questa sezione è racchiusa nel tag <config>. Il gruppo di parametri è in un tag <fields> con il nome attributo di "params". Ciascuna delle schede viene definita con un <fieldset> separato. In primo luogo sono i parametri di Base, dove noi scegliamo la categoria e il numero di articoli:

    <config>
        
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="catid"
                    type="category"
                    extension="com_contact"
                    multiple="true"
                    default=""
                    size="10"
                    label="JCATEGORY"
                    description="MOD_CONTACT_LIST_FIELD_CATEGORY_DESC" >
                </field>

                <field
                    name="count"
                    type="text"
                    default="5"
                    label="MOD_CONTACT_LIST_FIELD_ITEMS_LABEL"
                    description="MOD_CONTACT_LIST_FIELD_ITEMS_DESC" />

            </fieldset>    

Ciascuno dei singoli parametri sono in un tag <field>. Il nome attributo viene usato per ottenere i parametri nel vostro programma. Il tipo di attributo definisce che tipo di campo è questo. Ogni tipo viene definito nella struttura di Joomla!. I tipi più comuni sono usati nel testo, lista, editor, area di testo, categoria, calendario, pulsanti radio, checkbox, media, lista cartella e lista file. Per un elenco completo, vedere http://docs.joomla.org/Standard_form_fie.... Potete anche creare un vostro tipo come spiegato in http://docs.joomla.org/Creating_a_custom.... L'attributo etichetta e descrizione usa stringhe di linguaggio che trovate in entrambi i file globali della lingua o nella specifica estensione dei file di lingua.

I seguenti parametri avanzati sono i parametri di riserva che si dovrebbero mettere su tutti i vostri moduli a meno che non vogliate utenti che abbiano queste capacità standard. Tutti, tranne per il moduleclass_sfx funzionerà automaticamente solo inserendo questo codice. Per far funzionare il moduleclass_sfx avete bisogno di aggiungere <?php echo $moduleclass_sfx; ?> al tag classe nel file layout HTML dove volete consentire all'utente di definire una classe speciale.

            <fieldset
                name="advanced">

                <field
                    name="layout"
                    type="modulelayout"
                    label="JFIELD_ALT_LAYOUT_LABEL"
                    description="JFIELD_ALT_MODULE_LAYOUT_DESC" />

                <field
                    name="moduleclass_sfx"
                    type="text"
                    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
                    description="COM_MODULES_FIELD_MODULECLASS_SFX_DESC" />

                <field
                    name="cache"
                    type="list"
                    default="1"
                    label="COM_MODULES_FIELD_CACHING_LABEL"
                    description="COM_MODULES_FIELD_CACHING_DESC">
                    <option
                        value="1">JGLOBAL_USE_GLOBAL</option>
                    <option
                        value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
                </field>

                <field
                    name="cache_time"
                    type="text"
                    default="900"
                    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
                    description="COM_MODULES_FIELD_CACHE_TIME_DESC" />

                <field
                    name="cachemode"
                    type="hidden"
                    default="itemid">
                    <option
                        value="itemid"></option>
                </field>

            </fieldset>

Terminate il file chiudendo i tag:

        </fields>
    </config>
</extension>

mod_contact_list.php

Il mod_contact_list.php è il file di elaborazione principale per il programma. Funziona come il controller in una struttura del Model-View-Controller. Allo stesso modo separa il contenuto dalla presentazione e comporta l'avere file separati per HTML/CSS/JavaScript, separiamo il controllo dati del programma (model) e la visualizzazione (view). Il file inizia controllando che il file venga chiamato da Joomla! e non direttamente:

<?php
/**
 * Contact List
 * 
 */
 
// no direct access
defined('_JEXEC') or die;

Tutti i vostri file php dovrebbero iniziare con questo codice.

Metteremo il nostro codice di recupero dei dati nel file helper.php, quindi abbiamo bisogno di includere quel file. Questo contiene una definizione classe, quindi dobbiamo utilizzare il require_once. La directory name (_FILE_) porta nel percorso del file corrente in modo che possa essere utilizzata come percorso per il file helper.php. Ricordate che una definizione di classe in realtà non fa nulla nel momento in cui è inclusa.

// Include the class of the syndicate functions only once
require_once(dirname(__FILE__).'/helper.php');

Prossimamente avremo i dati effettuando una chiamata statica alla classe definita nel file helper.php e mettere il risultato nel $list. Il $params è un oggetto che contiene tutti i parametri definiti nel file xml.

// Static call to the class
$list = modContactListHelper::getList($params);

La riga successiva si limita ad un po' di pulizia. Useremo la classe parametro del suffisso modulo nel layout per la costruzione di una classe, quindi vogliamo fare un prima un po' di ritocchi. Mettendolo qui, ci assicuriamo che sia fatto anche se un progettista fa una sovrascrizione template.

$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

Infine, chiamiamo la struttura del processore modulo che verrà messo tutto insieme e passare di nuovo ilcodice HTML da visualizzare in base al file di layout (tmpl/default.php). Dal momento che questo viene fatto così come incluso, tutte le variabili sono ancora in campo.

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

Questa è la fine del file. Non include un tag di chiusura ?>. La pratica di Joomla è quello di saltare tutti i tag di chiusura php perché i caratteri dopo il tag php, includono alcuni caratteri di controllo, attivando l'invio di intestazioni HTML prematuramente, il che provoca errori.

helper.php

Stiamo usando il file helper.php per recuperare i dati. Si inizia il file php nel modo standard:

<?php
// no direct access
defined('_JEXEC') or die;

Vogliamo elencare i contatti nella tabella contatto nella categoria data. Dato che stiamo usando una tabella da un componente che viene definito nel modo standard di Joomla, siamo in grado di utilizzare le definizioni del modello esistente nel nostro programma. Per fare questo abbiamo bisogno di includere la parte della struttura di Joomla! che processa il componente modelli e fa una chiamata statica includendo i modelli da com_contact component.

jimport('joomla.application.component.model');
JModel::addIncludePath(JPATH_ADMINISTRATOR.'/components/com_contact/models', 'ContactModel');

Ora è il momento di definire la definizione della classe stessa. Questa classe non ha proprietà e getList() è l'unico metodo:

class modContactListHelper
{
    /**
     * Retrieves the list of contacts
     *
     * @param array $params An object containing the module parameters
     * @access public
     */    
    public function getList($params)
    {

La funzione inizia dalla ricezione dell'informazione globale, che viene recuperata da una chiamata statica all'Applicazione. Questo è quello che sostituisce il vecchio globale $mainframe dalla programmazione più recente di Joomla!.

		$app	= JFactory::getApplication();

Poi eseguiamo la connessione al database:

		$db		= JFactory::getDbo();

Ora abbiamo bisogno di creare un modello oggetto dai contatti. Noi usiamo una chiamata statica per JModel dicendogli il componente (Contacts) e il prefisso classe (ContactModel). Elaborando il modello definisce gli stati per ricordare in quale stato è il modello (secondo come i filtri sono impostati). Quando state creando un modulo, di solito non volete colpire qualsiasi stato in cui il componente si trova, così ignore_request gli dice di non ricordare lo stato di questa elaborazione.

		// Get an instance of the generic contact model
		$model = JModel::getInstance('Contacts', 'ContactModel', array('ignore_request' => true));

Successivamente impostare i parametri di applicazione del modello:

		$appParams = JFactory::getApplication()->getParams();
		$model->setState('params', $appParams);

Poi dobbiamo impostare i filtri in base ai parametri del modulo. Il list.start è impostato su 0 per iniziare all'inizio e abbiamo fissato la fine in base al conteggio del parametro che abbiamo inserito nei parametri del modulo. Il filter.published impostato su 1 dice soltanto i contatti pubblicati. Il list.select elenca i campi di ritorno.

		$model->setState('list.start', 0);
		$model->setState('list.limit', (int) $params->get('count', 5));
		
		$model->setState('filter.published', 1);

		$model->setState('list.select', 'a.id, a.name, a.catid' . 
				', a.address, a.suburb, a.postcode, a.state, a.telephone ' .
				', a.published, a.access, a.ordering, a.language'.
				', a.publish_up, a.publish_down');

Il filtro successivo è per le ACL per assicurarsi che soltanto i contatti che possono essere visti siano scelti per la visualizzazione.

		$access = !JComponentHelper::getParams('com_contact')->get('show_noauth');
		$authorised = JAccess::getAuthorisedViewLevels(JFactory::getUser()->get('id'));
		$model->setState('filter.access', $access);

Poi dobbiamo filtrare per la categoria basata sul parametro che abbiamo inserito nei parametri del modulo. Notate che questa è un array da quando abbiamo permessi multipli quando definiamo il parametro nel file xml.

		$model->setState('filter.category_id', $params->get('catid', array()));

Gli ultimi filtri sono per la lingua e per impostare l'ordine dei contatti nella lista.

		$model->setState('filter.language',$app->getLanguageFilter());
		$model->setState('list.ordering', 'ordering');
		$model->setState('list.direction', 'ASC');

Infine, abbiamo chiamato il metodo getItems() nell'oggetto $model. Dato che stiamo usando il metodo getItems() da componente contatti non abbiamo bisogno di scriverlo noi. Possiamo usare quello che già esiste. Tutto quello di cui abbiamo bisogno era definire lo stato dei filtri. Poi torniamo alla lista che abbiamo appena recuperato e chiudiamo la funzione e la classe. Notate che di nuovo non bisogna includere un tag php di chiusura.

		$items = $model->getItems();
		      
		return $items;
    }
}

tmpl/default.php

Ora tutto quello che dobbiamo fare è scrivere il codice HTML che visualizzerà l'elenco di informazioni che abbiamo raccolto. Separando il codice HMTL e mettendolo in un file layout nella cartella tmpl (template) consente ai progettisti di usare la sovrascrizione del template per cambiare il codice HTML come serve. Questo file inizia come gli altri file php: con il controllo per essere sicuri che soltanto Joomla! lo ha chiamato.

<?php
/**
 * Contact List Module Entry Point
 */ 

// no direct access
defined('_JEXEC') or die; ?>

Poi mettiamo il codice HTML per visualizzare la lista. E' una buona idea racchiudere tutto in un

con una classe che identifichi il tipo di modulo in modo che i progettisti (o voi) potete aggiungere uno stile per questo modulo. Questo è anche un buon posto per aggiungere il suffisso classe modulo. Mettendo il codice php immediatamente di seguito il tipo di classe del modulo dà al progettista molte più opzioni.

 

<div class="contact_list<?php echo $moduleclass_sfx; ?>">

Infine, creare una lista non ordinata e loop attraverso $list per visualizzare ciascuna delle linee. Dobbiamo poi chiudere il div alla fine del file.

<ul>
<?php foreach ($list as $item) :?>
	<li><h4><?php echo htmlspecialchars($item->name); ?></h4>
	<p><?php echo nl2br(htmlspecialchars($item->address)); ?><br />
	<?php echo htmlspecialchars($item->suburb); ?>, 
	<?php echo htmlspecialchars($item->state); ?> 
	<?php echo htmlspecialchars($item->postcode); ?><br />
	<?php echo htmlspecialchars($item->telephone); ?></p></li>
<?php endforeach; ?>
</ul>
</div>

language/en-GB/en-GB_mod_contact_list.ini

Questo è il file di lingua principale per il modulo. Mettete le chiavi lingua nel vostro programma tutte maiuscole con un prefisso MOD_CONTACT_LIST. Assegnate la stringa lingua che deve essere usata con un segno uguale e le virgolette intorno alla stringa. Questa è una struttura diversa dalla versione 1.5. Questa nuova struttura, molto più veloce, non permette spazi in chiave linguistica. Questo è un file ini, così non dovete usare jexec or die all'inizio.

; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_CONTACT_LIST="Contact List"
MOD_CONTACT_LIST_FIELD_CATEGORY_DESC="Select Contacts from a specific Category or Categories."
MOD_CONTACT_LIST_FIELD_ITEMS_DESC="The number of Contacts to display within this module"
MOD_CONTACT_LIST_FIELD_ITEMS_LABEL="Number of Contacts"
MOD_CONTACT_LIST_XML_DESCRIPTION="The Contact List will display a fixed number of contacts from a specific category or categories."

language/en-GB/en-GB_mod_contact_list.sys.ini

L'ultimo file è il file di lingua sys.ini. Questo file è usato solo sull'installazione e le schermate Update nel backend e necessita soltanto di queste chiavi. Queste due schermate hanno accesso a molte estensioni ognuna delle quali potrebbe avere file di lingua di altre dimensioni. Con l'inclusione di brevi file sys.ini per ogni estensione, le prestazioni sono migliorate.

; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_CONTACT_LIST="Contact List"
MOD_CONTACT_LIST_XML_DESCRIPTION="The Contact List will display a fixed number of contacts from a specific category or categories."
MOD_CONTACT_LIST_LAYOUT_DEFAULT="Default"

index.html

Si dovrebbe mettere un file index.html nella root di ogni cartella/sottocartella nel vostro modulo per impedire al pubblico di essere in grado di ottenere una lista dei file inserendo una directory nella barra degli indirizzi. Il file può essere semplice così:

<!DOCTYPE html><title></title>

Comprimere il Modulo per l'installazione

Dal momento che abbiamo già creato il file xml, l'unica cosa che dovete fare per creare un pacchetto di installazione è comprimere i file e le cartelle presenti nella cartella del modulo. Assicuratevi di zippare le cartelle e i file nella cartella mod_contact_list e di non includerla nella parte superiore dello stesso livello.

Se i file sono già nel sito di Joomla! potete usare la Gestione Estensione Extension/ExtensionManager/Discover per installare invece il modulo. Fate clic sull'icona Discover per cercare i file di estensione che non sono installati. Quando il vostro modulo viene mostrato, fate un segno di spunta sulla casella accanto e fare clic su Installa.

 

Commenti

Ringrazio innanzitutto per la ottima spiegazione,
ho notato un errore installando il componente in joomla 2.5:
i file della lingua
en-GB_mod_contact_list.ini
en-GB_mod_contact_list.sys.ini
vanno rinominati
en-GB.mod_contact_list.ini
en-GB.mod_contact_list.sys.ini

altrimenti non trova la traduzione.

buona giornata!