Guida allo sviluppo di plugin per wordpress: Gli strumenti di base

di Maurizio Tarchini | 15 set 2011 | in: Guide, Tutorial, Wordpress

Nel precedente articolo ci siamo lasciati con la realizzazione dell’intestazione del nostro plugin. Ora dovremo iniziare a lavorare sulle funzioni fondamentali che ci permetteranno di “inserirci” nell’esecuzione di WordPress per “aggiungere” quello che ci serve.
Per fare questo dovremo dichiarare delle funzioni e dire a WordPress dove o quando eseguirle. Detto così può sembrare complicato, ma vediamo subito di chiarire con un po’ di pratica.

add_action: Come aggiungere codice al runtime di WordPress?

La prima funzione che trattiamo in questo articolo é add_action() che ci permette di definire dove o quando una funzione deve essere eseguita. La funzione add_action() ha questo formato:

add_action(‘dove o quando’, ‘funzione da eseguire’);

Dunque, come secondo argomento della funzione dobbiamo passare il nome della funzione (da noi definita) che intendiamo eseguire.
Il primo parametro invece si riferisce ad un “gancio” messo a disposizione da WordPress; qui trovi l’elenco di questi ganci (la pagina continua molto oltre il primo gruppo di ganci).

wp_footer ad esempio si riferisce al gancio wp_footer del tema. Lo utilizzeremo se vogliamo che la nostra funzione sia eseguita in quel punto (dove).

Oppure potremo utilizzare publish_post se vogliamo eseguire una funzione nel momento in cui viene pubblicato un nuovo articolo (quando). Ad esempio se volessimo che alla pubblicazione di un nuovo articolo venga inviata un’email di notifica all’amministratore, dovremo scrivere qualcosa del genere:

add_action(‘publish_post’, ‘funzione_che_invia_un_email’);

Vediamo subito un esempio tanto semplice quanto inutile. Facciamo in modo che il nostro plugin inserisca un commento nell’header del nostro sito.
Innanzitutto dichiariamo una funzione che stampa un commento.

function ylb_print_test_comment()
{
    ?>
        <!-- Commento -->
    <?php
}

! best practice !
A questo punto vediamo una prima importantissima regola: il nome delle funzioni deve essere un po’ “complicato” e deve avere un prefisso (io uso l’acronimo del nome del plugin). Questo per limitare al massimo il rischio che un altro plugin o un tema contengano funzioni con nomi uguali alle nostre (eventualità che provocherebbe un fatal error).

Bene. Ora abbiamo la nostra funzione che stampa a video un commento. Non dobbiamo fare altro che dire a WordPress che vogliamo eseguirla nell’header del nostro sito utilizzando il gancio wp_head, in questo modo.

function ylb_print_test_comment()
{
    ?>
        <!-- Commento -->
    <?php
}

// diciamo a WordPress di eseguire la nostra funzione
// nell’header della pagina
add_action('wp_head', 'ylb_print_test_comment');

Attiviamo il plugin (se non lo abbiamo ancora fatto) e proviamo a caricare una pagina del nostro sito. Visualizzando il sorgente vedrai che il commento é stato inserito nell’header.

Cancelliamo ora quanto abbiamo scritto e dedichiamoci ad un’altra fondamentale funzione.

add_filter: Come manipolare i contenuti?

Questa funzione si utilizza prevalentemente per apportare delle modifiche (filtri) ai dati che verranno salvati nel database o ai dati in uscita da esso, o più in generale a qualsiasi tipo di dato. Anche add_filter ha una lunga serie di ganci. A differenza di add_action questi ganci non si riferiscono a quello che ho chiamato (per semplificare) un dove o un quando ma a un “cosa”.
In pratica questi ganci ci indicano a cosa vogliamo aggiungere il filtro che definiremo nella funzione.
Facciamo subito un esempio. Poniamo di voler aggiungere un filtro che trasformi tutti i titoli dei nostri post da:

Titolo del post

Titolo: Titolo del post

In pratica vogliamo aggiungere “Titolo: “ prima del titolo di ciascun post.
Il “gancio” di cui avremo bisogno é the_title, che fa appunto riferimento al titolo del post.

Iniziamo con lo scrivere la semplice funzione per implementare questo filtro.
Bisogna sapere che add_filter passerà come argomento alla nostra funzione il contenuto del gancio. Non dovremo fare altro che recuperarlo e modificarlo, in questo modo.

function ylb_filter_title_test($title)
{
    return 'Titolo: ' .$title;
}

Ed ora aggiungiamo il filtro

add_filter('the_title', 'ylb_filter_title_test');

Ed ecco fatto. Il titolo di ogni nostro post verrà passato come argomento della funzione ylb_filter_title_test che provvederà a modificarlo.

Ora che abbiamo trattato queste due fondamentali funzioni, siamo pronti per continuare il nostro plugin. Cancella tutto, mantenendo solo l’intestazione che abbiamo realizzato nel precedente articolo.

Come mostrare il nostro box della licenza?

Quello che dobbiamo fare per raggiungere lo scopo che ci siamo prefissati all’inizio di questa guida é aggiungere le informazioni relative alla licenza alla fine di ogni articolo. Iniziamo dunque a sviluppare la funzione.

function ylb_output_license_box($content)
{
    $return = $content;
    $return .= '<div class="ylb-container">
    <p>Il testo di questo articolo &eacute; di propriet&agrave; di Maurizio Tarchini ed &eacute; rilasciato sotto licenza Creative Commons. Sei libero di ridistribuirlo e riprodurlo....</p>
    <p><a href="#" class="ylb-close">chiudi</a></p>
    </div>';
    return $return;
}

Come vedi aggiungiamo il testo della licenza e il link per la chiusura del box alla fine del contenuto dell’articolo (per il momento in questo modo, più avanti quel testo lo renderemo disponibile come opzione nel pannello amministrativo di WordPress).

Ed ora non dovremo fare altro che aggiungere questo filtro al gancio che fa riferimento al contenuto dell’articolo (the_content), in questo modo:

add_filter('the_content', 'ylb_output_license_box');

A questo punto possiamo testare il nostro primo plugin. Alla fine di ogni articolo adesso dovrebbe apparire il testo della licenza.

Come aggiungere lo stile?

Nella cartella yiw-license-plugin creiamo la cartella css e al suo interno il file style.css.
Diamo ora un minimo di forma al nostro box

.ylb-container{margin: 50px; border: none; padding: 10px; background-color: #E6E6E6;-webkit-border-radius:8px;-moz-border-radius:8px;border-radius:8px;}

Ora abbiamo il nostro foglio di stile e dovremmo includerlo nell’header del sito.

Qualcuno a questo punto potrebbe pensare di scrivere una funzione come questa

function ylb_style()
{
?>
    <link rel='stylesheet' id='the-style-css'  href='wp-content/plugins/yiw-license-plugin/css/style.css' type='text/css' media='all' />

<?php
}

E passarla tramite add_action al gancio wp_head.
Funzionerebbe, ma non é il modo corretto

! best practice !
I fogli di stile vanno inclusi tramite un’apposita funzione, wp_enqueue_style. Questa funzione passa diversi parametri; quelli che ci interessano sono i primi due.
Il primo é il nome univoco del foglio di stile ed il secondo é l’url.

Quindi per includere il nostro foglio di stile, procederemo in questo modo:

wp_enqueue_style('ylb-style', ‘wp-content/plugins/yiw-license-plugin/css/style.css');

Anche se potrebbe andare non ci siamo ancora, il tutto può ancora essere ottimizzato.

! best practice !
WordPress raccomanda in questo caso di utilizzare la costante predefinita WP_PLUGIN_URL che contiene l’url della cartella plugin. Dunque procediamo in questo modo:

wp_enqueue_style('ylb-style', WP_PLUGIN_URL . '/yiw-license-plugin/css/style.css');

Ora possiamo ricaricare il nostro sito; il foglio di stile verrà correttamente caricato producendo un risultato simile a questo:

Riporto anche lo stato attuale del nostro plugin:

<?php
/*
Plugin Name: Yiw License Box
Plugin URI: http://www.yourinspirationweb.com
Description: Qui possiamo scrivere una breve descrizione del plugin
Version: 1.0
Author: Maurizio Tarchini
Author URI: http://www.yourinspirationweb.com
 */

function ylb_output_license_box($content)
{
    $return = $content;
    $return .= '<div class="ylb-container">
    <p>Il testo di questo articolo &eacute; di propriet&agrave; di Maurizio Tarchini ed &eacute; rilasciato sotto licenza Creative Commons. Sei libero di ridistribuirlo e riprodurlo....</p>
    <p><a href="#" class="ylb-close">chiudi</a></p>
    </div>';
    return $return;
}

add_filter('the_content', 'ylb_output_license_box');

wp_enqueue_style('ylb-style', WP_PLUGIN_URL . '/yiw-license-plugin/css/style.css');

?>

Conclusione

In questo articolo abbiamo approfondito le due funzioni cardine nell’ambito dello sviluppo di plugin. Abbiamo inoltre visto il modo corretto di includere un foglio di stile.
Nel prossimo tutorial implementeremo la chiusura del box con animazione jQuery.
Una cosa del tutto superflua ma mi serve per mostrarti come funziona l’inclusione di script e per parlare delle funzioni preposte a questo scopo.
Arrivato a questo punto cosa ne pensi? Non é così difficile come può sembrare, vero?

Capitoli di questa guida

**************************
La mascotte dell’articolo è stata fornita da @Fotolia

Scarica articolo in PDF

Tag: plugin, Wordpress

L'autore

Maurizio è sposato con la triade PHP - MySql - Apache e, non pago, ha un'amante chiamata jQuery. Ha un blog dove cerca di descrivere nei minimi particolari sia la moglie che l'amante. La sua vera specialità è la realizzazione di gestionali complessi anche se non rifiuta mai un sito web. +

Sito web dell'autore | Altri articoli scritti da Maurizio Tarchini

28 commenti

Pikadilly

15 settembre 2011 a 11:35

# 1

Superlativo. Semplice e chiaro. Grazie mille. ;)

Rispondi
- Maurizio
  
  15 settembre 2011 a 13:05
  
  # 2
  
  Grazie a te Pika!
Caluk

15 settembre 2011 a 13:21

# 3

Spettacolo Maurizio. Secondo articolo veramente fatto bene.

Visto che parli dell’inclusione di altri linguaggi, come il mio caro jQuery, aspetto con ansia il secondo articolo ;)

Rispondi
- Maurizio
  
  15 settembre 2011 a 21:37
  
  # 4
  
  E grazie anche a te Caluk.
  L’inclusione di jQuery e degli script é un passaggio molto importante.
scienzedellevanghe

16 settembre 2011 a 16:46

# 5

Peccato non aver incominciato adesso a sviluppare plugin, avrei potuto usifruire di una magnifica guida!

Rispondi
- Maurizio
  
  16 settembre 2011 a 20:22
  
  # 6
  
  Eh ma siete troppo buoni!
  Grazie scienzedellevanghe!
Luca

18 settembre 2011 a 21:09

# 7

Anche questo articolo è molto chiaro e finora no ho sbagliato nulla nei miei plugins!

Rispondi
- Maurizio
  
  22 settembre 2011 a 14:04
  
  # 8
  
  Grazie Luca
Tiziano

20 settembre 2011 a 12:21

# 9

Semplicissimo da seguire come sempre, ho solo un dubbio: i parametri che passi negli esempi, $title e $content, i nomi sono arbitrari o si riferiscono a variabili del core di wordpress?

Rispondi
- Maurizio
  
  22 settembre 2011 a 14:10
  
  # 10
  
  Ciao Tiziano.
  I nomi delle variabili sono arbitrari, indicano semplicemente il parametro che verrà passato alla funzione valorizzato con il contenuto del gancio.
Tiziano

17 ottobre 2011 a 23:08

# 11

Ciao Maurizio, nella mia funzione ho usato add_filter(‘the_content’, ‘nomefunzione’); ma il risultato della funzione viene visualizzato nella index dopo il tag , quando invece dovrebbe apparire solo in single.php, è normale questo comportamento? bisogna fare qualcosa affinché il filtro venga applicato solo in single.php?

Rispondi
- Tiziano
  
  17 ottobre 2011 a 23:09
  
  # 12
  
  *nel mio plugin*, sorry
- scienzedellevanghe
  
  17 ottobre 2011 a 23:28
  
  # 13
  
  mica nella funzione usi echo? come dici di comparire solo in single.php?
  è meglio che mostri il codice incriminato
  http://pastie.org/
- Maurizio
  
  17 ottobre 2011 a 23:49
  
  # 14
  
  Così come é proposto, appare in tutte le pagine.
  Se vuoi che compaia solo in single.php dovrai verificare con la funzione is_single()
  
  if(is_single())
  { mostra…
- Tiziano
  
  18 ottobre 2011 a 16:04
  
  # 15
  
  Grazie Maurizio, era quello che cercavo :)
Andrea

24 ottobre 2011 a 17:34

# 16

Intanto ottimo articolo, chiaro e semplice, ho però un problema.
Sto sviluppando un plugin che scarica la galleria Flickr di un utente in una pagina a scelta del sito.

Fin qui niente di che, fa ciò che deve senza problemi.
Ora ho l’esigenza di far visualizzare le immagini zoomate tramite Lightbox ma non riesco ad inserire né CSS né JS.

wp_enqueue_style(“fkystyle”, WP_PLUGIN_URL . “/flickry/style.css”);
wp_enqueue_style(“fkylightbox”, WP_PLUGIN_URL . “/flickry/lightbox.css”);

wp_enqueue_script(“lightbox”, WP_PLUGIN_URL . “/flickry/lightbox.js”, array(“jquery”));
wp_enqueue_script(“set_lightbox”, WP_PLUGIN_URL . “/flickry/set_lightbox.js”, array(“jquery”));

Invece di includere nel front-end include nel back-end, che devo fare?

Rispondi
- scienzedellevanghe
  
  25 ottobre 2011 a 13:19
  
  # 17
  
  mi pare strano che te lo condivida solo nel back end.. a che azione hai agganciato la tua funzione?
  
  Dovresti agganciarti a ‘init’ ed usare if(!is_admin()) per evitare che script e stili vengano inclusi nell’amministrazione
  
  http://codex.wordpress.org/Function_Reference/is_admin
- Andrea
  
  25 ottobre 2011 a 15:23
  
  # 18
  
  Lo aggancio a “wp_head” ed ho aggiunto il controllo con “is_admin()” come mi hai detto e arriva alla parte in cui dovrebbe inserire stili e script, però ancora non inserisce un tubazzo (non inserisce nel back-end almeno).
  
  Non è un metodo corretto da usare però se ovvio facendogli stampare tramite “echo” il codice che dovrebbe avere nell’head, funziona, nonostante la cosa non mi piaccia affatto, anzi mi infastidisce assai non sapere perché non vada.
  Il codice:
  
  wp_enqueue_style(“fkystyle”, WP_PLUGIN_URL . “/flickry/style.css”);
  wp_enqueue_style(“fkylightbox”, WP_PLUGIN_URL . “/flickry/lightbox.css”);
  wp_enqueue_script(“lightbox”, WP_PLUGIN_URL . “/flickry/lightbox.js”, array(“jquery”));
  wp_enqueue_script(“set_lightbox”, WP_PLUGIN_URL . “/flickry/set_lightbox.js”, array(“jquery”));
  
  credo sia giusto, visto che nel back-end lo inseriva senza alcun problema.
  Solo non va nel front-end e non capisco cosa sbaglio (lavoro con WP da una settimana e per ora ho fatto solo un tema e questo è il mio primo plugin quindi ci sta benissimo che sbaglio qualcosa).
  
  Se hai altre idee fammi sapere, per ora grazie dell’aiuto.
- scienzedellevanghe
  
  26 ottobre 2011 a 22:32
  
  # 19
  
  evidentemente wp_head è un azione successiva a quella in cui va a scrivere wp_enqueue_style/wp_enqueue_script
  
  agganciali ad init o a wp_print_styles/wp_enqueue_scripts come negli esempi della documentazione ufficiale.
  http://codex.wordpress.org/Function_Reference/wp_enqueue_style
  http://codex.wordpress.org/Function_Reference/wp_enqueue_script
evolution

26 giugno 2012 a 15:55

# 20

Ottimo tutorial, ora li leggo tutti :)

Rispondi
Mario

29 agosto 2012 a 02:31

# 21

Sono “incappato” in questo sito per puro caso (non ricordo neanche come ci sono finito), farvi i complimenti è poco, vi ho messo tra i preferiti e da oggi diventerò uno dei vostri lettori più assidui. Non sono riuscito a trovare un solo articolo poco interessante!

P.S. Questa guida è fantastica, non l’ho ancora testata ma concettualmente ho capito tutto (ed è quanto dire alle 2:30 di notte ^^). Domani proverò a passare alla pratica.

Rispondi
Boris

19 marzo 2013 a 13:51

# 22

Apprezzo moltissimo il tuo lavoro, credo che dimostrerò la mia gratitudine passandoti il plugin che realizzerò grazie al tuo aiuto. Si tratta di una video gallery, non so ancora se andare a mostrare i video embeddati nei vari posts o se creare un pannello lato admin per gestire video e preview…

Avrai mie notizie!
Ciao Maurizio

Boris

Rispondi