Tutorial Child Theme IV. Filter Hooks

¿Qué son los Filter Hooks?

Filter hooksMuchas funciones de WordPress disponen de un “mecanismo” para cambiar su comportamiento sin modificar el código original. Este “mecanismo” se llama filter hook.

¿Donde se encuentran?

Los Filter hooks se encuentran en el core de WordPress (documentación codex), en los plugins y en las plantillas que instalamos. Para encontrarlos debemos revisar la documentación del desarrollador, pero a veces nos encontramos con que no existe. En ese caso podemos averigurar si los tiene, haciendo una busqueda dentro de ficheros php. Debemos buscar apply_filters

Los Filter hooks se encuentran en el core de WordPress, en los plugins y en las plantillas

¿Cómo funcionan?

Con frecuencia los filter hooks capturan la salida de las funciones infiltradas. En este caso lo habitual es reemplazar, borrar o añadir algo en esta salida. En otras ocasiones los filter hooks funcionan capturando los parámetros que necesita esa función.

¿Cómo se utilizan?

Los Filter Hook se pueden utilizar en el archivo functions.php de la plantilla, pero si queremos actualizar la plantilla sin perder nuestra personalización, mejor los utilizamos dentro de un Child Theme.

La mejor forma de usar los filter hooks es dentro de un Child Theme o plugin propio

Ejemplo paso a paso

Como en tutoriales anteriores vamos a utilizar Orbit como plantilla padre y creamos un Child Theme llamado childorbit.

Recordamos brevemente como hacerlo:

  • Añadimos una carpeta llamada childorbit dentro de la carpeta themes de nuestro WordPress
  • Creamos un fichero style.css con el siguiente contenido
/*
Theme Name: childorbit
Theme URI: bitado.com/childorbit
Description: Child Theme. Parent Theme Orbit
Author: Pinto
Author URI: bitado.com
Template: orbit
Version: 0.1
*/
@import url("../orbit/style.css");    
  • Activamos childorbit como plantilla de nuestro WordPress

El objetivo de este ejemplo es personalizar el breadcrumb de la plantilla Orbit. Necesitamos añadirle un enlace en el extremo derecho:

Final Breadcrumb

En la documentación de orbit localizamos el Filter Hook orbit_render_breadcrumb dentro de la función que muestra el breadcrumb. Esta es la línea de código del Filter hook infiltrado:

$output = apply_filters( 'orbit_render_breadcrumb', $output );

Ahora debemos crear un fichero llamado functions.php dentro de nuestro Child Theme.

En el fichero functions.php debemos crear una función para utilizar el filter hook:

<?php

add_filter( 'orbit_render_breadcrumb', 'childorbit_custom_breadcrumb' );
function childorbit_custom_breadcrumb( $output ) {
    return $output;
}

?>

La función add_filter nos permite usar el filter hook. El primer parámetro es el nombre del filter hook que hemos buscado previamente, y el segundo parámetro es una llamada a nuestra función que realiza los cambios apropiados.

En el código de la función original apply_filters pasa la variable $output al filter hook, que en este caso es un array con el html que saca a pantalla. Muchas veces es mejor logear estos parámetros para ver cómo debemos actuar.

Para logear en WordPress debemos tener activado el modo debug. Añadimos las siguientes lineas en wp-config.php:

define('WP_DEBUG',         true);
define('WP_DEBUG_DISPLAY', false);
define('WP_DEBUG_LOG',     true);

Con esto conseguimos depurar, sacando errores y mensajes al fichero log: wp-content/debug.log.

Logeamos la variable $output con la función error_log:

<?php

add_filter( 'orbit_render_breadcrumb', 'childorbit_custom_breadcrumb' );
function childorbit_custom_breadcrumb( $output ) {
    error_log( print_r( $output, TRUE ) );
    return $output;
}

?>

Cuando actualizamos el navegador el fichero debug.log nos muestra lo siguiente:

[11-Jun-2013 09:13:17 UTC] Array
(
    [content] => Home
    [before] => <div class="breadcrumb"><p>
    [after] => </p></div>
)   

Esto es el breadcrumb que muestra en el navegador:

Breadcrumb

Podemos añadir nuestro enlace personalizado en el elemento content del array $output.

$output['content'] .= '<span style="float: right; margin-right: 24px;"><a href="#">Filter in breadcrumb</a></span>';    

El fichero functions.php queda así:

<?php

add_filter( 'orbit_render_breadcrumb', 'childorbit_custom_breadcrumb' );
function childorbit_custom_breadcrumb( $output ) {
     $output['content'] .= '<span style="float: right; margin-right: 24px;"><a href="#">Filter in breadcrumb</a></span>';

    return $output;
}

?>   

Cuando actualizamos el navegador, este es el resultado final:

Final Breadcrumb

Básicamente lo que hace un filter hooks es infiltrarse en una determinada función y actualizar sus parámetros para modificar su comportamiento. Esto nos da unas ventajas importantes:

  • Resulta más fácil personalizar el código.
  • Al tener separado el código, el mantenimiento de nuestras modificaciones resulta más fácil.
  • Si actualizamos WordPress y las plantillas, no perderemos nuestra personalización (Si usamos Child Themes)

Puedes bajar el código desde aquí

Comentarios

  1. Hola Pedro, muchas gracias por tus excelente e instructivos artículos.
    Mi pregunta, tenemos Hooks Action y Filter, que deben escribirse en el fichero functions, php del child theme: ¿ambos tipos de hooks pueden coexistir en el mismo fichero functions, php sin problema alguno?
    Gracias nuevamente, y saludos.
    Guillermo

Responder a Pedro Pinto Cancelar respuesta

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