Custom WP_Query - SearchWP

WPFilters está diseñado para funcionar con la consulta principal de WordPress en páginas de archivo estándar, páginas de categorías y páginas de inicio del blog. Sin embargo, cuando creas una plantilla de página personalizada con tu propia WP_Query, las publicaciones que deseas filtrar provienen de tu consulta personalizada en lugar de la consulta principal de WordPress (que representa la página en sí).

Para que WPFilters funcione con una WP_Query personalizada, debes marcar la consulta con una bandera especial y usar una marca HTML específica. Esto le dice a WPFilters que aplique la lógica de filtrado a tu consulta personalizada y permite que el JavaScript del frontend actualice las partes correctas de la página cuando los usuarios interactúan con los filtros.

Configuración Requerida

Bandera de Consulta

Debes agregar ‘wpfilters’ => true a tus argumentos de WP_Query. Esto marca la consulta para que WPFilters aplique su lógica de filtrado, lea los parámetros del filtro de la URL, calcule qué IDs de publicación coinciden con los filtros seleccionados y actualice la consulta en consecuencia.

Sin esta bandera, WPFilters trata tu consulta como una consulta normal sin filtrar y la ignora por completo.

Nota: No uses ‘suppress_filters’ => true en tus argumentos de consulta. WPFilters trata las consultas suprimidas de la misma manera que WordPress trata las llamadas a get_posts() y las omite por completo.

Tu consulta debe permitir que se ejecuten los filtros para que WPFilters funcione correctamente.

Marca HTML Requerida

WPFilters se basa en clases CSS específicas y una estructura HTML para que el JavaScript del frontend pueda localizar y actualizar los elementos correctos de la página durante el filtrado AJAX:

Contenedor de Resultados: La salida de tu bucle de publicaciones debe estar envuelta en un elemento con la clase wpfilters-results. Después de una solicitud AJAX de filtro, WPFilters reemplaza el contenido dentro de este contenedor con los resultados filtrados.

Contenedor de Paginación: Tus enlaces de paginación deben estar envueltos en un elemento con la clase wpfilters-pagination. Esto permite que el JavaScript encuentre y actualice la paginación después de filtrar.

Sin estas clases contenedoras, las actualizaciones AJAX pueden fallar o dirigirse a elementos de página incorrectos, lo que provoca un mal funcionamiento de la interfaz de filtro.

Plantilla de Ejemplo

El siguiente ejemplo muestra una plantilla de página personalizada completa que funciona con WPFilters. Esta plantilla está diseñada para temas clásicos de WordPress que usan get_header() y get_footer(), como Twenty Twenty o temas hijos personalizados.

	<?php
	/**
	* Template Name: WP Filters — custom query
	*
	* @package YourTheme
	*/

	get_header();
	?>

	<main id="primary" class="site-main">
	<div class="section-inner">

	<header class="page-header">
	<h1 class="entry-title">
	<?php esc_html_e( 'Custom query with WPFilters', 'your-textdomain' ); ?>
	</h1>
	</header>

	<div class="wpfilters-wrapper">

	<aside
	class="wpfilters-sidebar widget-area"
	role="complementary"
	aria-label="<?php esc_attr_e( 'Filters', 'your-textdomain' ); ?>"
	>
	<?php
	if ( class_exists( '\WPFilters\Renderer' ) ) {
	echo \WPFilters\Renderer::render( 1 ); // Search.
	echo \WPFilters\Renderer::render( 2 ); // Category.
	echo \WPFilters\Renderer::render( 3 ); // Post type.
	}
	?>
	</aside>

	<div class="wpfilters-content content-area">

	<?php
	// Page templates use `page`; archives use `paged`.
	$paged = max(
	1,
	(int) get_query_var( 'paged' ),
	(int) get_query_var( 'page' )
	);

	$args = array(
	'post_type' => array( 'post', 'page' ),
	'post_status' => 'publish',
	'posts_per_page' => 10,
	'paged' => $paged,
	'orderby' => 'title',
	'order' => 'ASC',
	'wpfilters' => true,
	);

	$query = new WP_Query( $args );
	?>

	<?php if ( $query->have_posts() ) : ?>

	<div class="wpfilters-results">

	<?php
	while ( $query->have_posts() ) :
	$query->the_post();
	?>

	<article
	id="post-<?php the_ID(); ?>"
	<?php post_class( 'entry' ); ?>
	>
	<h2 class="entry-title">
	<a href="<?php the_permalink(); ?>">
	<?php the_title(); ?>
	</a>
	</h2>

	<div class="entry-summary">
	<?php the_excerpt(); ?>
	</div>
	</article>

	<?php endwhile; ?>

	</div>

	<nav
	class="wpfilters-pagination navigation pagination"
	aria-label="<?php esc_attr_e( 'Posts pagination', 'your-textdomain' ); ?>"
	>
	<?php
	echo paginate_links(
	array(
	'total' => $query->max_num_pages,
	'current' => $paged,
	'mid_size' => 2,
	'prev_text' => __( 'Previous', 'your-textdomain' ),
	'next_text' => __( 'Next', 'your-textdomain' ),
	)
	);
	?>
	</nav>

	<?php else : ?>

	<p class="wpfilters-results">
	<?php esc_html_e( 'No posts found.', 'your-textdomain' ); ?>
	</p>

	<?php endif; ?>

	<?php wp_reset_postdata(); ?>

	</div>
	</div>
	</div>
	</main>

	<?php
	get_footer();
	?>

view raw page-wpfilters.php hosted with ❤ by GitHub

Cómo Funciona la Plantilla

La Bandera de Consulta de WPFilters

El argumento ‘wpfilters’ => true en la WP_Query marca esta consulta para el procesamiento de WPFilters. Cuando esta bandera está presente, WPFilters aplica su lógica de filtrado leyendo los parámetros del filtro de la URL, calculando qué IDs de publicación coinciden con los filtros seleccionados y (durante las solicitudes AJAX) estableciendo post__in para mostrar solo las publicaciones coincidentes.

Contenedor de Resultados

El elemento <div class=”wpfilters-results”> envuelve toda la salida del bucle de publicaciones. Este contenedor es fundamental porque el JavaScript del frontend busca esta clase para encontrar dónde inyectar los resultados filtrados. Después de que se completa una solicitud AJAX de filtro, WPFilters reemplaza el contenido dentro de este contenedor con las nuevas publicaciones filtradas.

Por coherencia, incluso el mensaje "no se encontraron publicaciones" está envuelto en un elemento con la clase wpfilters-results. Esto asegura que exista un elemento objetivo estable, independientemente de si se encuentran o no publicaciones.

Contenedor de paginación

El elemento <nav class=\"wpfilters-pagination\" > envuelve la salida de paginate_links(). Este contenedor permite que JavaScript localice y actualice los enlaces de paginación después de filtrar. Sin este contenedor, la paginación podría no actualizarse correctamente cuando cambian los filtros.

Manejo de variables de paginación

Las plantillas de página utilizan la variable de consulta de página para la paginación, mientras que los archivos usan 'paged'. El código de la plantilla maneja ambas tomando el valor máximo de cualquiera de las variables, asegurando que la paginación funcione correctamente independientemente de qué variable establezca WordPress.

Consideraciones importantes

Alinear consulta con fuentes de filtros

Las opciones de filtro se generan automáticamente basándose en los tipos de publicación incluidos en tu WP_Query. WPFilters solo muestra opciones de filtro que son relevantes para los tipos de publicación que estás consultando. Si tu WP_Query no incluye tipos de publicación que tengan los datos de taxonomía o campo personalizado de los que se basan tus filtros, esas opciones de filtro no aparecerán.

Por ejemplo, si tu elemento de filtro está configurado para mostrar categorías pero tu WP_Query solo incluye el tipo de publicación de página, el filtro de categoría aparecerá vacío porque las páginas normalmente no tienen asignaciones de categoría. De manera similar, si tienes un filtro de taxonomía personalizada para productos de WooCommerce pero tu consulta solo incluye publicaciones normales, no se mostrarán opciones de filtro porque las publicaciones no usan taxonomías de productos.

Preservar parámetros de URL en la paginación

WPFilters agrega selecciones de filtro a la URL como parámetros de consulta. Cuando los usuarios navegan entre páginas, estos parámetros deben conservarse para que los filtros permanezcan activos. Puedes extender la función paginate_links() con el parámetro 'add_args' para mantener los parámetros de filtro en los enlaces de paginación.

Pasa solo claves de parámetros seguras y conocidas para evitar problemas de seguridad. No copies ciegamente todos los valores de $_GET sin validación.

Temas de bloques y edición completa del sitio

Si estás utilizando un tema de bloques o un tema de Edición Completa del Sitio (FSE) que no tiene archivos tradicionales header.php y footer.php, este ejemplo de plantilla no funcionará como está escrito. Para temas de bloques, necesitarás crear un tema hijo con soporte de plantilla clásica o usar las partes de plantilla HTML y los patrones de bloques equivalentes del tema de bloques.

Instalación y configuración

Ubicación del archivo

Guarda el archivo de plantilla en el directorio de tu tema activo. Para un tema padre, colócalo en: wp-content/themes/tu-tema/wp-filters-query.php

Para una mejor mantenibilidad, usa un tema hijo: wp-content/themes/tu-tema-hijo/wp-filters-query.php

Asignar plantilla a una página

Ve a Páginas → Añadir nueva en tu administrador de WordPress
En la barra lateral, busca la opción Plantilla
Selecciona "WP Filters — consulta personalizada"
Publica o actualiza la página

Visita la página en el frontend y prueba tus filtros y paginación.

Resumen

Usar WPFilters con una WP_Query personalizada te da control total sobre cómo se muestra y filtra el contenido. Al marcar correctamente tu consulta y estructurar tu plantilla, puedes crear experiencias de filtrado potentes y dinámicas más allá de los archivos estándar de WordPress.