Realizzare un primo plugin

Si crea un plugin nello stesso luogo in cui si installano quelli che sono già disponibili e pronti da scaricare (Vedi «Installare i plugin»).

Il sistema di plugin si basa sulla ricerca dei percorsi conosciuti in un elenco ben preciso. Gli amanti della tecnica lo chiameranno spip_path (cfr. Dove mettere i file dei modelli?). L’attivazione, o la disattivazione, di un plugin influisce sull’aggiunta della sua cartella associata a questo elenco. Pertanto per realizzare il primo plugin si dovrà creare:

-  Una cartella plugins/ alla radice del sito. La conseguenza diretta di questa azione è attivare l’interfaccia di gestione dei plugin. Il primo sintomo è la comparsa del pulsante «Gestione dei plugin» nel menu «Configurazione» dell’interfaccia privata (solo in modalità interfaccia completa)


-  Una sotto-cartella mio_primo_plugin/ per il plugin che si dovrà scrivere.

Per indicare a SPIP quel che il plugin deve fare, c’è un file di descrizione chiamato plugin.xml, che si crea nella medesima cartella del plugin. Si tratta di un file con una sintassi rigida ma relativamente semplice come questa:

<plugin>
 <nom>Mio primo plugin</nom>
 <version>1.0</version>
 <prefix>demo</prefix>
</plugin>

Si tratta di un file contenente solo i tag obbligatori.

-  Il tag nom può essere internazionalizzato grazie al segnaposto multi (esempio: <nom><multi>My first plugin[fr]Mon premier plugin</multi></nom>). E’ il titolo del plugin.
-  Il tag version è puramente informativo. Non vi è una regola precisa per gestire i numeri di versione. Spetta allo sviluppatore gestire i numeri di versione. In futuro, potrà essere possibile che questo valore sia utile per gestire eventuali dipendenze e un minimo di uniformità tra SPIP e i plugin...
-  Il tag prefix è cruciale. E’ innanzitutto importante assicurarsi dell’unicità di questo valore tra tutti i plugin che avete installato. In secondo luogo, esso definisce il prefisso delle funzioni che andrete a programmare in PHP e che saranno gli elementi motori del plugin. Quindi, se più plugin coabitano con funzioni che gestiscono cose simili sarà impossibile che esse provochino degli errori a causa dei loro nomi. Esso è quel che si chiama anche uno «spazio di nomi».

Benché al momento ciò non produca alcun effetto, questo minimo permette già di attivare il plugin nell’interfaccia:

Per fare ciò, è necessario spuntare la casella di fronte al nome del plugin e cliccare sul pulsante «convalida» in basso. La zona del titolo è in grigio.

Divertitevi a eliminare uno o l’altro di questi tag per constatare che SPIP può indicarvi quel che manca o semplicemente smette di funzionare.

*-*-*

E’ possibile mettere altri elementi in un file plugin.xml:

-  Il tag <etat>: 4 valori possibili. In mancanza di questo tag, o se è presente ma vuoto, il plugin viene considerato come "in via di sviluppo". Il funzionamento del plugin non viene minimamente influenzato dal valore di questo tag. Si deve notare che un simbolo colorato permette di riconoscere a colpo d’occhio lo stato.

statocolore del simbolosignificato
dev nero In via di sviluppo. Numerosi bug possibili. Forse non funziona.
test arancio La funzione principale è operativa e va verificata. Gli sviluppatori contano su di noi per avere commenti su eventuali errori o suggerimenti sull’ergonomia di un’interfaccia grafica, per esempio.
stable verde Completamente operativa. Senza bug, in teoria.
experimental rosso Per chi ama il rischio!

-  I tag <auteur> e <description> sono facoltativi e funzionano come i testi di un articolo (sono permesse le sorciatoie) e servono a fornire delle informazioni succinte sul plugin. Quindi il codice:

<plugin>
 <nom>Mio primo plugin</nom>
 <version>1.0</version>
 <prefix>demo</prefix>
 <etat>dev</etat>
 <auteur>Pinco Pallino [contact->mailto:pallinop@miosito.net]
 _ [mon site->http://www.miosito.net]</auteur>
 <description>Questo plugin &egrave; una dimonstrazione. E' distribuito sotto licenza GNU/GPL</description>
</plugin>

farà visualizzare:

Notare che è necessario trasformare i caratteri accentati in entità HTML. (&egrave; per è, per esempio)

*-*-*

Se allo stesso livello di plugin.xml si mette un file squelette.html, il plugin, una volta attivato, permette di utilizzare il suddetto modello di layout che sarà utilizzabile chiamandolo nel proprio browser con il formato «solito»: vostrosito.net/spip.php?page=squelette. Si tratta di un esempio semplicistico ma comunque un primo esempio di override di file. Questo principio verrà approfondito in un altro tutorial.

*-*-*

Per illustrare questa dimostrazione andremo a realizzare un plugin il cui scopo è di colorare in maniera particolare qualsiasi occorrenza della parola «spip» in un testo. A tal fine andiamo a mettere nella cartella del plugin i 2 file utili e informare SPIP circa i loro nomi, usando alcuni tag supplementari nel file xml:

<plugin>
 <nom>Mio primo plugin</nom>
 <version>1.0</version>
 <prefix>demo</prefix>
 <etat>experimental</etat>
 <auteur>Pinco Pallino [contact->mailto:pallinop@miosito.net]
 _ [mon site->http://www.miosito.net]</auteur>
 <description>Questo plugin &egrave; una dimonstrazione. E' distribuito sotto licenza GNU/GPL</description>
 <fonctions>exemple_fonctions.php</fonctions>
 <options>exemple_options.php</options>
</plugin>

Qui sotto diamo la descrizione dei 2 tag aggiunti

-  <fonctions>: contiene il nome di un file che verrà caricato ad ogni aggiornamento della pagina. E’ l’equivalente per ogni plugin del file mes_fonctions.php. Quindi non viene utilizzato per il sito pubblico poiché viene chiamato solo se si calcola la cache. In tale file si metteranno tipicamente dei filtri o delle definizioni di segnaposti, di criteri.
-  <options>: contiene il nome di un file che verrà caricato ad ogni chiamata di pagina. Equivale al file mes_options.php per ogni plugin. Viene utilizzato anche nell’interfaccia privata ad ogni chiamata di pagina.

Create i 2 file con il contenuto sottostante:

exemple_fonctions.php:

<?php

function colore_spip($texte) {
 global $couleur;
 return preg_replace('/([^(class=")])(spip)/i',
  '$1<span style="color: '.$couleur.';">$2</span>',
  $texte);
}

?>

exemple_options.php:

<?php

$couleur = '#ff017d';

?>

Attenzione! Ci sono nomi di file che è preferibile non utilizzare per i plugin: siamo nel quadro di un elenco di cartelle conosciute e SPIP si ferma sempre al primo file trovato. Se il file del tag <fonctions>, si chiama mes_fonctions.php, ci sarà confusione con il file della propria cartella di modelli di layout, se esiste, e soprattutto se più plugin sono programmati con questo nome di file, il sistema rischia di perdere l’orientamento... lo stesso dicasi per mes_options.php, che si deve riservare alla cartella ecrire/ come pure per i file lingua local_xx.php ai quali si preferirà un altro metodo descritto in un tutorial dedicato all’override di codice.

Quindi: evitate i nomi «comuni» quali mes_fonctions.php e mes_options.php.

In un altro articolo vedremo come fare l’override delle cartelle di SPIP. Sappiate che nomi di cartelle quali «modeles», «formulaires», «inc», «action» ecc... sono da utilizzare cum grano salis.

Infine, è necessario fare attenzione a essere molto precisi nel digitare i nomi di file in plugin.xml, l’interfaccia di gestione è molto capricciosa per l’aggiunta degli ultimi tag (messaggi di errore che fanno piantare il server...)

Insomma, ecco fatto, questo plugin dà un nuovo filtro per i vostri modelli. Provate a mettere [(#TEXTE|colore_spip)] dentro article.html per esempio.

*-*-*

Tutti i plugin si installano nella cartella plugins/, ma è possibile creare delle sotto-cartelle per suddividere i plugin che si installano e che si sviluppano.

Quindi, per l’arborescenza sotto riportata:

plugins/
   |
   |-- mon_premier_plugin/
   |-- mes_raccourcis_supplementaires/
          |
          |-- raccourcis_2/
          |-- raccourcis_3/
   |-- mes_autres_plugins/
          |
          |-- raccourcis_4/
          |-- raccourcis_5/

l’interfaccia di gestione avrà questo aspetto:

Autore Fausto Barbarito Publié le : Mis à jour : 26/10/12

Traductions : català, corsu, Español, italiano