martedì 12 luglio 2011

Scrivere plugin per Joomla (II parte)

Nell'articolo Scrivere plugin per joomla (I parte) abbiamo visto i vari tipi di plugin presenti in Joomla e i relativi eventi che possono essere utilizzati in ogni classe di plugin. Oggi andremo a scrivere un plugin di prova che chiameremo MyString.

File necessari in un plugin

Il plugin in questione appartiene alla tipologia "content" e ci permetterà di inserire una stringa a piacere ogni volta che inseriremo il segnaposto {mystring} in un contenuto di Joomla.
Il numero di files minimi necessari per la creazione di un plugin sono due:
  1. mystring.php
  2. mystring.xml
Nel nostro caso ci limiteremo a questi due soli file. Ricordiamo che in caso di bisogno, possiamo creare una cartella (nel nostro esempio "mystring") in cui collocare altri file (php, immagini o javascript), specificando la cartella aggiuntiva nel file mystring.xml.

Il cuore del Plugin mystring.php

Nel file mystring.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 {mystring} e di sostiturila con del codice html.

<?php
// impediamo l'accesso diretto allo script
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport( 'joomla.plugin.plugin' );

class plgContentMystring extends JPlugin
{
    /**
    * Costruttore
    * Chiamiamo il costruttore della classe genitrice per inizializzare il plugin
    */
    function plgContentMystring( &$subject, $params )
    {
        parent::__construct( $subject, $params );
    }

    /**
    * MyString 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 {mystring} all'interno del contenuto
        if ($this->params->get( 'enabled', 1 ) && strripos($article->text, "{mystring}") !== 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="'. $class .'"' : "" ;
            // Inserisco il testo dentro il tag con la relativa classe
            $about_text = '<' . $tag . $output .'>' . $about_text . '';
            // Rimuovo eventuale tag inseriti automaticamente dall'editor
            $article->text = str_replace("{mystring}", "{mystring}", $article->text);
            // Effettuo la sostituzione finale
            $article->text = str_replace("{mystring}", $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 plgContentMystring.
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 {mystring} 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.
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).


Il file mystring.xml

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

<install group="content" type="plugin" version="1.5">
<name>My String</name>
<author>Autore</author>
<creationdate>....</creationdate>
<license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
<authoremail>...</authoremail>
<authorurl>....</authorurl>
<version>1</version>
<description>Visualizza dele informazioni ad ogni occorrenza della stringa {mystring}</description>
<files>
<filename plugin="mystring">mystring.php</filename>
</files>
</install>

Nessun commento:

Posta un commento