WP_Query personalizzata

WPFilters è progettato per funzionare con la query principale di WordPress nelle pagine di archivio standard, nelle pagine delle categorie e nelle pagine principali del blog. Tuttavia, quando crei un modello di pagina personalizzato con la tua WP_Query, i post che desideri filtrare provengono dalla tua query personalizzata anziché dalla query principale di WordPress (che rappresenta la pagina stessa).

Per far funzionare WPFilters con una WP_Query personalizzata, devi contrassegnare la query con un flag speciale e utilizzare un markup HTML specifico. Questo indica a WPFilters di applicare la logica di filtraggio alla tua query personalizzata e consente al JavaScript frontend di aggiornare le parti corrette della pagina quando gli utenti interagiscono con i filtri.

Configurazione Richiesta

Flag Query

Devi aggiungere ‘wpfilters’ => true ai tuoi argomenti WP_Query. Questo contrassegna la query in modo che WPFilters applichi la sua logica di filtraggio, legga i parametri del filtro dall'URL, calcoli quali ID di post corrispondono ai filtri selezionati e aggiorni la query di conseguenza.

Senza questo flag, WPFilters tratta la tua query come una normale query non filtrata e la ignora completamente.

Nota: Non utilizzare ‘suppress_filters’ => true negli argomenti della tua query. WPFilters tratta le query soppresse allo stesso modo in cui WordPress tratta le chiamate a get_posts() e le salta completamente.

La tua query deve consentire l'esecuzione dei filtri affinché WPFilters funzioni correttamente.

Markup HTML Richiesto

WPFilters si basa su classi CSS e struttura HTML specifiche in modo che il JavaScript frontend possa individuare e aggiornare i corretti elementi della pagina durante il filtraggio AJAX:

Wrapper Risultati: L'output del tuo loop di post deve essere racchiuso in un elemento con la classe wpfilters-results. Dopo una richiesta AJAX di filtro, WPFilters sostituisce il contenuto all'interno di questo wrapper con i risultati filtrati.

Wrapper Paginazione: I tuoi link di paginazione dovrebbero essere racchiusi in un elemento con la classe wpfilters-pagination. Questo consente al JavaScript di trovare e aggiornare la paginazione dopo il filtraggio.

Senza queste classi wrapper, gli aggiornamenti AJAX potrebbero fallire o interessare elementi della pagina errati, causando il malfunzionamento dell'interfaccia del filtro.

Esempio di Modello

L'esempio seguente mostra un modello di pagina personalizzato completo che funziona con WPFilters. Questo modello è progettato per temi WordPress classici che utilizzano get_header() e get_footer(), come Twenty Twenty o temi child personalizzati.

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

Come Funziona il Modello

Il Flag Query wpfilters

L'argomento ‘wpfilters’ => true nella WP_Query contrassegna questa query per l'elaborazione di WPFilters. Quando questo flag è presente, WPFilters applica la sua logica di filtraggio leggendo i parametri del filtro dall'URL, calcolando quali ID di post corrispondono ai filtri selezionati e (durante le richieste AJAX) impostando post__in per visualizzare solo i post corrispondenti.

Wrapper Risultati

L'elemento <div class=”wpfilters-results”> racchiude l'intero output del loop di post. Questo wrapper è fondamentale perché il JavaScript frontend cerca questa classe per trovare dove inserire i risultati filtrati. Dopo che una richiesta AJAX di filtro è completata, WPFilters sostituisce il contenuto all'interno di questo wrapper con i nuovi post filtrati.

Per coerenza, anche il messaggio “nessun post trovato” è racchiuso in un elemento con la classe wpfilters-results. Questo garantisce che esista un elemento target stabile, indipendentemente dal fatto che vengano trovati o meno dei post.

Wrapper Paginazione

L'elemento <nav class=”wpfilters-pagination”> racchiude l'output di paginate_links(). Questo wrapper consente a JavaScript di individuare e aggiornare i link di paginazione dopo il filtraggio. Senza questo wrapper, la paginazione potrebbe non aggiornarsi correttamente quando i filtri cambiano.

Gestione Variabili Paginazione

I modelli di pagina utilizzano la variabile di query 'page' per la paginazione, mentre gli archivi utilizzano 'paged'. Il codice del modello gestisce entrambi prendendo il valore massimo di una delle due variabili, garantendo che la paginazione funzioni correttamente indipendentemente da quale variabile WordPress imposta.

Considerazioni Importanti

Allinea la Query alle Fonti dei Filtri

Le opzioni di filtro vengono generate automaticamente in base ai tipi di post inclusi nella tua WP_Query. WPFilters visualizza solo le opzioni di filtro pertinenti ai tipi di post che stai interrogando. Se la tua WP_Query non include tipi di post che hanno i dati della tassonomia o del campo personalizzato su cui si basano i tuoi filtri, tali opzioni di filtro non appariranno.

Ad esempio, se il tuo elemento filtro è configurato per mostrare le categorie ma la tua WP_Query include solo il tipo di post 'pagina', il filtro delle categorie apparirà vuoto perché le pagine in genere non hanno assegnazioni di categorie. Allo stesso modo, se hai un filtro di tassonomia personalizzata per i prodotti WooCommerce ma la tua query include solo post normali, non verranno visualizzate opzioni di filtro perché i post non utilizzano le tassonomie dei prodotti.

Conserva i Parametri URL nella Paginazione

WPFilters aggiunge le selezioni del filtro all'URL come parametri di query. Quando gli utenti navigano tra le pagine, questi parametri devono essere conservati in modo che i filtri rimangano attivi. Puoi estendere la funzione paginate_links() con il parametro 'add_args' per mantenere i parametri del filtro nei link di paginazione.

Passa solo chiavi di parametro sicure e conosciute per evitare problemi di sicurezza. Non copiare ciecamente tutti i valori da $_GET senza validazione.

Temi Block e Full Site Editing

Se stai utilizzando un tema a blocchi o un tema Full Site Editing (FSE) che non dispone dei tradizionali file header.php e footer.php, questo esempio di modello non funzionerà così com'è. Per i temi a blocchi, dovrai creare un tema figlio con supporto per modelli classici o utilizzare le parti di modello HTML e gli schemi di blocchi equivalenti del tema a blocchi.

Installazione e Configurazione

Posizione del File

Salva il file del modello nella directory del tuo tema attivo. Per un tema padre, posizionalo in: wp-content/themes/tuo-tema/wp-filters-query.php

Per una migliore manutenibilità, usa un tema figlio: wp-content/themes/tuo-tema-figlio/wp-filters-query.php

Assegna il Modello a una Pagina

Vai su Pagine → Aggiungi Nuova nella tua bacheca di WordPress
Nella barra laterale, trova l'opzione Modello
Seleziona “WP Filters — query personalizzata”
Pubblica o aggiorna la pagina

Visita la pagina sul frontend e testa i tuoi filtri e la paginazione.

Riepilogo

Usare WPFilters con una WP_Query personalizzata ti dà il pieno controllo su come i contenuti vengono visualizzati e filtrati. Marcare correttamente la tua query e strutturare il tuo template ti permette di creare esperienze di filtraggio potenti e dinamiche oltre gli archivi standard di WordPress.