Benutzerdefinierte WP_Query

WPFilters ist dafür konzipiert, mit der Hauptabfrage von WordPress auf Standard-Archivseiten, Kategorieseiten und Blog-Homepages zu arbeiten. Wenn Sie jedoch eine benutzerdefinierte Seitenvorlage mit Ihrer eigenen WP_Query erstellen, stammen die zu filternden Beiträge aus Ihrer benutzerdefinierten Abfrage und nicht aus der Hauptabfrage von WordPress (die die Seite selbst darstellt).

Damit WPFilters mit einer benutzerdefinierten WP_Query funktioniert, müssen Sie die Abfrage mit einem speziellen Flag markieren und spezifisches HTML-Markup verwenden. Dies teilt WPFilters mit, die Filterlogik auf Ihre benutzerdefinierte Abfrage anzuwenden und ermöglicht es dem Frontend-JavaScript, die richtigen Teile der Seite zu aktualisieren, wenn Benutzer mit Filtern interagieren.

Erforderliche Einrichtung

Abfrage-Flag

Sie müssen 'wpfilters' => true zu Ihren WP_Query-Argumenten hinzufügen. Dies markiert die Abfrage, damit WPFilters seine Filterlogik anwendet, Filterparameter aus der URL liest, berechnet, welche Beitrags-IDs mit den ausgewählten Filtern übereinstimmen, und die Abfrage entsprechend aktualisiert.

Ohne dieses Flag behandelt WPFilters Ihre Abfrage als normale, ungefilterte Abfrage und ignoriert sie vollständig.

Hinweis: Verwenden Sie nicht 'suppress_filters' => true in Ihren Abfrageargumenten. WPFilters behandelt unterdrückte Abfragen genauso wie WordPress get_posts()-Aufrufe und überspringt sie vollständig.

Ihre Abfrage muss das Ausführen von Filtern zulassen, damit WPFilters ordnungsgemäß funktioniert.

Erforderliches HTML-Markup

WPFilters ist auf spezifische CSS-Klassen und HTML-Strukturen angewiesen, damit das Frontend-JavaScript die richtigen Seitenelemente während des AJAX-Filterns lokalisieren und aktualisieren kann:

Ergebnis-Wrapper: Ihre Beitrags-Loop-Ausgabe muss in einem Element mit der Klasse wpfilters-results umschlossen sein. Nach einer Filter-AJAX-Anfrage ersetzt WPFilters den Inhalt innerhalb dieses Wrappers durch die gefilterten Ergebnisse.

Paginierungs-Wrapper: Ihre Paginierungslinks sollten in einem Element mit der Klasse wpfilters-pagination umschlossen sein. Dies ermöglicht es dem JavaScript, die Paginierung nach dem Filtern zu finden und zu aktualisieren.

Ohne diese Wrapper-Klassen können die AJAX-Aktualisierungen fehlschlagen oder die falschen Seitenelemente ansprechen, was zu Fehlfunktionen der Filteroberfläche führt.

Beispielvorlage

Das folgende Beispiel zeigt eine vollständige benutzerdefinierte Seitenvorlage, die mit WPFilters funktioniert. Diese Vorlage ist für klassische WordPress-Themes konzipiert, die get_header() und get_footer() verwenden, wie z. B. Twenty Twenty oder benutzerdefinierte Child-Themes.

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

Wie die Vorlage funktioniert

Das wpfilters Query Flag

Das Argument 'wpfilters' => true in der WP_Query markiert diese Abfrage für die WPFilters-Verarbeitung. Wenn dieses Flag vorhanden ist, wendet WPFilters seine Filterlogik an, indem es Filterparameter aus der URL liest, berechnet, welche Beitrags-IDs mit den ausgewählten Filtern übereinstimmen, und (während AJAX-Anfragen) post__in setzt, um nur die übereinstimmenden Beiträge anzuzeigen.

Ergebnis-Wrapper

Das Element <div class=”wpfilters-results”> umschließt die gesamte Ausgabe der Beitrags-Loop. Dieser Wrapper ist entscheidend, da das Frontend-JavaScript nach dieser Klasse sucht, um zu finden, wo gefilterte Ergebnisse eingefügt werden sollen. Nach Abschluss einer Filter-AJAX-Anfrage ersetzt WPFilters den Inhalt innerhalb dieses Wrappers durch die neuen gefilterten Beiträge.

Der "keine Beiträge gefunden"-Hinweis ist aus Konsistenzgründen ebenfalls in ein Element mit der Klasse wpfilters-results eingeschlossen. Dies stellt sicher, dass ein stabiles Zielelement vorhanden ist, unabhängig davon, ob Beiträge gefunden werden oder nicht.

Paginierungs-Wrapper

Das Element <nav class=”wpfilters-pagination”> umschließt die Ausgabe von paginate_links(). Dieser Wrapper ermöglicht es JavaScript, die Paginierungslinks nach dem Filtern zu lokalisieren und zu aktualisieren. Ohne diesen Wrapper werden die Paginierungslinks möglicherweise nicht korrekt aktualisiert, wenn sich die Filter ändern.

Behandlung von Paginierungsvariablen

Seitenvorlagen verwenden die Seiten-Query-Variable für die Paginierung, während Archive paged verwenden. Der Vorlagencode behandelt beide, indem er den Maximalwert beider Variablen nimmt, um sicherzustellen, dass die Paginierung unabhängig davon korrekt funktioniert, welche Variable WordPress setzt.

Wichtige Überlegungen

Query mit Filterquellen abgleichen

Filteroptionen werden automatisch basierend auf den in Ihrer WP_Query enthaltenen Post-Typen generiert. WPFilters zeigt nur Filteroptionen an, die für die abgefragten Post-Typen relevant sind. Wenn Ihre WP_Query keine Post-Typen enthält, die über die Taxonomie oder benutzerdefinierte Feldinformationen verfügen, aus denen Ihre Filter erstellt werden, werden diese Filteroptionen nicht angezeigt.

Wenn Ihr Filterelement beispielsweise so konfiguriert ist, dass Kategorien angezeigt werden, Ihre WP_Query jedoch nur den Post-Typ „Seite“ enthält, wird der Kategorie-Filter leer angezeigt, da Seiten normalerweise keine Kategoriezuweisungen haben. Wenn Sie einen benutzerdefinierten Taxonomie-Filter für WooCommerce-Produkte haben, Ihre Abfrage jedoch nur normale Beiträge enthält, werden keine Filteroptionen angezeigt, da Beiträge keine Produkt-Taxonomien verwenden.

URL-Parameter in der Paginierung beibehalten

WPFilters fügt Filterauswahlen als Query-Parameter zur URL hinzu. Wenn Benutzer zwischen den Seiten navigieren, müssen diese Parameter beibehalten werden, damit die Filter aktiv bleiben. Sie können die Funktion paginate_links() mit dem Parameter 'add_args' erweitern, um Filterparameter in den Paginierungslinks beizubehalten.

Übergeben Sie nur sichere, bekannte Parameter-Schlüssel, um Sicherheitsprobleme zu vermeiden. Kopieren Sie nicht blind alle Werte aus $_GET ohne Validierung.

Block- und Full-Site-Editing-Themes

Wenn Sie ein Block-Theme oder ein Full Site Editing (FSE)-Theme verwenden, das keine traditionellen header.php- und footer.php-Dateien hat, funktioniert dieses Vorlagenbeispiel nicht wie geschrieben. Für Block-Themes müssen Sie entweder ein Child-Theme mit klassischem Vorlagen-Support erstellen oder die entsprechenden HTML-Vorlagenteile und Blockmuster des Block-Themes verwenden.

Installation und Einrichtung

Dateispeicherort

Speichern Sie die Vorlagendatei im Verzeichnis Ihres aktiven Themes. Für ein Eltern-Theme legen Sie sie unter: wp-content/themes/your-theme/wp-filters-query.php ab.

Für bessere Wartbarkeit verwenden Sie ein Child-Theme: wp-content/themes/your-child-theme/wp-filters-query.php

Vorlage einer Seite zuweisen

Gehen Sie in Ihrem WordPress-Adminbereich zu Seiten → Neu hinzufügen
Finden Sie in der Seitenleiste die Option Vorlage
Wählen Sie „WP Filters — benutzerdefinierte Abfrage“
Veröffentlichen oder aktualisieren Sie die Seite

Besuchen Sie die Seite im Frontend und testen Sie Ihre Filter und Paginierung.

Zusammenfassung

Die Verwendung von WPFilters mit einer benutzerdefinierten WP_Query gibt Ihnen die volle Kontrolle darüber, wie Inhalte angezeigt und gefiltert werden. Durch die richtige Kennzeichnung Ihrer Abfrage und die Strukturierung Ihrer Vorlage können Sie leistungsstarke, dynamische Filtererlebnisse aufbauen, die über die Standard-WordPress-Archive hinausgehen.