Crear un Widget para WordPress

Hoy en el trabajo me he visto en la obligación de crear un Widget para WordPress. Los Widgets son aquellos «cuadros» que podemos añadir normalmente al sidebar de nuestro blog, aunque hablando con propiedad se pueden añadir a cualquier área de Widgets (pueden existir varias áreas, para el footer, o áreas personalizadas para las diferentes visualizaciones).

Por ejemplo, en este blog, los cuadros que hay a la derecha son Widgets (el de búsqueda, Twitter, posts, etc).

WordPress desde la versión 2.8 nos facilita la tarea de crear nuevos Widgets personalizados que podemos complicarlos todo lo que queramos. En este caso, como se trata de un ejemplo haremos uno bastante sencillo, un Widget gestionable donde podremos decir cuál es el título, la descripción de una oferta y la URL de la oferta.

Para crear Widgets en WordPress se utiliza la clase WP_Widget cuyo código podéis analizar aquí.

Para crear uno tenemos que crear una clase en PHP con cuatro funciones básicas:

• constructor
• form
• update
• widget

[php]
// La nueva clase debe heredar de WP_Widget
class ofertas_widget extends WP_Widget {
function ofertas_widget() {
// Constructor del Widget
}

function form($instance) {
// Construye el formulario de administración
}

function update($new_instance, $old_instance) {
// Guarda las opciones del Widget
}

function widget($args, $instance) {
// Construye el código para mostrar el widget públicamente
}
}
[/php]

Tras la creación de la clase debemos usar el conector widgets_init asociado a una acción que llame a la función register_widget().

Vamos a ver esto en un ejemplo.

[php]
add_action(‘widgets_init’, ‘registra_mis_widgets’);
function registra_mis_widgets() {
register_widget(‘ofertas_widget’);
}
[/php]

Pero antes de lo anterior tenemos que «rellenar» las funciones básicas de la clase del Widget.

Constructor

En el constructor básico principalmente llamamos al constructor de la clase WP_Widget, lo podemos hacer como está aquí o llamando al constructor de la forma de PHP5.

Los parámetros de este constructor son la id del Widget, el título y unos argumentos opcionales que incluyen la descripción y la clase que se aplicará al «envoltorio» del Widget que en cada tema puede ser un elemento diferente (li, div, etc).

Se puede pasar un cuarto parámetro, que es un array conteniendo la altura y anchura del cuadro de configuración en el panel de administración aunque la altura por ahora no se usa. En el ejemplo no se pasa.

[php]
function ofertas_widget() {
$options = array(‘classname’ => ‘mi-estilo’,
‘description’ => ‘Widget que muestra una oferta’);
$this->WP_Widget(‘ofertas_widget’, ‘Ofertas’, $options);
}
[/php]

El siguente paso es la función form.

Form

La función form, recordemos, muestra el formulario de edición en el panel de administración.

[php]
function form($instance) {
// Valores por defecto
$defaults = array(‘titulo’ => ‘Ofertas’, ‘descripcion’=> », ‘url’ => »);
// Se hace un merge, en $instance quedan los valores actualizados
$instance = wp_parse_args((array)$instance, $defaults);
// Cogemos los valores
$titulo = $instance[‘titulo’];
$descripcion = $instance[‘descripcion’];
$url = $instance[‘url’];
// Mostramos el formulario
?>
<p>
Titulo
<input class="widefat" type="text" name="<?php echo $this->get_field_name(‘titulo’);?>"
value="<?php echo esc_attr($titulo);?>"/>
</p>

<p>
Descripcion
<input class="widefat" type="text" name="<?php echo $this->get_field_name(‘descripcion’);?>"
value="<?php echo esc_attr($descripcion);?>"/>
</p>

<p>
URL
<input class="widefat" type="text" name="<?php echo $this->get_field_name(‘url’);?>"
value="<?php echo esc_attr($url);?>"/>
</p>
<?php
}
[/php]

Update

Recordamos que en esta función se hace la actualización de los datos de la instancia.

[php]
function update($new_instance, $old_instance) {

$instance = $old_instance;
// Con sanitize_text_field elimiamos HTML de los campos
$instance[‘titulo’] = sanitize_text_field($new_instance[‘titulo’]);
$instance[‘descripcion’] = sanitize_text_field($new_instance[‘descripcion’]);
$instance[‘url’] = sanitize_text_field($new_instance[‘url’]);

return $instance;

}
[/php]

Widget

Y por último la función que muestra el Widget en la parte pública.

[php]
function widget($args, $instance) {
// Extraemos los argumentos del area de widgets
extract($args);

$titulo = apply_filters(‘widget_title’, $instance[‘titulo’]);
$descripcion = $instance[‘descripcion’];
$url = $instance[‘url’];

echo $before_widget;
echo $before_title;
echo $titulo;
echo $after_title;
echo ‘<p>’.$descripcion.'</p>’;
echo ‘<p>’.$url.'</p>’;
echo $after_widget;
}
[/php]

¿Y de donde salen variables como $before_widget, $after_widget, $before_title o $after_title? Cuando registramos un área de Widgets son argumentos que podemos pasar. Por ejemplo en el theme Twentytwelve, este es el registro del sidebar principal.

[php]
// Main
register_sidebar( array (
‘name’ => __( ‘Main Sidebar’,’wpex’),
‘id’ => ‘sidebar’,
‘description’ => __( ‘Widgets in this area are used in the default sidebar. This sidebar will be used for your standard blog posts.’,’wpex’ ),
‘before_widget’ => ‘<div class="sidebar-box %2$s clr">’,
‘after_widget’ => ‘</div>’,
‘before_title’ => ‘<‘. $wpex_sidebar_headings .’ class="widget-title">’,
‘after_title’ => ‘</’. $wpex_sidebar_headings .’>’,
) );
[/php]

Solamente faltaría una cosa, incluir la clase del Widget y hacer su registro. En functions.php lo incorporaríamos.

[php]
require_once(get_template_directory().’/core/ofertas_widget.php’);
add_action(‘widgets_init’, ‘registra_mis_widgets’);
function registra_mis_widgets() {
register_widget(‘ofertas_widget’);
}
[/php]

Resultado

Bueno, y tras toda esta ristra de código, pasamos a poner unas imágenes del resultado en el panel de administración:

En la parte pública nos encontraríamos con lo siguiente:

Como se puede ver en el Firebug al aside se le aplica la clase CSS que hemos pasado en el constructor (cuando pasamos las opciones), faltaría, claro está, estilizar la clase para que se muestre el Widget de una manera más visual.

Hasta aquí el cómo crear un Widget sencillo. Podemos complicarlo todo lo que queramos, incorporar librerias Javascript, hacer acordeones, tabs, invocar al bucle de WordPress y un sinfín de opciones cuyo límite es nuestra imaginación y un poco de destreza buscando documentación 😉

Espero que os haya resultado interesante la entrada y no se haya hecho muy pesada. Tenéis los comentarios abiertos para cualquier sugerencia o duda.

Gracias por la lectura 🙂