Custom WP_Query - SearchWP

WPFilters foi projetado para funcionar com a consulta principal do WordPress em páginas de arquivo padrão, páginas de categoria e páginas iniciais do blog. No entanto, quando você cria um modelo de página personalizado com sua própria WP_Query, os posts que você deseja filtrar vêm de sua consulta personalizada em vez da consulta principal do WordPress (que representa a própria página).

Para fazer o WPFilters funcionar com uma WP_Query personalizada, você precisa marcar a consulta com uma flag especial e usar marcação HTML específica. Isso informa ao WPFilters para aplicar a lógica de filtragem à sua consulta personalizada e permite que o JavaScript do frontend atualize as partes corretas da página quando os usuários interagem com os filtros.

Configuração Necessária

Flag da Consulta

Você deve adicionar ‘wpfilters’ => true aos seus argumentos WP_Query. Isso marca a consulta para que o WPFilters aplique sua lógica de filtragem, leia os parâmetros do filtro da URL, calcule quais IDs de post correspondem aos filtros selecionados e atualize a consulta de acordo.

Sem essa flag, o WPFilters trata sua consulta como uma consulta normal não filtrada e a ignora completamente.

Observação: Não use ‘suppress_filters’ => true nos argumentos da sua consulta. O WPFilters trata consultas suprimidas da mesma forma que o WordPress trata chamadas get_posts() e as pula completamente.

Sua consulta deve permitir que os filtros sejam executados para que o WPFilters funcione corretamente.

Marcação HTML Necessária

O WPFilters depende de classes CSS e estrutura HTML específicas para que o JavaScript do frontend possa localizar e atualizar os elementos corretos da página durante a filtragem AJAX:

Wrapper de Resultados: A saída do seu loop de posts deve ser envolvida em um elemento com a classe wpfilters-results. Após uma solicitação AJAX de filtro, o WPFilters substitui o conteúdo dentro deste wrapper pelos resultados filtrados.

Wrapper de Paginação: Seus links de paginação devem ser envolvidos em um elemento com a classe wpfilters-pagination. Isso permite que o JavaScript encontre e atualize a paginação após a filtragem.

Sem essas classes de wrapper, as atualizações AJAX podem falhar ou atingir elementos incorretos da página, fazendo com que a interface do filtro funcione mal.

Exemplo de Template

O exemplo a seguir mostra um modelo de página personalizado completo que funciona com o WPFilters. Este modelo foi projetado para temas clássicos do WordPress que usam get_header() e get_footer(), como Twenty Twenty ou temas filhos 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

Como o Template Funciona

A Flag de Consulta wpfilters

O argumento ‘wpfilters’ => true na WP_Query marca esta consulta para processamento pelo WPFilters. Quando essa flag está presente, o WPFilters aplica sua lógica de filtragem lendo os parâmetros de filtro da URL, calculando quais IDs de post correspondem aos filtros selecionados e (durante solicitações AJAX) definindo post__in para exibir apenas os posts correspondentes.

Wrapper de Resultados

O elemento <div class=”wpfilters-results”> envolve toda a saída do loop de posts. Este wrapper é crucial porque o JavaScript do frontend procura por esta classe para encontrar onde injetar os resultados filtrados. Após a conclusão de uma solicitação AJAX de filtro, o WPFilters substitui o conteúdo dentro deste wrapper pelos novos posts filtrados.

Para consistência, até a mensagem “nenhum post encontrado” é envolvida em um elemento com a classe wpfilters-results. Isso garante que um elemento de destino estável exista, quer os posts sejam encontrados ou não.

Contêiner de Paginação

O elemento <nav class=”wpfilters-pagination”> envolve a saída do paginate_links(). Este contêiner permite que o JavaScript localize e atualize os links de paginação após a filtragem. Sem este contêiner, a paginação pode não ser atualizada corretamente quando os filtros mudam.

Tratamento de Variáveis de Paginação

Modelos de página usam a variável de consulta page para paginação, enquanto arquivos usam paged. O código do modelo lida com ambos, pegando o valor máximo de qualquer uma das variáveis, garantindo que a paginação funcione corretamente, independentemente de qual variável o WordPress define.

Considerações Importantes

Alinhar Consulta com Fontes de Filtro

As opções de filtro são geradas automaticamente com base nos tipos de post incluídos em sua WP_Query. WPFilters exibe apenas opções de filtro que são relevantes para os tipos de post que você está consultando. Se sua WP_Query não incluir tipos de post que tenham os dados de taxonomia ou campo personalizado dos quais seus filtros são construídos, essas opções de filtro não aparecerão.

Por exemplo, se seu elemento de filtro estiver configurado para mostrar categorias, mas sua WP_Query incluir apenas o tipo de post page, o filtro de categoria aparecerá vazio porque as páginas normalmente não têm atribuições de categoria. Da mesma forma, se você tiver um filtro de taxonomia personalizada para produtos WooCommerce, mas sua consulta incluir apenas posts regulares, nenhuma opção de filtro será exibida porque os posts não usam taxonomias de produtos.

Preservar Parâmetros de URL na Paginação

WPFilters adiciona seleções de filtro à URL como parâmetros de consulta. Quando os usuários navegam entre as páginas, esses parâmetros devem ser preservados para que os filtros permaneçam ativos. Você pode estender a função paginate_links() com o parâmetro 'add_args' para manter os parâmetros de filtro nos links de paginação.

Passe apenas chaves de parâmetro seguras e conhecidas para evitar problemas de segurança. Não copie cegamente todos os valores de $_GET sem validação.

Temas de Bloco e Edição Completa do Site

Se você estiver usando um tema de bloco ou um tema de Edição Completa do Site (FSE) que não tenha arquivos tradicionais header.php e footer.php, este exemplo de modelo não funcionará como está escrito. Para temas de bloco, você precisará criar um tema filho com suporte a modelo clássico ou usar as partes de modelo HTML e padrões de bloco equivalentes do tema de bloco.

Instalação e Configuração

Localização do Arquivo

Salve o arquivo do modelo em seu diretório de tema ativo. Para um tema pai, coloque-o em: wp-content/themes/seu-tema/wp-filters-query.php

Para melhor manutenibilidade, use um tema filho: wp-content/themes/seu-tema-filho/wp-filters-query.php

Atribuir Modelo a uma Página

Vá para Páginas → Adicionar Nova em seu admin do WordPress
Na barra lateral, encontre a opção Modelo
Selecione “WP Filters — consulta personalizada”
Publique ou atualize a página

Visite a página no frontend e teste seus filtros e paginação.

Resumo

Usar WPFilters com um WP_Query personalizado oferece controle total sobre como o conteúdo é exibido e filtrado. Ao marcar corretamente sua consulta e estruturar seu modelo, você pode criar experiências de filtragem poderosas e dinâmicas além dos arquivos padrão do WordPress.