En este HowTo aprenderás cómo y cuando se deben usar los filtros de WordPress. Para ello usaremos la función add_filter() y apply_filters() cuando necesitemos crear filtros personalizados.
WordPress nos ofrece una gran cantidad de filtros que permiten tanto a plugins como temas modificar diferentes tipos de datos durante su ejecución. Por lo que estos filtros nos permiten interceptar cualquier tipo de dato y modificarlo durante su ejecución antes de que este sea enviado al navegador. Si ya has trabajado con event y observers en Magento2 te será muy fácil entender como funcionan ya que su funcionalidad es muy parecida.
Para entender correctamente que son los filtros vamos a profundizar en cómo funciona WordPress. Para la mayor parte de tareas de programación en WordPress usamos Hooks que nos permiten incrustar código en la página mientras está siendo generada. Estos Hooks pueden ser de dos tipos
- filtros (filter hooks)
- acciones (actions hooks)
Los filtros (filter hooks) nos permiten interceptar y manipular datos en tiempo de ejecución, antes de que estos sean enviados al navegador. Por ejemplo, en caso de querer modificar los comentarios que han enviando los usuarios para así filtrar y ocultar palabras no permitidas.
Las acciones (actions hooks) nos permiten incluir funcionalidades personalizadas durante la generación de la página. Por ejemplo, en caso de necesitar incluir un aviso con la politica de privacidad a pie de pagina usaremos el action hook wp_footer.
En conclusión, con los filtros modificamos una salida de datos y con las acciones incluimos funcionalidades.
add_filter()
La función de WordPress add_filter() nos va a permitir enlazar (hook) una función o método a una acción concreta. add_filter() acepta los siguientes parámetros:
- El nombre del filtro que queremos incluir. Para saber que filtro queremos usar, podemos consultarlo en la misma API siguiendo este enlace.
- Función o método que se va a ejecutar cuando el filtro es activado.
- El orden de prioridad a la hora de ejecutarse. Por defecto es 10.
- Un número de argumentos.
Los filtros pueden usarse de varias formas, veamos su sintaxis:
- En Programación Orientada a Objetos (OOP) a través un método estático de una clase.
1add_filter( 'the_title', [ '__CLASS__', 'metodo' ]); - En Programación Orientada a Objetos (OOP) a través un método público de una clase.
1add_filter( 'the_title', [ $this, 'metodo' ]); - La forma más usada, es a través de una función simple.
1add_filter( 'the_title', 'funcion' );Es probable que ni así tengamos claro para que sirven los filtros por lo que mejor será verlo en funcionamiento con ejemplos.
Puede ser difícil de entender sin un ejemplo práctico por lo que vamos a incluir el filtro the_title con el que vamos a poder modificar los títulos que tengan una fecha determinada y en caso de coincidencia incluimos el texto » | San Valentín».
1 2 3 4 5 6 7 8 9 10 11 12 |
<?php function add_text_to_title( $title ) { if ( get_the_date('Y-m-d') == "2019-02-14" ) { $title .= ' | Oferta'; } else { $title .= ''; } return $title; } add_filter( 'the_title', 'add_text_to_title' ); |
Voy a explicar este filtro paso a paso para que se entienda correctamente:
- Por un lado tenemos la función que va a ejecutarse con el filtro add_text_to_title()
- Dicha función recibe un argumento con el título de los Post o Páginas.
- La sentencia return es muy importante ya que nos permite retornar el título ya modificado.
- Por último tenemos que incluir la función add_filter() indicando el filtro the_title y la función que se encarga de manejar los datos recibidos por el filtro.
Sigamos viendo más ejemplos, en este caso usaremos el filtro the_comments y crearemos una función que nos va a permitir censurar palabras mal sonantes de los usuarios:
1 2 3 4 5 6 7 8 9 10 11 |
function censurar_comentarios( $content ) { $words = [ 'estúpido', 'subnormal' ]; $content = str_ireplace( $words, '{censurado}', $content ); return $content; } add_filter( 'comment_text', 'censurar_comentarios' ); |
Sigamos viendo más ejemplos, en este caso personalizaremos los extractos de los Post. En el primero modificaremos la cantidad de palabras a mostrar y en otro vamos a incluir un texto de leer más:
1 2 3 4 5 6 7 8 9 |
function custom_excerpt_length( $length ) { return 20; } add_filter( 'excerpt_length', 'custom_excerpt_length', 999 ); function custom_excerpt_more( $more ) { return '<a href="'.get_the_permalink().'" rel="nofollow">'.__(' leer más', 'artegrafico-gold').'</a>'; } add_filter( 'excerpt_more', 'custom_excerpt_more' ); |
WordPress nos ofrece un sin fin de filtros para poder modificar cualquier tipo de dato. Como es imposible memorizarlos cuando necesitemos de uno en concreto
es mejor que consultarlos en el siguiente enlace
¿Es posible desactivar filtros?
Si. Para desactivar un filtro usaremos la función remove_filter() al que le pasaremos el nombre del filtro y la función que queremos desactivar.
¿Y si necesito crear un filtro personalizado?
Ya hemos visto que WordPress permite incluir filtros de muchos tipos usando la función add_filter() pero también tenemos que saber que podemos crear nuestros propios filtros personalizados. Para ello usaremos la función apply_filters() y una vez creados los usaremos mediante add_filter()
La función applly_filters() acepta 3 parámetros:
- El nombre del filtro personalizado que estamos creando.
- El valor de retorno del filtro.
- Parámetros adicionales.
Para entender como funciona la función apply_filters() volveremos a utilizar un ejemplo. Vamos a crear un nuevo filtro al que vamos a llamar default_theme_options, el cual recibe un array de valores con las configuraciones de nuestro tema.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
if (!function_exists('default_theme_options ')) { function default_theme_options ( ) { $default_theme_options = [ 'background' => '#fff', 'excerpt' => true, 'excert_length' => 30 ]; return apply_filters( 'default_theme_options', $default_theme_options); } } |
Una vez hemos creado el filtro personalizado vamos a enlazar y agrupar estas configuraciones del nuevo filtro con las que tengamos creadas en nuestro tema. Por lo que tenemos que llamar al filtro que acabamos de crear anteriormente usando la función que ya conocemos add_filter() para así fusionar ambas configuraciones.
1 2 3 4 5 6 7 8 |
if (!function_exists('get_theme_options')) { function get_theme_options($default_theme_options) { $get_theme_options = get_theme_mods(); // get all theme options $array = array_merge($get_theme_options, $default_theme_options); return $array; } } add_filter('default_theme_options', 'get_theme_options'); |
Ahora debemos tener las configuraciones del nuevo filtro y las del tema en un sólo array para acceder a sus valores cuando los necesitemos.
1 2 |
$GLOBAL['theme_options'] = default_theme_options(); echo $GLOBAL['theme_options']['excert_length']; |
Recuerda que este es sólo es un ejemplo de uso de la función apply_filters(). Para acceder acceder a las configuraciones del tema se suele usar la función get_theme_mod()