– ¡Quieto todo el mundo! ¡Esto es un pre_get_posts! – Así puedo imaginarme el diálogo entre la acción pre_get_posts y el propio Core de WordPress. Y es que esta acción permite frenar y modificar la consulta SQL por defecto de cualquier plantilla de nuestra web ¿Quieres un ejemplo? Supongamos el listado de un Custom Post Type de «Automóviles», en lugar de devolver las últimas 10 entradas de automóviles podemos solicitar 5, o podemos indicar que nos lo devuelva ordenado por título en lugar de fecha de publicación o bien filtrar la búsqueda para no devolver cierto tipo de automóviles.

Sintáxis

<?php
/**
 *	Esta función modifica la consulta SQL estándar
 *	para una plantilla determinada.
 *
 *	@param $query WP_Query
 */
function funcion_para_modificar_la_consulta_por_defecto( $query ) {
	// Agregar al menos el condicional main-query
	if( $query->is_main_query() ):
		
		/*
		 * Aquí podemos modificar los valores del parámetro $query
		 * 
		 * En el ejemplo cambiamos a 5 las filas a devolver en lugar de
		 * las 10 filas que están configuradas en el administrador de
		 * WordPress.
		 */
		$query->set('posts_per_page', 5); 
		
	endif;
}
add_action( 'pre_get_posts', 'funcion_para_modificar_la_consulta_por_defecto' );

A la hora de usar esta acción es importante tener en cuenta los siguientes puntos:

  • Siempre poner el condicional $query->is_main_query() ya que WordPress realiza muchas consultas a base de datos antes de realizar la propia de la plantilla. De esta manera nos estamos asegurando que estaremos modificando la consulta adecuada.
  • Si queremos modificar la consulta de una plantilla específica deberemos agregar una nueva etiqueta condicional. Veamos este último punto en el siguiente ejemplo.

Caso de uso

Volvamos a utilizar el ejemplo que detallé en la introducción. Imaginemos que por algún motivo el cliente nos solicita mostrar el listado de los automóviles ordenados alfabéticamente. Ya sabemos que por defecto WordPress ordena los posts por la fecha en la que fueron escritos.

Para implementar esta funcionalidad deberemos llamar a nuestra ya conocida acción pre_get_posts y modificar los valores de orden de la consulta.

<?php
/**
 *	Esta función modifica la consulta del archive
 *	de automóviles para devolver los resultados
 *	ordenados por título.
 *
 *	@param $query WP_Query
 */
function mg_archive_coches_ordenados_por_titulo( $query ) {
	// Agregar el condicional main-query y también una etiqueta de plantilla.
	// De esta forma solo estamos modificando la consulta cuando un usuario
	// acceda al Archive de Coches.
	if( $query->is_main_query() && is_post_type_archive('coche') ):
		
		/*
		 * Modificamos la consulta para que el orden sea por tíulo
		 * en lugar de la fecha de publicación.
		 */
		$query->set( 'orderby', 'title' );
		$query->set( 'order', 'ASC' );
		
	endif;
}
add_action( 'pre_get_posts', 'mg_archive_coches_ordenados_por_titulo' );

Recuerda que puedes modificar cualquier valor de la clase WP_Query. Échale un vistazo al enlace al Codex de WordPress y márcala como favorito, seguro tendrás que volver pronto a utilizarla.

Otros posibles usos

También podríamos cancelar la búsqueda por defecto. Se estarán preguntando ¿Y por qué hacer eso? Puede surgir el caso en que la búsqueda por defecto no nos sirva en la plantilla que estamos trabajando y es una buena idea cancelarla así ahorramos un acceso innecesario a la base de datos. Basta simplemente con devolver un valor falso en la acción. Veamos el código de ejemplo.

<?php
/**
 *	Esta función modifica la consulta del archive
 *	de automóviles para devolver los resultados
 *	ordenados por título.
 *
 *	@param $query WP_Query
 */
function mg_cancelar_archive_socios( $query ) {
	// Por más que cancelemos la consulta siempre tendremos
	// que verificar que estamos atacando a la llamada correcta.
	if( $query->is_main_query() && is_post_type_archive('socios') ):
		
		// Cancelar la consulta SQL con un simple return false
		return false;
		
	endif;
}
add_action( 'pre_get_posts', 'mg_cancelar_archive_socios' );

Conclusión

pre_get_posts es uno de mis hooks preferidos. No hay proyecto en el que no lo utilice. Una vez que lo domines tendrás un panorama más amplio y un gran margen de movimiento sobre la jerarquía de plantilla aplicada a un proyecto. Y ya sabes que cualquier duda que tengas puedes dejarme tu comentario.

¡Feliz código!