Wordpress: creare un widget

In questo articolo vedremo come creare un semplicissimo widget per Wordpress che mostrerà un post a caso tratto dall'insieme di quelli già pubblicati. Come vedrete, la procedura è la medesima per tutti i widget di Wordpress.

Preparazione

Creiamo una directory vuota locale a cui daremo lo stesso nome del nostro widget (random-post). Al suo interno creeremo un file PHP vuoto con lo stesso nome della directory. Quindi avremo:

random-post
|-- random-post.php

Metadati

Apriamo il file PHP e inseriamo il tag di apertura PHP. Quindi inseriamo i metadati che serviranno a Wordpress per mostrare correttamente le informazioni sul nostro widget nella pagina dei plugin:

/*
Plugin Name: Random Post Widget
Plugin URI: http://gabrieleromanato.com
Description: Displays a random post
Author: Gabriele Romanato
Version: 1
Author URI: https://gabrieleromanato.com/
*/

Sostituite le varie informazioni con i vostri dati e salvate il file.

Struttura del widget

La struttura di un widget di Wordpress è sempre la seguente:

class RandomPostWidget extends WP_Widget
{


	function RandomPostWidget() {...}
	
	function form($instance) {...}
	
	function update($new_instance, $old_instance) {...}
	
	function widget($args, $instance) {...}



}

La classe RandomPostWidget deriva dalla classe di Wordpress WP_Widget. Essa ha quattro metodi:

1. RandomPostWidget::RandomPostWidget(): metodo di inizializzazione e registrazione del widget (ha sempre lo stesso nome della classe)
2. RandomPostWidget::form($instance): genera il form in cui l'utente può impostare le opzioni per il widget, come ad esempio il titolo
3. RandomPostWidget::update($new_instance, $old_instace): aggiorna il form del widget
4. RandomPostWidget::widget($args, $instance): elabora i dati e genera l'output prodotto dal widget

Inizializzare il widget

Il widget viene inizializzato in questo modo:

function RandomPostWidget() {
    $widget_ops = array('classname' => 'RandomPostWidget', 'description' => 'Displays a random post' );
    $this->WP_Widget('RandomPostWidget', 'Random Post', $widget_ops);
}

Le opzioni comprendono il nome della classe CSS del widget e la sua descrizione. Queste opzioni vengono passate come parametri al costruttore della classe WP_Widget, che inizializza il widget.

Generare il form di opzioni

Il form delle opzioni del widget viene generato come segue:

function form($instance) {
    $instance = wp_parse_args( (array) $instance, array( 'title' => '' ) );
    $title = $instance['title'];
?>
  <p><label for="<?php echo $this->get_field_id('title'); ?>">Title: <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo attribute_escape($title); ?>" /></label></p>
<?php
  }

In questo caso l'array associativo usato ha solo l'opzione title, ossia il titolo per il widget. I metodi get_field_id() e get_field_name() appartengono alla classe genitrice WP_Widget. La classe CSS widefat è una delle classi CSS predefinite usate da Wordpress per la sua interfaccia.

Aggiornare il form di opzioni

Il form di opzioni viene aggiornato in questo modo:

function update($new_instance, $old_instance) {
    $instance = $old_instance;
    $instance['title'] = $new_instance['title'];
    return $instance;
}

In pratica viene usata l'opzione title della nuova istanza del widget, sostituendo quella della precedente instanza.

Lavorare sui dati e generare l'output

Il metodo RandomPostWidget::widget($args, $instance) opera sui dati e genera l'output del widget:

function widget($args, $instance) {
    extract($args, EXTR_SKIP);
 
    echo $before_widget;
    $title = empty($instance['title']) ? ' ' : apply_filters('widget_title', $instance['title']);
 
    if (!empty($title))
      echo $before_title . $title . $after_title;;

query_posts('posts_per_page=1&orderby=rand');
if (have_posts()) : 
	echo "<p>";
	while (have_posts()) : the_post(); 
		echo "<a href='".get_permalink()."'>".get_the_title();
		echo "</a>";	
 
	endwhile;
	echo "</p>";
endif; 
wp_reset_query(); 
 
 
    echo $after_widget;
  }
 
}

Un widget ha tre punti chiave:

1. $before_widget: contenuto che apre il widget
2. $before_title: contenuto che viene prima del titolo del widget
3. $after_widget: contenuto che chiude il widget

L'elaborazione dei dati e l'output avvengono dopo il secondo punto e prima del terzo. In questo caso creiamo un nuovo loop di Wordpress e specifichiamo di voler ottenere un solo post in ordine casuale tramite la funzione query_posts(). Notate come ho utilizzato funzioni che non restituiscono un output per reperire l'URL e il titolo del post. Il motivo è semplice: stiamo già usando echo e quindi non possiamo utilizzare funzioni come the_title() o the_permalink() che ne fanno già uso.

Lanciare il widget

Il nostro codice si conclude in questo modo dopo la fine della classe RandomPostWidget:

add_action( 'widgets_init', create_function('', 'return register_widget("RandomPostWidget");') );?>

Creiamo una action sull'inizializzazione dei widget e registriamo il widget tramite register_widget() a cui passiamo il nome della nostra classe.