Añadiendo Hooks Personalizados en WordPress: Filtros Personalizados

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

En esta serie dividida en dos partes, vamos a ver el sistema de hooks de WordPress. Concretamente, estudiaremos de cerca tanto las acciones como los filtros, así como el papel que juegan en el desarrollo de WordPress.

Aunque ambos son definidos como hooks, cada uno juega un papel específico en el desarrollo con WordPress. Y si deseas alcanzar un nivel experto como desarrollado WordPress, es importante no solo entender la diferencia entre ellos, sino también saber como puedes implementar tus propios hooks.

En el primer artículo de esta serie, definimos lo que eran los hooks, vimos como se usaban, repasamos también las acciones e incluso como podemos incluir las propias. Si te perdiste el primer artículo, te recomiendo encarecidamente que lo leas antes de continuar con este tutorial.

Antes de empezar con los hooks, te refrescaré lo que tratamos en el episodio anterior, tras ello continuaremos avanzando.

Dicho esto, comencemos.

Breve Recopilación

En el artículo anterior, vimos como los hooks son una implementación del diseño con patrones basados en eventos. En particular, lo definimos como sigue:

El software contiene ciertos puntos en los cuales emite un mensaje indicando que algo a sucedido.
Nosotros, como desarrolladores, somos capaces de escribir código que escucha estos mensajes y responde a ellos emitiendo un código a medida.

Más adelante, repasamos como se implementa este patrón concreto en WordPress. Hablamos sobre como podemos sacar ventaja de ello, y después vimos como implementar una acción de nuestra creación.

Hicimos también una pequeña distinción:

Las acciones están planteadas para trabajar con la funcionalidad, y los filtros con información.

Mientras las acciones nos permiten modificar la forma en que algo se comporta, los filtros nos van a permitir transformar la información antes de que sea almacenada, recuperada o mostrada en la pantalla. En este tutorial, veremos como trabajan los filtros antes de mostrar la información en la pantalla, como por ejemplo transformar el texto en minúsculas o eliminar las vocales del texto.

En definitiva, se trata de intentar divertirnos y ver resultados tangibles a través del trabajo que haremos mientras aprendemos todo acerca de este poderoso aspecto de WordPress.

Antes de empezar, necesitamos asegurarnos de que disponemos de un entorno de desarrollo preparado.

Los Comienzos

Recuerda que en el artículo anterior indicamos que nuestro entorno de desarrollo local debería consistir en:

WordPress 4.5.2
tu IDE preferido
un servidor web
una copia de PHP
una base de datos

Para muchos, Apache, PHP y MySQL resultan sencillos de instalar. Si eres un usuario más avanzado, quizá uses algo como Nginx y una base de datos alternativa. Si es tu caso, perfecto, pero para los propósitos de este tutorial voy a asumir que tienes el primero.

Y si no tienes ninguno preparado, no te preocupes: te lo explicamos. El tutorial del enlace te guiará sobre todo lo que necesitas para empezar a trabajar con WordPress en tu equipo local.

Una vez estes preparado, podremos proseguir.

Entender los Filtros de WordPress

El Codex de WordPress nos proporciona de un sencillo conjunto de recursos para aquellos que buscan conocer todo sobre los filtros. Como ya hemos indicado, define los filtros como sigue:

Los filtros personalizados difieren de las Acciones personalizadas ya que estas últimas te permiten agregar o eliminar código de Acciones existentes. Por otra parte los filtros personalizados te permiten sustituir datos específicos (como variables) encoptrados dentro de un Acción existente.

Pero si lo que buscas es una lista completa de filtros disponiblers para WordPress, entonces asegúrate de visitar (y marcar en favoritos) esta página del Codex. Contiene filtros que bien merece la pena detenerse 20 segundos, muchos de los cuales enlazan a su propia página de documentación.

Significa que si tienes curiosidad sobre la existencia de un filtro, no tienes más que consultar la página. Igualmente, puedes visitar la página de un filtro en particular para conocer los argumentos de sus parámetros, un ejemplo de la definición de una función, y cómo trabajar con él.

Algunas Palabras Sobre la Prioridad y los Parámetros

Antes de avanzar más, quiero asegurarme de que todos estamos en la misma en lo que se refiere a la prioridad y el número de argumentos a los que hace referencia cuando hablamos de ellos dentro del contexto de los hooks de WordPress.

Toma como ejemplo, el siguiente código:

1	<?php
2	add_filter( 'author_edit_pre', 'filter_function_name', 10, 2 );

Esto indica cuatro cosas:

el nombre del filtro al que estamos vinculando
el nombre de la función que debería ser convocada
la prioridad con la cual la función debería ser llamada
cuantos parámetros debería aceptar la función

Generalmente hablando, los dos primeros puntos se entienden fácilmente; y aunque, los otros dos pueden confundir a los desarrolladores novatos, no constituyen un concepto de difícil comprensión.

Primero, piensa en la prioridad como el cuando es llamada la función. Recuerda, desde el momento en el que un hook puede tener multiples funciones asociadas, la prioridad te permite definir con que celeridad o retardo será invocada tu función. Cuanto más bajo sea el número, más pronto será ejecutada; cuanto más alta sea la cifra, más se retrasará.

Segundo, el número indica cuantos parámetros admite un argumento. Si no especificas una cifra, o bien no aceptará ninguno o aceptará el argumento predeterminado. Si quieres indicar una cantidad diferente a lo que se espera, deberías especificar cuantos argumentos debe aceptar el argumento. Veremos esto detalladamente más adelante en el tutorial.

Trabajar Con Filtros

Para empezar a trabajar con filtros, avancemos y creémos nuestro propio archivo en el directorio raíz de twentysixteen. Llamaremos al archivo tutsplus-filters.php. Después, en el archivo functions.php de twentysixteen, añadiremos la siguiente línea de código.

1	<?php
2	include_once( get_template_directory() . '/tutsplus-filters.php' );

Esto asegurará que todo nuestro código a medida resida en un único archivo que podremos excluir cuando no deseemos usarlo. También lo mantiene aislado en su propia área, de manera que no se mezcle con cualquier código del tema.

Filtrar Contenido de Las Entradas

Antes de empezar a definir nuestros filtros, es importante entender como trabajan. Partiendo de la premisa de que los filtros están pensados para modificar datos y las entradas son bloques constructores de un blog, vamos a ver como podemos filtrar el contenido de una entrada del mismo antes de que se muestre en pantalla.

Mientras trabajas con este ejemplo, observa lo similar que es a la forma de trabajar con las acciones de WordPress, aunque en lugar de modificar el comportamiento, modifican datos.

1. Registrar Nuestro Filtro

Para registrar nuestro filtro, necesitamos dos piezas de información:

el nombre del filtro al que vamos a vincular nuestra función
una función que será la responsable de filtrar los datos

Como vamos a modificar contenido de una entrada, podemos tomar ventaja del filtro the_content. El proceso de la función es el siguiente:

acepta un sólo argumento, el contenido de la entrada, nos permite modificarlo, y devuelve el resultado al código que realiza la llamada.

En este caso, WordPress está enviando el contenido de la entrada a la función, y ésta devolverá la información cuando la haya procesado.

Llamemos a nuestra función tutsplus_the_content y después la registramos con WordPress.

<?php

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
    return $content;
}

Fundamentalmente, este es el aspecto que debería tener la función. Por supuesto, ahora no es de gran utilidad. Simplemente devuelve el contenido que ha procesado.

2. Modificar el Contenido

Hagamos que la función modifique los datos un poco más. Concretamente, vamos a hacer esto:

asegurarnos de que el post se ve en una página con una sola entrada.
añadir un mensaje sobre la entrada que explique que el contenido de la entrada está siendo modificado

No es el empleo más práctico de un filtro, pero te dará una idea de cómo puedes modificar una función.

Así es como debería ser el código. Presta también atención a los comentarios del código:

<?php

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {

    // Don't proceed with this function if we're not viewing a single post.
  if ( ! is_single() ) {
		return $content;
	}

	// First, define the message to be displayed.
	$html .= '<p>';
		$html .= 'This is a custom message created by a hooked function.';
	$html .= '</p>';

	// Now prepend it to the content.
	$content = $html .= $content;

	return $content;
}

Si miras la página en la vista de índice o en la vista principal del blog, entonces apreciarás que la entrada se muestra tal y como lo haría sin la modificación. Sin embargo, si visitas una entrada individual, verás que aparece una nueva frase por encima de cada artículo. Específicamente, verás esto:

Esto es un mensaje creado por una función vinculada.

Pero, hagamos algo más avanzado aún. Además de añadir un mensaje por encima del contenido, vamos a eliminar todas las vocales del contenido antes de devolverlo a WordPress.

Para conseguirlo, usaremos el siguiente código:

<?php

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {

    // Don't proceed with this function if we're not viewing a single post.
	if ( ! is_single() ) {
		return $content;
	}

	// First, remove all of the vowels from the content using a regular expression.
	$content = preg_replace( '$[aeiou]$i', '', $content );

	// Then, define the message to be displayed.
	$html .= '<p>';
		$html .= 'This is a custom message created by a hooked function.';
	$html .= '</p>';

	// And now prepend it to the content.
	$content = $html .= $content;

	return $content;
}

Implementa ese código y guarda, después visita cualquier entrada en tu instalación de WordPress.

Técnicamente, la función anterior realiza dos cosas, con el objetivo de mantener el código más cohesionado, recomiendo dividir el proceso en dos funciones separadas y que sea nuestra función de filtrado la que se encargue de invocar a ambas.

Aquí tienes el aspecto que debería tener el resultado:

<?php

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {

    // Don't proceed with this function if we're not viewing a single post.
	if ( ! is_single() ) {
		return $content;
	}

	$content = _tutsplus_strip_vowels( $content );
	$content = _tutsplus_add_message( $content );

	return $content;
}

function _tutsplus_strip_vowels( $content ) {
	return preg_replace( '$[aeiou]$i', '', $content );
}

function _tutsplus_add_message( $content ) {

	$html .= '<p>';
		$html .= 'This is a custom message created by a hooked function.';
	$html .= '</p>';

	return ( $html . $content );
}

Nuevamente, esta no es una implementación muy útil o práctica de un filtro, pero permite ver exactamente lo que podríamos hacer con nuestras propias funciones.

Definir Filtros Personalizados

Aunque es sencillo aprovechar la funcionalidad de los filtros pre-existentes. Como comentamos anteriormente, se trata simplemente de usar add_filter, especificando el nombre del filtro, y después indicar el nombre de la función que queremos invocar para que filtre los datos.

¿Pero qué sucede si queremos crear nuestro filtro personalizado? Quizá deseamos un filtro que convierta en minúsculas todo el texto de la entrada. O puede que queramos un filtro para eliminar todas sus vocales

Entender apply_filters

Aquí es donde empieza el interés en apply_filters. Esta función particular acepta dos argumentos:

una etiqueta que identifica el nombre del hook del filtro
un valor que hace referencia al orden con el cual el filtro debe ser aplicado

Si observases este ejemplo, get_the_content en el núcleo de WordPress, observarías que envía el valor especificado a través de the_content_more_link vía apply_filters.

Es útil entender esto, pero, ¿cómo definimos nuestros filtros personalizados como los que pueden llamar apply_filters en la funcionalidad que hemos desarrollado?

Añadir Nuestros Propios Filtros

Añadir nuestros propios filtros es fácil. Necesitamos especificar las mismas cuatro cosas que hemos destacado antes:

el nombre del filtro
la función que debería invocar el filtro
la prioridad de la función
el número de argumentos que debería aceptar

Empecemos con un simple ejemplo.

Convertir Todo en Minúsculas

Asegurarnos que todo el contenido de la entrada está en minúsculas.

Primero, queremos definir el filtro con una prioridad de 10. Sabemos que solo va a aceptar un argumento, el contenido, así que indicaremos la cifra 1 cuando añadamos nuestro filtro:

1	<?php
2	add_filter( 'tutsplus_lowercase_all', 'tutsplus_lowercase_all_callback', 10, 1 );

Continuamos definiendo la estructura de una función simple que usa la función PHP strtolower para transformar en minúculas cualquier valor que le haya sido enviado, y lo devolvemos.

1	<?php
2	function tutsplus_lowercase_all_callback( $content ) {
3	return strtolower( $content );
4	}

La versión final del código será algo así:

<?php
add_filter( 'tutsplus_lowercase_all', 'tutsplus_lowercase_all_callback', 10, 1 );
function tutsplus_lowercase_all_callback( $content ) {
    return strtolower( $content );
}

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {

    // Don't proceed with this function if we're not viewing a single post.
	if ( ! is_single() ) {
		return $content;
	}

	return apply_filters( 'tutsplus_lowercase_all', $content );
}

¿sobradamente simple como para no entenderlo, no? Echemos un vistazo a un ejemplo más basado en una funcionalidad que ya hemos visto.

Eliminar Todas las Vocales

Para eliminar todas las vocales, podemos emplear la misma función que acabamos de definir; aún así, tenemos que cambiar la manera en que se registra el filtro en WordPress, y después asegurarnos de que la función registrada invoca apply_filters adecuadamente.

Como ya hemos visto como añadir nuestro filtro, especificar una prioridad, definir el número de argumentos que debería aceptar, e implementar una función, no gastaré más tiempo en detalles triviales.

Aquí tenemos el filtro y cómo es llamado por sí mismo:

<?php

add_filter( 'tutsplus_remove_vowels', 'tutsplus_remove_vowels_callback', 10, 1 );
function tutsplus_remove_vowels_callback( $content ) {
    return preg_replace( '$[aeiou]$i', '', $content );
}

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {

	// Don't proceed with this function if we're not viewing a single post.
	if ( ! is_single() ) {
		return $content;
	}

	return apply_filters( 'tutsplus_remove_vowels', $content );
}

Y luego tenemos cómo puedes llamarlo desde el mismo hook inicial.

Invocar A Todos Juntos

Y para terminar, es posible invocar multiples veces apply_filters:

<?php

add_filter( 'tutsplus_remove_vowels', 'tutsplus_remove_vowels_callback', 10, 1 );
function tutsplus_remove_vowels_callback( $content ) {
    return preg_replace( '$[aeiou]$i', '', $content );
}

add_filter( 'tutsplus_lowercase_all', 'tutsplus_lowercase_all_callback', 10, 1 );
function tutsplus_lowercase_all_callback( $content ) {
	return strtolower( $content );
}

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {

	// Don't proceed with this function if we're not viewing a single post.
	if ( ! is_single() ) {
		return $content;
	}

	return apply_filters( 'tutsplus_lowercase_all',
					apply_filters( 'tutsplus_remove_vowels', $content )
				 );
}

Advierte con que esto se obtiene el mismo resultado que en los casos anteriores, pero lo hace condensándolo en una única línea de código. Existen también otras formas de escribir esto, pero el propósito de este tutorial es instruirte en como escribir tus propios filtros y como sacar ventaja de apply_filters en tu propio trabajo.

Conclusión

Con este tutorial concluye nuestra introducción a los hooks de WordPress. A través de la serie, hemos revisado como aprovechar los filtros y acciones existentes, así como a crear e implementar los tuyos propios.

El sistema de hooks es uno de los más poderosos aspectos de WordPress para los desarrolladores, así que es importante familiarizarse con ellos. Haciéndolo así, no solo eres capaz de manipular el comportamiento y datos que WordPress provee, sino también definir tus propios hooks que otros desarrolladores podrán usar en su código.

Te animo a seguir jugando con el código que hemos visto en ambos tutoriales.

Por último, si estás en busca de nuevas utilidades que amplíen tu selección de herramientas para WordPress o código para prepararte y convertirte en experto en WordPress, no olvides echar un vistazo a lo que tenemos en Envato Market.

Recuerda, puedes echar un vistazo a todos los cursos y tutoriales que he creado en mi página de perfil, y además seguirme a través de mi blog y/o Twitter en @tommcfarlin en donde hablo sobre practicas de desarrollo para diferentes tipos de software y como podemos emplearlas en WordPress.

Por favor no dudes en dejar tu consulta o comentarios en el feed inferior, mi ánimo es responderlos todos.