WordPress Hooks: Filters

En la entrada anterior vimos lo que eran los Actions en WordPress. En esta vamos a ver el otro tipo de hook: los filters.

Los Filters o filtros son un concepto parecido a los Actions. La diferencia es que su propósito es modificar la salida de información antes de que sea grabada en base de datos o mostrada en pantalla. Es decir, es una función a la cual podemos pasar información con el objetivo de manipular textos y contenidos antes de ser utilizados, por ejemplo modificar el título de un post antes de ser mostrado en pantalla.

Dicho de otro modo: Tengo esta información, modifícala por esta otra.

Si aún no ha quedado claro, vamos a verlo mejor con un par de ejemplos. El primero utilizando un filtro típico de WordPress, the_content, y en el segundo veremos cómo crear nuestros propios filtros en un plugin o tema.

Alterando el contenido de un post mediante el filter the_content

Para utilizar los filtros deberemos utilizar la función add_filter() de WordPress:

add_filter( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 );

Donde

• $tag (requerido): El nombre del filtro sobre el que queremos actuar.
• $function_to_add (requerido): La función que se ejecutará cuando el filtro se aplique.
• $priority (opcional): Prioridad de ejecución respecto a otras funciones que pueden también engancharse al filtro. El valor por defecto es 10. Valores bajos corresponden a mayor prioridad de ejecución.
• $accepted_args (opcional): El número de argumentos que la función acepta. Por defecto 1.

WordPress dispone de multitud de filtros, puedes ver la relación de todos ellos aquí. Uno de los que más se utilizan es el filtro the_content. Éste filtro se ejecuta antes de mostrar el contenido de un post en pantalla. Se utiliza mucho para añadir información adicional como publicidad, scripts, posts relacionados, etc… al final del contenido

<?php

function add_text_to_content($content) {
    $content .= " | Escrito por Pablo López";

    return $content;
}
add_filter( 'the_content', 'add_text_to_content' );

Como puede verse, a la variable $content, que tiene el contenido de nuestro post, concatenamos el texto Escrito por Pablo López. Retornamos la variable $content modificada por nosotros. Ésto es importante, a diferencia de los Actions, un Filter siempre debe retornar un valor.

Creando nuestros propios Filters

Crear filtros en nuestros temas y/o plugins es una buena práctica, ya que nos dará flexibilidad de cara al futuro para hacer ciertas modificaciones. Imaginemos que estamos haciendo un plugin que tiene un formulario para recoger una serie de datos.

Entre estos datos pintamos un select con rangos de edad: 0 – 10, 11 – 20, 21 – 30, 31 – 40, 41 – 50, +50. Si queremos dejar una puerta abierta para nosotros o para que un tercero pueda modificar estos valores, crearemos un filter con la función apply_filters().

<?php

function get_age_range() {
    $ranges = array(
        '0 - 10',
        '11 - 20',
        '21 - 30',
        '31 - 40',
        '41 - 50',
        '+50'
    );

    $list = '<select>';

    if ( has_filter( 'age_range' ) ) {
        $ranges = apply_filters( 'age_range', $ranges );
    }

    foreach ( $ranges as $key => $range ) :
        $list .= '<option value="' . $key . '">' . $range . '</option>';
    endforeach;

    $list .= '</select>';

    return $list;
}

function add_new_age_range( $ranges ) {
    unset($ranges[5]);

    $new_ranges = array(
        '51 - 60',
        '+61'
    );

    $ranges = array_merge($ranges, $new_ranges);

    return $ranges;
}
add_filter( 'age_range', 'add_new_age_range', 10, 1 );

La primera función get_age_range() es la que pinta el select de rango de edades. Como puede verse hemos creado el filter age_range con la función apply_filters().

En este ejemplo tenemos otra función add_new_age_range() que elimina el último rango de edad (+50) y añade dos tramos más. Esta función es a la que llamaremos desde add_filter() para modificar el contenido del select de nuestro tema o plugin.

De este modo dejamos la puerta abierta para poder actuar sobre el retorno en pantalla de una función a través de un filtro.

• « WordPress Hooks: Actions
• Los 10 mandamientos del WPO… »