Creare plugin per Joomla 1.5

scritto da Federico Capoano

In questo articolo vedremo come sviluppare un plugin per Joomla 1.5.

Come risultato avremo un plugin molto semplice, infatti l’articolo non si propone come obiettivo quello di svlippuarne uno complesso, ma di illustrare a chi si sta avvicinando da poco al core di Joomla le basi della creazione di plugin.

Che cos’è un plugin e a cosa serve?

Nel framework di Joomla 1.5 per plugin si intende una parte di codice che viene eseguita in un determinato momento del caricamento della pagina o ad una determinata azione dell’utente

La possibilità di eseguire del codice in un determinato momento, a seconda che certe condizioni si verifichino o meno, ci da la possibilità di estendere le funzionalità di Joomla, aggiungendo caratteristiche e operazioni che ci aiutano a risolvere determinati problemi, come ad esempio migliorare l’usabilità del sito aggiungendo delle informazioni ai contenuti, ma anche operazioni più complesse come migliorare le performance, effettuare il caching o un backup del database.

L’unico limite a questa estensibilità sono la nostra fantasia, la nostra abilità nella programmazione con PHP e della conoscenza di Joomla.

Possiamo osservare i plugin installati di default in Joomla andando in “Estensioni” > “Gestione Plugin” nel backend del nostro sito Joomla

Potenza e pericolosità di un plugin

Un plugin è uno strumento che può essere molto potente ed utile per il nostro sito Joomla.

Proprio per questo motivo dobbiamo essere cauti non solo nel realizzarne uno ma anche nell’utilizzare quelli che sono installati sul nostro sito:
un plugin che non viene scritto tenendo a mente le performance e/o peggio ancora bypassando il framework di Joomla può essere dannoso e/o rischioso per un sito Joomla.

Esaminiamo i due possibili problemi principali:

Perdita di performance

Se un plugin effettua molte query in modo inefficiente al database o esegue cicli molto lunghi utilizzando funzioni di PHP che consumano molte risorse il risultato potrebbe rallentare sensibilmente il caricamento del sito.

Se un plugin con dei difetti come quelli appena descritti venisse eseguito ad ogni caricamento di pagina in un sito ospitato su un’hosting condiviso, come ad esempio Aruba, lo stress potrebbe ripercuotesi su tutti i siti ospitati sullo stesso server e in alcuni casi questo potrebbe risultare in un interruzione del servizio nei confronti del sito che ospita lo script difettato.

Problemi di sicurezza e compatibilità

Un plugin che contiene codice non conforme al framework di Joomla rischia di compromettere la sicurezza del nostro sito, per spiegare questo aspetto molto importante farò un esempio abbastanza elementare:

Se un programmatore con poca esperienza dovesse recuperare il contenuto di una variabile nella query string con PHP e quindi volesse visualizzarla nella pagina probabilmente utilizzerebbe un codice del genere:

 
<?php $variabile = $_GET["variabile"]; ?>
<p>La variabile nella query string &egrave; <?=$variabile ?></p>
 

Questo codice contiene una falla di sicurezza e un possibile problema di compatibilità:

Una variabile proveniente dall’esterno va sempre controllata e filtrata prima di essere eseguita o visualizzata. Non farlo significherebbe aprire delle falle in cui un attaccante potrebbe divertirsi a provare gli attacchi che vengono effettuati più comunemente sul web: SQL Injection, Php Injection ed Cross Site scripting per esempio.

Inoltre gli short-hand tags possono costituire un problema di compatibilità sui server che utilizzano molti linguaggi di programmazione e che quindi li disabilitano per evitare ambiguità con gli altri linguaggi.

Il framework di Joomla fornisce delle classi, metodi e funzioni che risolvono tutti i problemi di routine della programmazione di applicazioni in PHP e sconsiglia vivamente l’uso di short hand tags.

Riscriviamo quindi il codice scritto poco fa integrandolo in Joomla evitando così problemi di sicurezza e compatiblità:

 
<?php $variabile = JRequest::getString( "variabile", NULL ); ?>
<p>La variabile nella query string &egrave; <?php echo $variabile ?>
 

Questo codice fa uso del metodo statico getString della classe JRequest del framework di Joomla, che ci permette di recuperare il contenuto di una variabile nell’array superglobale $_REQUEST (che contiene a sua volta anche $_GET, $_POST e $_COOKIE). Questo metodo controlla ed elimina eventuale codice HTML o PHP contenuto nella variabile e restituisce il contenuto ripulito.

Noterete anche che la variabile viene stampata sullo schermo utilizzando

 
<?php echo $variabile ?>
 

invece che il vecchio

 
<?=$variabile ?>
 

Questo permetterà al nostro script di essere eseguito su tutti i server e di non causare problemi di compatibilità. Inoltre dal mio punto di vista seguendo questa convenzione si riesce a scrivere un codice più leggibile.

La classe JRequest contiene altri metodi utili per recuperare variabili dall’array superglobale $_REQUEST e per prevenire possibili attacchi, per approfondire l’argomento vi consiglio la lettura dell’articolo Preventing SQL Injections.

Tipologie di Plugin

Joomla viene distribuito con certo numero di tipologie di plugin definite core.
Queste tipologe sono raggruppate nella cartella /plugins/ di ogni installazione Joomla e sono le seguenti:

• authentication: per estendere l’autenticazione
• content: per effettuare controlli o inserire funzionalità nei contenuti
• editors: per realizzare editor
• editors-xtd: per le estensioni degli editor
• search: per estendere le funzionalità di ricerca
• system: per far eseguire codice in vari momenti del caricamento del framework
• user: per estendere le funzionalità degli utenti
• xmlrpc: per estendere l’interattività con altri servizi web (ad es:Desktop remoti)

Ogni tipologia di plugin serve a svolgere delle funzionalità diverse.
I plugin della tipologia “authentication” (autenticazione) svolgeranno sicuramente delle operazioni molto diverse da quelli della tiplogia “search” (ricerca): per permettere ciò Joomla mette a disposizione a ciascuna tipologia di plugin una serie di eventi. Gli eventi nono sono altro che diversi momenti o appunto eventi che si susseguono nel caricamento del framework di Joomla. È possibile quindi eseguire del codice in ognuno degli eventi che Joomla mette a disposizione per una determinata tipologia di plugin.

Le tipologie sono estensibili, ciò significa che qualora se ne presentasse la necessità sarebbe possibile creare una nuova tipologia di plugin. Solitamente questo accade quando si sviluppa un componente che ha degli eventi personalizzati e che ha bisogno di effettuare certe operazioni all’esecuzione di questi eventi.

Eventi a disposizione per ogni tipologia di plugin

Authentication:

• onAuthenticate

Content:

• onPrepareContent
• onAfterDisplayTitle
• onBeforeDisplayContent
• onBeforeContentSave (aggiunto nella versione 1.5.4)
• onAfterContentSave (aggiunto nella versione 1.5.4)

Editors:

• onInit
• onGetContent
• onSetContent
• onSave
• onDisplay
• onGetInsertMethod

Editors XTD (Extended):

• onDisplay

Search:

• onSearch
• onSearchAreas

System:

• onAfterInitialise
• onAfterRoute
• onAfterDispatch
• onAfterRender

User:

• onLoginUser
• onLoginFailure
• onLogoutUser
• onLogoutFailure
• onBeforeStoreUser
• onAfterStoreUser
• onBeforeDeleteUser
• onAfterDeleteUser

XML-RPC:

• onGetWebServices

Sviluppiamo finalmente il nostro plugin: “Aboutme”

Dopo questa lunga (ma importante) panoramica sui plugin possiamo finalmente iniziare a sviluppare un semplice plugin della tipologia “content” che ci aiuterà a inserire qualche informazione su di noi ogni volta che inseriremo la stringa {aboutme} in un contenuto di Joomla.

Files necessari

Il numero di files minimi necessari per la creazione di un plugin sono due:

• aboutme.php
• aboutme.xml

Nel nostro caso ci limiteremo a questi due soli files. Nel caso avessimo avuto bisogno di più files avremmo potuto creare una cartella “aboutme/” in cui collocare gli altri files (che potrebbero essere files php, immagini o javascript), specificando la cartella aggiuntiva nel file aboutme.xml.

aboutme.php

Nel file aboutme.php inseriremo il codice che verrà eseguito all’evento “onPrepareContent”, ossia prima che il contenuto di un articolo (o di un modulo) venga stampato. Questo ci permetterà di trovare eventuali occorrenze della stringa {aboutme} e di sostiturila con del codice html che da qualche breve informazione a proposito di noi.

Queste brevi informazioni inserite da noi stessi saranno gestibili dal pannello di controllo del plugin.

Inoltre potremo scegliere la classe css da applicare al testo mentre nei “parametri avanzati” avremo la possibilità di decidere quale tag utilizzare (tra blockquote, p e div) per contenere il testo e se effettuare l’escape con la funzione HTML entities di php oppure no.

 
<?php
/**
* @version 1.0
* @name About Me
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
* Plugin per Joomla 1.5 che inserisce alcune informazioni ad ogni occorrenza della stringa {aboutme}
* Per maggiori informazioni visitare http://www.joomlashow.it/guide/sviluppo-estensioni/creare-un-plugin-per-joomla-1.5/
*/
 
// impediamo l'accesso diretto allo script
defined( '_JEXEC' ) or die( 'Restricted access' );
 
jimport( 'joomla.plugin.plugin' );
 
// Creiamo una la classe del nostro plugin estendendo la classe Jplugin ed ereditando tutti i suoi metodi
class plgContentAboutme extends JPlugin
{
 
  /**
   * Costruttore
   * Chiamiamo il costruttore della classe genitrice per inizializzare il plugin
   */
  function plgContentAboutme( &$subject, $params )
  {
    parent::__construct( $subject, $params );
  }
 
  /**
   * Aboutme prepare content method
   *
   * Questo metodo viene chiamato da Joomla prima che il contenuto viene visualizzato
   *
   * @param   oggetto contenente l'articolo    The article object.  Note $article->text is also available
   * @param   oggetto contenente i parametri del plugin
   * @limitstart   il numero di pagina, a noi questo non interessa qui
   */
  function onPrepareContent( &$article, &$params, $limitstart )
  {
    global $mainframe;
 
        // Se il plugin è attivato e se viene trovata la stringa {aboutme} all'interno del contenuto
      if ($this->params->get( 'enabled', 1 ) && strripos($article->text, "{aboutme}") !== false) {
 
            // Recupero il testo da inserire
            $about_text = $this->params->get('about_text', NULL);
 
            // Controllo HTML
            if(intval($this->params->get('htmlentities', NULL)) == 1) $about_text = htmlentities($about_text, ENT_QUOTES);
 
            // Recupero il tag selezionato
            $tag = $this->params->get('tag', 'blockquote');
 
            // Recupero la classe css
            $class = $this->params->get('css_class', NULL);
            // Se la classe è vuota non ho bisogno di inserire l'attributo class
            $output = ($class != '') ? ' class="'</span>. <span style="color: #0000ff;">$class .'"' : "" ;
 
            // Inserisco il testo dentro il tag con la relativa classe
            $about_text = '<' . $tag . $output .'>' . $about_text . '</' . $tag . '>';
 
            // Rimuovo eventuale tag <p> inserito automaticamente dall'editor
            $article->text = str_replace("<p>{aboutme}</p>", "{aboutme}", $article->text);
 
            // Effettuo la sostituzione finale
            $article->text = str_replace("{aboutme}", $about_text, $article->text);
 
            return true;
      }
      else return false;
  }
}
 

Anche se i commenti nel codice sono abbastanza espliciti, è necessario fare delle precisazioni:

per convenzione il nome della classe deve essere: plg + Tipologia plugin (prima lettera maiuscola) + Nome plugin (prima lettera maiuscola), quindi nel nostro caso plgContentAboutme.

La prima funzione della classe è il costruttore che per retrocompatibilità con php4 deve avere lo stesso nome della classe. Se avessimo voluto scrivere un plugin non retrocompatibile e quindi disegnato per php 5 (o superiore) avremmo potuto semplicemente utilizzare “__constructor”

In questo caso il costruttore è stato inserito solo come esempio teorico: noterete infatti che non esegue nessuna operazione e può essere cancellato.
Se avessimo voluto effettuare alcune operazioni anche nel caso la stringa {aboutme} non fosse stata trovata avremmo potuto inserire le istruzioni nella funzione costruttore ed in quel caso il codice sarebbe stato eseguito ad ogni caricamento della pagina (tenere sempre a mente ciò che si è detto a proposito delle performance).

Avremmo potuto utilizzare anche un tipo di programmazione procedurale evitando di scrivere una classe, ma dato che gli sviluppatori del framework di Joomla raccomandano di seguire questo paradigma è bene seguire il loro consiglio. Inoltre giocare con questo tipo di codice ci abitua al design strutturato a oggetti di tutte le moderne applicazioni web (e non solo web).

aboutme.xml

Il file aboutme.xml è necessario per l’installazione del plugin e per la gestione dei parametri.

 
<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
  <name>About Me</name>
  <author>Federico Capoano</author>
  <creationDate>February 2009</creationDate>
  <license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
  <authorEmail>info[chiocciola]joomlashow.it</authorEmail>
  <authorUrl>www.joomlashow.it</authorUrl>
  <version>1</version>
  <description>Visualizza dele informazioni ad ogni occorrenza della stringa {aboutme}</description>
    <files>
        <filename plugin="aboutme">aboutme.php</filename>
    </files>
    <params>
        <param name="about_text" type="textarea" rows="8" cols="35" default="" label="Testo" description="Scrivi le informazioni che verranno aggiunte al posto della stringa {aboutme}." />
        <param name="css_class" type="text" default="" label="Classe CSS" description="Specifica una classe CSS per il tag contenitore." />
    </params>
    <params group="advanced">
        <param name="tag" type="list" default="1" label="Tag contenitore" description="In quale tag vuoi racchiudere il tuo testo">
            <option value="blockquote">Blockquote</option>
            <option value="p">Paragrafo</option>
            <option value="div">Div</option>
        </param>
        <param name="htmlentities" type="radio" default="0" label="Escape HTML" description="Specifica se vuoi che il testo inserito venga processato con la funzione htmlentities di PHP">
            <option value="0">Disattivato</option>
            <option value="1">Attivato</option>
        </param>
    </params>
</install>
 

Spiegherò brevemente il significato generale dei tags:

• <install version=”1.5″ type=”plugin” group=”content"></strong> questo tag indica all’installer di joomla 1.5 che il pacchetto è un plugin della tipologia "content"</li>
  <li><strong><name></strong>: nome del plugin</li>
  <li><strong><author></strong>: nome dell’autore del plugin</li>
  <li><strong><creationDate></strong>: data creazione del plugin, appare nel backend</li>
  <li><strong><license></strong>: licenza con cui viene distribuito il plugin, tag opzionale</li>
  <li><strong><authorEmail></strong>: data creazione del plugin, appare nel backend</li>
  <li><strong><authorUrl></strong>: sito dell’autore, appare nel backend</li>
  <li><strong><version></strong>: versione del plugin, appare nel backend</li>
  <li><strong><description></strong>: descrizione del plugin, appare al momento dell’installazione</li>
  <li><strong><files></strong>: contiene altri tag che definiscono i files del plugin, serve all’installer di Joomla</li>
  <li><strong><filename plugin="aboutme">aboutme.php</filename></strong>: indica che il file php del plugin è aboutme.php</li>
  <li><strong><params></strong>, <strong><params group="advanced"></strong>: parametri del plugin</li>
  </ul>
  <blockquote class="note”>Se avessimo avuto bisogno di una cartella contenente altri files avremmo dovuto specificare i files nella sezione <files> dell’xml:

   
  <files>
      <filename plugin="aboutme">aboutme.php</filename>
      <filename>aboutme/aboutme.css</filename>
      <filename>aboutme/aboutme.js</filename>
  </files>
   

  Parametri del plugin

  Per aggiungere dei paramtri 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 "Parametri avanzati".</p>
  <p style="text-align: center;”>

  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;

  Installazione del plugin

  Il nostro plugin è finito e non ci resta che installarlo e provarlo.

  Per fare questo prima di tutto creiamo un archivio zip contenente i nostri due file e chiamiamolo plugin-aboutme.zip (il nome qui non ha importanza, potete scegliere qualsiasi altro nome preferiate).

  Andiamo nel backend del nostro sito joomla e clicchiamo su “Estensioni” dal menu superiore e quindi su “Installa/Disinstalla”.

  

  Scegliamo quindi 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.

  

  Clicchiamo di nuovo quindi su “Estensioni” e dopodichè andiamo in “Gestione plugin”.
  Noteremo quindi il nuovo plugin About Me, apriamolo, attiviamolo e modifichiamo i parametri.

  Scriviamo il testo che vogliamo far apparire al posto della stringa {aboutme} nella textarea del parametro testo del nostro plugin.

  

  Inseriamo quindi la famosa stringa {aboutme} in un qualsiasi articolo o contenuto statico del nostro sito e apriamo l’url dello stesso per verificarne il funzionamento.

  

  Et voila! la stringa {aboutme} viene sostituita dal testo inserito nel backend!

  Conclusione

  Ora non vi rimane che sperimentare e giocare con questo codice per creare dei plugin più complessi.

  Per essere in grado di sviluppare plugin più complessi dovreste conoscere più a fondo il framework di Joomla e il funzionamento dei plugin.
  Seguendo questi links potrete trovare altre informazioni utili per approfondire le vostre conoscenze:

  • Joomla 1.5 API Reference – qui troverete il riferimento ufficiale delle API del framework d Joomla 1.5 (in inglese)
  • How to Create a Joomla! Plugin – articolo sul blog degli svlippatori di Joomla (in inglese)
  • How to create a content plugin – articolo nella documentazione ufficiale di Joomla 1.5 (in inglese)
  • Creazione di un plugin per joomla 1.5 – traduzione del precedente in Italiano

  Qui invece potrete trovare i files usati nell’articolo: plugin-aboutme.zip

  Fonte : Qua