Plugins (XIV) Creando un Widget

Los widgets nos pueden salvar la vida en multitud de ocasiones, sobre todo cuando queremos mostrar un contenido estático, ya que podemos incluir html sin ningún problema, y muchos plugins nos ayudan ademas introduciendo widgets para su uso.

Pero puede ocurrir, y mas temprano que tarde de forma general que como desarrolladores, nos encontremos con la necesidad de que lo que queremos mostrar en el widget sea un contenido dinámico. Entonces es cuando tenemos que proceder a crear nuestro propio widget.

¿como funciona un widget?

Un widget no deja de ser más que una clase extendida de WP_Widget con cuatro funciones dentro.

  • Función constructora: donde establecemos la id, el nombre y una descripción del widget.
  • widget(): se encarga de representar el widget. Es donde va todo el código que vamos a utilizar y que queremos que muestre.
  • form(): aqui está el formulario de opciones que tiene un Widget cuando lo metemos en una Sidebar.
  • update(): que ejecuta la acción del botón ‘Guardar’ del formulario.

Como se puede observar en principio todo es más simple que el mecanismo de un chupete, con estas cuatro funciones, o incluso solo las dos primeras si nuestro widget no tiene opciones para guardar, podemos hacer todo lo que necesitemos en un widget.

Organizando los archivos

Lo primordial es saber que los widgets deben de estar dentro de plugins o del archivo functions.php, pero nosotros lo haremos como un plugin, así aprendemos varias cosas a la vez, además evitaremos que al actualizar el tema se actualice el archivo functions.php y nuestro widget desaparezca.

Para ello vamos a crear un plugin con el siguiente texto:

<?php

/*
Plugin Name: Hola Widget
Plugin URI: http://mialtoweb.es/
Description: Crea un Widget para añadir a cualquier Sidebar.
Version: 1.0
Author: Mialto
Author URI: http://mialtoweb.es/
*/

/**
 * Función que instancia el Widget
 */
function pw_create_widget(){
    include_once(plugin_dir_path( __FILE__ ).'/includes/widget.php');
    register_widget('pw_widget');
}
add_action('widgets_init','pw_create_widget'); 

?>

Los comentarios son la forma que tiene WP de saber que se trata de un plugin… no los borres aunque debes editarlos para que aparezca tu información.

Después tenemos la función pw_create_widget() (el nombre de esta función es arbitrario) pero hace varias cosas:

  • recoger el path donde se encuentra el archivo de nuestro widget, sin el cual no funcionaría. En nuestro caso busca dentro del plugin en includes/widget.php
  • registra el widget en el sistema con la función registrer_widget(). Esta función recibe como parámetro el nombre de la clase que le daremos al widget.

Ahora debemos de crear nuestro widget, que debe de heredar (extends) de la clase WP_Widget y que tiene la siguiente estructura:

<?php

class pw_widget extends WP_Widget {

    function pw_widget(){
        // Constructor del Widget.
    }

    function widget($args,$instance){
        // Contenido del Widget que se mostrará en la Sidebar
    }

    function update($new_instance, $old_instance){
        // Función de guardado de opciones
    }

    function form($instance){
        // Formulario de opciones del Widget, que aparece cuando añadimos el Widget a una Sidebar
    }
} 

?>

Esta plantilla puede servir de ejemplo para todos los widgets que necesitemos, y como puedes ver tiene las cuatro funciones de las que hablábamos más arriba.

constructor

La primera función ha de llamarse igual que la clase, es la que se instancia una vez que el widget es llamado. Lo que tenemos que hacer en ella es llamar al constructor WP_Widget con las opciones del widget.

Es la más repetitiva, y y tan solo hay que cambiar algunas cosillas:

    function pw_widget(){
        // Constructor del Widget.
        $widget_ops = array('classname' => 'pw_widget', 'description' => "Descripción de Mi primer Widget" );
        $this->WP_Widget('pw_widget', "Mi primer Widget", $widget_ops);
    }

En los lugares donde pone pw_widget hay que poner el nombre de la clase del widget en descripción ponemos la descripción del widget y donde pone «Mi primer Widget» ponemos el titulo del widget, con eso es bastante.

widget

En esta función es donde vamos  a generar el contenido que aparecerá en nuestro widget, ya sea un código php, javascript, un bucle de wordpress (ya sabeis «loop controls, controls wordpress» )… Nosotros en este ejemplo vamos a hacer un hola mundo y a continuación algo un poco más complejo (si se puede llamar así…)

Hola Mundo

Para hacer un hola mundo solo hay que poner la siguiente función:

    function widget($args,$instance)
    {
        ?>
        <h2>Hola Mundo</h2>
        <?php
    }

Con esto ya podríamos activar nuestro plugin desde el panel de control, en la sección de plugins y nuestro widget aparecería entre los que podemos utilizar…

Hola mundo!

¿Pero que ocurre si queremos que el widget responda a los datos recibidos en un formulario de configuración, como tantos que hay por ahí? Pues bien en ese caso deberemos de utilizar las otras dos funciones de la plantilla de widget, pero ademas vamos a tener que utilizar el argumento $instance de la función principal para poder recoger y mostrar ese dato de la siguiente forma:

    function widget($args,$instance)
    {
        $nombre = $instance['nombre'];
        ?>
        <h2>Hola <?= $nombre?></h2>
        <?php
    }

Aquí vemos como se recoge, de forma similar a php, el dato que queremos utilizar, en este caso el dato es nombre, por medio de $instance[‘dato’];

form

Esta función como su propio nombre indica es el formulario de opciones que nos ofrecerá el widgets para su configuración, por lo que muco de su contenido es en html….

function form($instance){
    $nombre = $instance['nombre'];
    ?>
    <p>
        <label for='<?= $this->get_field_id('nombre'); ?>'>Nombre</label>
        <input type='text' name='<?= $this->get_field_name('nombre'); ?>' id='<?= $this->get_field_id('nombre'); ?>' value='<?= $nombre; ?>'>
    </p>
    <?php
}

El parámetro $instance sigue apareciendo con los valores previamente guardados.

Los valores de id y name del texto no los podemos establecer nosotros, para ello debe utilizarse:

  • $this->get_field_id  para la id
  • $this->get_field_name para el name

Con el fin de que wordpress se entienda internamente.

update

Esta función nos sirve para guardar nuestros campos cuando se hace click en el botón de guardar:

function update($new_instance, $old_instance){
    $instance = $old_instance; // De esta forma, tenemos ya presentes los datos guardados previamente.
    $instance['nombre'] = strip_tags($new_instance['nombre']);
    return $instance;
}

Este código hace los siguiente:

  • Copia los datos antiguos, en caso de que los haya para ponerlos en el formulario
  • Se sustituyen los datos antiguos por los nuevos $new_instance, y se evita la inyección de html con la funcion strip_tags();
  • Se retorna $instance modificado

Activando el Widget

Como ya hemos dicho más arriba, para activar nuestro widget, debemos:

  • Instalar nuestro plugin, ya sea por ftp o por el instalador del panel de control
  • Activar el plugin en la sección de plugins del panel de control
  • Ir a apariencia > widgets arrastrar el widget a la sección que queramos, configurarlo y guardarlo.

A partir de aquí ya todo queda a la imaginación que tengáis, las ganas y lo que necesitéis.