Custom WP_Query - SearchWP

WPFilters est conçu pour fonctionner avec la requête principale de WordPress sur les pages d'archives standard, les pages de catégories et les pages d'accueil du blog. Cependant, lorsque vous créez un modèle de page personnalisé avec votre propre WP_Query, les articles que vous souhaitez filtrer proviennent de votre requête personnalisée plutôt que de la requête principale de WordPress (qui représente la page elle-même).

Pour que WPFilters fonctionne avec une WP_Query personnalisée, vous devez marquer la requête avec un indicateur spécial et utiliser une balise HTML spécifique. Cela indique à WPFilters d'appliquer la logique de filtrage à votre requête personnalisée et permet au JavaScript côté client de mettre à jour les parties correctes de la page lorsque les utilisateurs interagissent avec les filtres.

Configuration requise

Indicateur de requête

Vous devez ajouter ‘wpfilters’ => true à vos arguments WP_Query. Cela marque la requête afin que WPFilters applique sa logique de filtrage, lise les paramètres de filtre dans l'URL, calcule quels ID d'article correspondent aux filtres sélectionnés et mette à jour la requête en conséquence.

Sans cet indicateur, WPFilters traite votre requête comme une requête normale non filtrée et l'ignore complètement.

Note : N'utilisez pas ‘suppress_filters’ => true dans vos arguments de requête. WPFilters traite les requêtes supprimées de la même manière que WordPress traite les appels get_posts() et les ignore complètement.

Votre requête doit permettre l'exécution des filtres pour que WPFilters fonctionne correctement.

Marquage HTML requis

WPFilters s'appuie sur des classes CSS et une structure HTML spécifiques afin que le JavaScript côté client puisse localiser et mettre à jour les éléments corrects de la page lors du filtrage AJAX :

Conteneur des résultats : La sortie de votre boucle d'articles doit être enveloppée dans un élément avec la classe wpfilters-results. Après une requête AJAX de filtrage, WPFilters remplace le contenu de ce conteneur par les résultats filtrés.

Conteneur de pagination : Vos liens de pagination doivent être enveloppés dans un élément avec la classe wpfilters-pagination. Cela permet au JavaScript de trouver et de mettre à jour la pagination après le filtrage.

Sans ces classes de conteneur, les mises à jour AJAX peuvent échouer ou cibler les mauvais éléments de page, ce qui entraîne un dysfonctionnement de l'interface de filtrage.

Exemple de modèle

L'exemple suivant montre un modèle de page personnalisé complet qui fonctionne avec WPFilters. Ce modèle est conçu pour les thèmes WordPress classiques qui utilisent get_header() et get_footer(), tels que Twenty Twenty ou les thèmes enfants personnalisés.

	<?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

Comment le modèle fonctionne

L'indicateur de requête wpfilters

L'argument ‘wpfilters’ => true dans la WP_Query marque cette requête pour le traitement par WPFilters. Lorsque cet indicateur est présent, WPFilters applique sa logique de filtrage en lisant les paramètres de filtre à partir de l'URL, en calculant quels ID d'article correspondent aux filtres sélectionnés et (lors des requêtes AJAX) en définissant post__in pour n'afficher que les articles correspondants.

Conteneur des résultats

L'élément <div class=”wpfilters-results”> enveloppe la sortie complète de la boucle d'articles. Ce conteneur est essentiel car le JavaScript côté client recherche cette classe pour trouver où injecter les résultats filtrés. Une fois qu'une requête AJAX de filtrage est terminée, WPFilters remplace le contenu de ce conteneur par les nouveaux articles filtrés.

Par souci de cohérence, même le message « aucun article trouvé » est encapsulé dans un élément avec la classe wpfilters-results. Cela garantit qu'un élément cible stable existe, que des articles soient trouvés ou non.

Conteneur de pagination

L'élément <nav class='wpfilters-pagination'> encapsule la sortie de paginate_links(). Ce conteneur permet au JavaScript de localiser et de mettre à jour les liens de pagination après le filtrage. Sans ce conteneur, la pagination pourrait ne pas être mise à jour correctement lorsque les filtres changent.

Gestion des variables de pagination

Les modèles de page utilisent la variable de requête 'page' pour la pagination, tandis que les archives utilisent 'paged'. Le code du modèle gère les deux en prenant la valeur maximale de l'une ou l'autre variable, garantissant ainsi que la pagination fonctionne correctement, quelle que soit la variable définie par WordPress.

Considérations importantes

Aligner la requête avec les sources de filtres

Les options de filtre sont générées automatiquement en fonction des types d'articles inclus dans votre WP_Query. WPFilters n'affiche que les options de filtre pertinentes pour les types d'articles que vous interrogez. Si votre WP_Query n'inclut pas les types d'articles qui ont les données de taxonomie ou de champ personnalisé sur lesquelles vos filtres sont construits, ces options de filtre n'apparaîtront pas.

Par exemple, si votre élément de filtre est configuré pour afficher les catégories mais que votre WP_Query n'inclut que le type d'article 'page', le filtre de catégorie apparaîtra vide car les pages n'ont généralement pas d'affectations de catégorie. De même, si vous avez un filtre de taxonomie personnalisée pour les produits WooCommerce mais que votre requête n'inclut que des articles ordinaires, aucune option de filtre ne s'affichera car les articles n'utilisent pas les taxonomies de produits.

Conserver les paramètres d'URL dans la pagination

WPFilters ajoute les sélections de filtres à l'URL sous forme de paramètres de requête. Lorsque les utilisateurs naviguent entre les pages, ces paramètres doivent être conservés pour que les filtres restent actifs. Vous pouvez étendre la fonction paginate_links() avec le paramètre 'add_args' pour conserver les paramètres de filtre dans les liens de pagination.

Ne passez que des clés de paramètres sûres et connues pour éviter les problèmes de sécurité. Ne copiez pas aveuglément toutes les valeurs de $_GET sans validation.

Thèmes de blocs et d'édition complète du site

Si vous utilisez un thème de bloc ou un thème d'édition complète du site (FSE) qui n'a pas de fichiers header.php et footer.php traditionnels, cet exemple de modèle ne fonctionnera pas tel quel. Pour les thèmes de blocs, vous devrez soit créer un thème enfant avec la prise en charge des modèles classiques, soit utiliser les parties de modèle HTML et les modèles de blocs équivalents du thème de bloc.

Installation et configuration

Emplacement du fichier

Enregistrez le fichier modèle dans le répertoire de votre thème actif. Pour un thème parent, placez-le à : wp-content/themes/votre-theme/wp-filters-query.php

Pour une meilleure maintenabilité, utilisez un thème enfant : wp-content/themes/votre-theme-enfant/wp-filters-query.php

Attribuer un modèle à une page

Accédez à Pages → Ajouter dans votre administration WordPress
Dans la barre latérale, trouvez l'option Modèle
Sélectionnez « WP Filters — requête personnalisée »
Publiez ou mettez à jour la page

Visitez la page sur le front-end et testez vos filtres et votre pagination.

Résumé

L'utilisation de WPFilters avec une WP_Query personnalisée vous donne un contrôle total sur la manière dont le contenu est affiché et filtré. En marquant correctement votre requête et en structurant votre modèle, vous pouvez créer des expériences de filtrage puissantes et dynamiques au-delà des archives WordPress standard.