Liberamente tradotto dalla wiki di Joomla.org, il testo ufficiale che spiega passo per passo seriamente il modo migliore per creare il proprio primo componente. Posso dirmi fiero di aver tradotto la prima vera guida in italiano, anche e sopratutto perchè non bocciando gli altri, spiega tutto assai meglio, essendo stata scritta dai creatori di Joomla!.
Buona lettura
Introduzione
La struttura di un framework è la base di una applicazione che può essere usata da un sviluppatore. La struttura in Joomla! 1.5 è davvero molto potente. In Joomla! il codice è stato completamente ispezionato e pulito. Questo tutorial ti guiderà attraverso il processo di sviluppo di un componente che usa un framework.
Lo scopo di questo progetto sarà sviluppare un semplice componente "Hello World!". Nei prossimi tutorial, questa semplice struttura sarà ampliata per mostrare il potere e la versatilità del pattern MVC in Joomla!
Requisiti
Il pacchetto Joomla alla versione 1.5 o maggiore
Introduzione al Model-View-Controller
Mentre l'idea dietro ad un componente può sembrare estremamente semplice, il codice può divenire rapidamente molto complesso all'aggiunta di caratteristiche supplementari o di una interfaccia personalizzata.
Model-View-Control (d'ora in poi MVC) è un pattern che può essere usato per organizzare il codice in modo che la logica della costruzione e i dati siano separati. La premessa dietro a questo approccio è che se la logica della costruzione è raggruppata in una sezione, poi l'interfaccia e l'interazione utente che circondano i dati possono essere revisionate e personalizzati senza dovere riprogrammare le logiche di costruzione
Ci sono tre parti principali in un componente MVC. Qui sono descritte in breve, ma per ulteriori chiarimenti potete utilizzare i link alla fine di questa guida.
Model
Il Model (o modello) è la parte del componente che gestisce i dati. Offre la possibilità di maneggiare questi dati in moltissimi modi oltre al solo recupero dei dati dalle routine. Nel nostro caso, il model conterrà metodi per aggiungere, rimuovere ed aggiornare informazioni sui "Saluti" nel database. Conterrà anche un metodo per recuperare gli stessi "Saluti" dal database. In generale, i dati fondamentali dovrebbero tutti essere immessi nel Model. Così' se hai bisogno di cambiare delle informazioni riguardanti i dati nel tuo componente potrai riferirti semplicemente al Model e non al Control o alla View
View
La View è la parte del componente che è usata per prendere i dati dal Model così che possa darci l'interazione. Per una applicazione Web-Based, la View generalmente sarebbe una pagina HTML che presenta dei dati. La View raccoglie dati dal modello (che le raccoglie dal controller) ed immette i dati nel template presentandoli all'utente. La view non modifica i dati in alcun modo, può solo presentarli all'utente.
Controller
Il controller è responsabile delle azioni degli utenti. Nel caso di una web-application, un'azione di utente causa una richiesta di pagina. Il controller determinerà che richiesta è, usando il model per manipolare i dati e passandoli poi alla view. Il controller non espone i dati nel modello, comanda i metodi nel modello che cambia i dati, e poi passa il modello nella view che li espone.
L'implementazione di MVC in Joomla![/u]
In Joomla! l'implementazione dell'MVC è avvenuta con tre classi: JModel, JView(link), JController(link). Per ulteriori informazioni su queste Classi puoi fare riferimento alle alla documentazione sulle API (WIP)
Creazione di un componente
Per un componente base si abbisogna di cinque file:
+ sito/hello.php - Punto di entrata del tuo componente
+ sito/controller.php - Questo file contiene la base del controller
+ sito/views/hello/view.html.php - Questo file cattura i file necessari da mandare poi al template
+ sito/views/hello/tmpl/default.php - Questo è il template di output
+ hello.xml - Questo file XML serve a dire a Joomla come installarlo e a fornire poche e incisive informazioni su di esso
E' sempre saggio dare al nome del file di entrata del tuo componente lo stesso nome del componente stesso. Per esempio se il tuo componente si chiama "Marò_ma _com'è intricato_sto_componente" nel momento dell'installazione Joommla guarderà in Hello.xml scrivendo quindi maromacomeintricatostocomponente, diversamente, non funzionerà.
I caratteri speciali come ad esempio gli underscore "_" hanno un significato speciale anche per Joomla! sarebbe quindi ancor più saggio evitarlo nei nomi dei componenti e negli archivi.
la cartella del sito è nella cartella components che è si può trovare nel front end.
Creare un Punto d'Entrata
Joomla! ha sempre solo un punto d'entrata. Index.php per l'entrata comune del sito e administrator/index.php per entrare nella parte amministrativa.
Per l'applicazione che deve mostrare il tuo componente l'URL è definita dai dati POST. Per il nostro componente quindi l'url sarebbe
index.php?option=com_hello&view=hello
questo link fa partire il singolo punto d'entrata del tuo componente che è situato in realtà in: components/com_hello/hello.php.
il codice di questo file è abbastanza tipico nei componenti:
sito/hello.php
<?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* components/com_hello/hello.php
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/
// No direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
// Require the base controller
require_once( JPATH_COMPONENT.DS.'controller.php' );
// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
$path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
if (file_exists($path)) {
require_once $path;
} else {
$controller = '';
}
}
// Create the controller
$classname = 'HelloController'.$controller;
$controller = new $classname( );
// Perform the Request task
$controller->execute( JRequest::getVar( 'task' ) );
// Redirect if set by the controller
$controller->redirect();
la prima riga di codice riguarda il solito controllo di sicurezza che non permette ad un file di essere eseguito al di fuori di Joomla!
JPATH_COMPONENT è la path assoluta di un componente, in questo caso di components/com_hello. Se hai bisogno di specificare che si tratti della parte Front End devi usare JPATH_COMPONENT_SITE se invece è l'amministrazione, devi usare JPATH_COMPONENT_ADMINISTRATOR:
DS invece è il separatore di cartelle del sistema: un '/' o '\' viene assegnato automaticamente dal Framework, così lo sviluppatore non deve preoccuparsi delle diverse versione del sistema operativo. DS si dovrebbe comunque usare sempre per i file residenti sul server.
Dopo aver caricato il controller di base, bisogna cointrollare di quale specifico controller abbisogna, il controller base è l'unico controller e lo lasceremo per usi futuri.
JRequest:getVar() cerca le variabili negli URL o nei POST data. Se la tua URL è index.php?option=com_hello&controller=controller_name possiamo recuperare il nome del controller nel componente usato con: echo JRequest::getVar('controller');
Ora abbiamo il nostro controller di base in "HelloController" in com_hello/controller.php, ma se hai bisogno di un ulteriore controller puoi chiamarlo "HelloControllerController1" in com_hello/controllers/controller1.php. Usando questo schema potrai facilitare le cose in questo modo:'{Componentname}{Controller}{Controllername}'
Dopo che il controller è stato creato ci basta dirgli cosa deve fare come definito nell'url: index.php?option=com_hello&task=sometask. Se non gli è stata assegnata nessuna funzione assume una funzione di visualizzazione. Quando sarà mostrata, la variabile decidera cosa mostrare, le altre comuni operazioni saranno salvataggio, edit e nuovo...
E' probabile che il controller decida di ricaricare la pagina, di solito dopo un comando come "salva". Quest'ultimo stato si cura del redirezionamento.
il primo punto d'entrata (hello.php) essenzialmente passa i controlli al Controller, per eseguire le operazioni richieste.
Hai notato che il tag php "?>" non viene utilizzato in questo file? La ragione consiste nel fatto che omettendolo evitiamo gli spazi bianchi nel codice. Questa pratica è stata definita in Joomla 1.5 è sarà utilizzata in tutti i file che contengono solo codice php.
Creare il Controller
Questo componente ha un solo compito - Salutare il mondo! Per questo motivo il controller sarà molto, molto semplice dato che non è richiesta nessuna iterazione con i dati. Tutto quello che c'è da fare è sulla View. Avremo soltanto un metodo nel nostro controller: display(). La maggior parte delle funzionalità richieste sono contenute nella classe JController, così non dovremo fare altro che invocare il metodo Jcontroller::display()
[
<?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/
// No direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport('joomla.application.component.controller');
/**
* Hello World Component Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HelloController extends JController
{
/**
* Method to display the view
*
* @access public
*/
function display()
{
parent::display();
}
}
Il costrutto JController è sempre registrato da display() è il suo compito, a meno che non gli se ne assegni uno differente (usando il registerDefaultTask() il metodo) sarà predefinito
Il metodo display() non è veramente necessario per invocare il costruttore principale. Comunque, è un buon indizio visuale per indicare quello che sta accadendo nel controller.
Il metodo JController::display () determinerà il nome della view e configurazione dalla richiesta e la caricherà configurandola.Quando crei un collegamento dal menù per il tuo componente, Il menù manager permetterà di selezionare la view più appropriata e di configurarla. Una view si riferisce ad una prospettiva di un certo set di dati di solito (i.e. un elenco di macchine, un elenco di eventi, una sola macchina un solo evento). E' sul Layout che le View si organizzano.
Nel nostro componente, noi avremo una sola view chiamato Hello, ed un solo Layout (default).
Creiamo la View
Le operazioni della View sono davvero molto semplici: Raccoglie i dati e li visualizza dentro un template. Per essere visualizzati nel template utilizzano il metodo JView::assignRef.
di seguito il codice di sito/views/hello/view.html.php:
<?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport( 'joomla.application.component.view');
/**
* HTML View class for the HelloWorld Component
*
* @package HelloWorld
*/
class HelloViewHello extends JView
{
function display($tpl = null)
{
$greeting = "Hello World!";
$this->assignRef( 'greeting', $greeting );
parent::display($tpl);
}
}
Creiamo il Template
il template/layout di Joomla! è un normalissimo file Php che utilizza il layout per raccogliere i dati diretti alla view in maniera particolare. Le variabili assegnate dal metodo JView::assignRef
Le variabili assegnate dal metodo JView::assignRef danno accesso al template che usa $this->{propertyname} (guarda l'esempio riportato sotto per una maggiore comprensione
<?php
// No direct access
defined('_JEXEC') or die('Restricted access'); ?>
<h1><?php echo $this->greeting; ?></h1>
Wrapping It all up - Creazione di Hello.xml
E' possibile installare a mano un componente copiando i file tramite un client ftp e caricando le tavole del database. E' più efficiente ancora però creare un Installer che permette appunto al Joomla! Installer di fare questo per te!
Descrizioni basilari del componente ad esempio il nome e altre descrizioni opzionali come il copyright e le informazioni di licenza.
la lista dei file da copiare
Opzionale, file Php che permette installazioni addizionali o disinstallazioni
Opzionale, File Sql contenente le queries del database da eseguire in fase di installazione/disinstallazione
Il formato XML del file hello.xml è il seguente:
<?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>
<!-- The following elements are optional and free of formatting constraints -->
<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>
<!-- The version string is recorded in the components table -->
<version>1.01</version>
<!-- The description is optional and defaults to the name -->
<description>Description of the component ...</description>
<!-- Site Main File Copy Section -->
<!-- Note the folder attribute: This attribute describes the folder
to copy FROM in the package to install therefore files copied
in this section are copied from /site/ in the package -->
<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>
<administration>
<!-- Administration Menu Section -->
<menu>Hello World!</menu>
<!-- Administration Main File Copy Section -->
<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
</files>
</administration>
</install>
Guardando bene il codice, ti renderai conto che ci sono dei file che vengono copiati di cui non abbiamo parlato. Questo file è Index.html. l'index.html si piazza nella directory per impedire che un utente dando il link completo ad una directory contenente un componente possa vedere la lista dei file.
Per prevenire questa cosa, basta quindi creare l'index.html inserendo una semplice riga
<html><body bgcolor="#FFFFFF"></body></html>
questo semplice codice mostra una pagina bianca.
l'altro file è Hello.php. Questo è il punto d'entrata del componente dall'amministrazione. se non hai una sezione amministrativa del componente, può contenere la pagina bianca.
Mi spiace dirlo, ma questa guida, essendo scritta dagli stessi creatori di Joomla è certamente la più chiara...spero di aver fatto felice qualcuno!
Francesco
