Nuestro primer widget WordPress

En este artículo vamos a ver cómo hacer un widget que nos permita crear un slider con los thumbnails de los posts que nosotros escojamos. Para ello, vamos a aprovechar el slider ‘carousel.js’ de Bootstrap.

Antes de nada, quiero dar las gracias al blog de Juan Ignacio Alberola, pues con su post Crear un Widget para WordPress, junto con el manido Codex WordPress, he conseguido realizar mi primer widget.

Vamos allá.

El sidebar y las zonas libres de widgets

En el pasado artículo Mejorando el pie de página de WordPress, veíamos cómo funcionaba la barra lateral (sidebar) y cómo podíamos crear zonas libres de widgets. Cuando creemos un widget debemos pensar que esas serán sus posibles ubicaciones en la salida por pantalla.

Ubicación del archivo del widget

En este caso, vamos a ubicar el archivo en el subdirectorio ‘widgets’ de nuestro tema. Para ello, deberemos incluirlo en el archivo functions.php mediante la sentencia require_once, donde le indicaremos la ubicación y el nombre del archivo para tal efecto, como podemos comprobar más abajo.

Instanciar el widget

Para ejecutar el widget en nuestro tema, debemos instanciarlo en su archivo functions.php. Yo, en este caso, lo he hecho así:

Estructura básica

Todo widget tiene una clase con 4 funciones, según esta estructura:

Para crear un widget, como se puede ver en la primera línea de la estructura básica, sólo tenemos que extender la clase WP_Widget que trae la instalación WordPress por defecto.

El constructor del widget

El constructor es la declaración de la función que estamos creando. La declaramos pasándole a la clase WP_Widget los parámetros de $nombre, $título y $argumentos (en forma de matriz), como podemos ver arriba.

El formulario (form) del back-end

El bloque form nos permite generar el formulario en el que introduciremos los datos en el panel de administración, en ‘Apariencia > Widgets’.

Básicamente, le debemos indicar los campos <input> en los que introduciremos los parámetros que nos interesen luego para la visualización en el front-end del widget.

Si os fijáis, yo aquí creo dos campos. El primero es auxiliar que consiste en un <select> que nos muestra los diferentes posts de nuestra web con sus ID y sus títulos. Para ello, genero una $consulta con la sentencia new wp_query( $argumentos ), a partir de la cual creo un ‘loop’ secundario.

En la última línea, defino el campo en el que introduciremos los números de artículo mediante sus id, separados por comas (,).

Guardar los parámetros del widget

Básicamente, una vez hemos introducido los argumentos en los diferentes campos del formulario, ahora lo guardamos en la base de datos (update).

Mostrar el resultado en el front-end

Primeramente, tenemos dos líneas que nos aportarán ciertos datos. La primera nos extrae (extract) los argumentos ($args). Estos argumentos los dimos en el archivo functions.php, al declarar la barra lateral, y son ‘before_widget’, ‘after_widget’, ‘before_title’ y ‘after_title’. En la segunda línea obtenemos el título del widget. Estos argumentos los mostramos por pantalla en las siguientes 4 líneas de código.

A continuación, empezamos a crear las estructura de div’s necesaria para el funcionamiento del script carousel.js, que nos ha aportado Bootstrap.

Recordemos que definíamos la lista de artículos cuyos thumbnails mostrar, como una lista de sus id, separados con comas. Con la sentencia $instance[‘seleccion’] recuperamos la cadena, la que dividimos mediante la función explode, y creamos una matriz $elemento con los id’s por separado.

Al recorrer la matriz mediante la sentencia foreach ($elemento as $articulo), podremos ir creando las diferentes div de cada elemento del slider. Unicamente debemos añadir un $contador, que nos permita saber en qué elemento estamos en cada momento para aprovecharlo para incluir la clase active en el div class=”item” el primero de todos, ya que sin ello, no arranca la función JavaScript. Observamos que aprovecho las etiqueta de plantilla del Codex get_the_post_thumbnail()get_the_permalink()get_the_title(), que permiten extraer los datos buscados, pero fuera del ‘loop’.

Repaso de funciones empleadas

WP_Widget Clase extendida del core de WP para registrar widgets. Esta clase debe ser extendida para cada widget y WP_Widget::widget()WP_Widget::update()WP_Widget::form() deben ser reescritas.

Métodos de la clase:

  • __construct. Constructor PHP5.
  • _get_display_callback. Devuelve la llamada de vuelta de pantalla.
  • _get_form_callback. Devuelve la llamada de vuelta del formulario.
  • _get_update_callback. Devuelve la llamada de vuelta del guardado.
  • _register. Registra todas las instancias de widget de esta clase de widgets.
  • _register_one. Registra una instancia de la clase widget.
  • _set. Selecciona el número de orden interno de la instancia del widget.
  • display_callback. Genera el contenido actual del widget (no sobreescribir).
  • form. Muestra el formulario de actualización de ajustes.
  • form_callback. Genera el formulario de control del widget (no sobreescribir).
  • get_field_id. Construye los atributos id para emplearlo con los campos de WP_Widget::form().
  • get_field_name. Construye los atributos de nombre para emplearlo en los campos form().
  • get_settings. Devuelve los ajustes para todas las instancias de la clase widget.
  • is_preview. Determina si la consulta actual está dentro de la previsualización del Personalizador WP.
  • save_settings. Guarda los ajustes para todas las instancias de la clase widget.
  • update. Actualiza una instancia particular de un widget.
  • update_callback. Maneja los ajustes modificados (no sobreescribir).
  • widget. Muestra en pantalla el contenido del widget.
  • WP_Widget. Constructor PHP4.

WP_Query es una clase que permite realizar una consulta alternativa en WordPress.

extract Función PHP que se emplea para importar variables a la tabla de símbolos actual desde un array.

apply_filters( $etiqueta, $valor ) Llama a la función añadida a un gancho de filtro. Esta función se verá más detalladamente en el próximo artículo de la serie.

add_action( $etiqueta, $función_a_añadir, $prioridad, $argumentos ) Engancha una función a una acción específica. Esta función también se revisará en el próximo artículo.

register_widget( $widget_class ) Registra un widget.

sanitize_text_field( $cadena ) Sanea una cadena del código HTML.

wp_parse_arguments( $argumentos, $defecto ) Utilidad genérica para mezclar juntas una matriz de argumentos y una matriz de valores por defecto.

Así pues, el código entero del widget es el siguiente:

 

En fin, esto es todo. En el próximo artículo veremos qué otros parámetros podemos incluir para que los usuarios puedan personalizar nuestros temas.

4 opiniones en “Nuestro primer widget WordPress”

  1. Hola Sergio,

    ya han pasado unos meses de la mención a mi blog pero por casualidad lo he descubierto hoy, en plenas puertas de Agosto.

    Aprovecho el comentario para agradecerte tal mención y para quedar a tu disposición para lo que necesites. Además, ya te tengo fichado en Feedly 🙂

    Un saludo

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *