カスタム WP_Query

WPFiltersは、標準のアーカイブページ、カテゴリページ、ブログのホームページでWordPressのメインクエリと連携するように設計されています。しかし、独自のWP_Queryを使用してカスタムページテンプレートを作成すると、フィルタリングしたい投稿は、ページ自体を表すWordPressのメインクエリからではなく、カスタムクエリから取得されます。

WPFiltersをカスタムWP_Queryと連携させるには、クエリに特別なフラグを付け、特定のHTMLマークアップを使用する必要があります。これにより、WPFiltersはカスタムクエリにフィルタリングロジックを適用し、ユーザーがフィルタと対話したときにフロントエンドのJavaScriptがページの正しい部分を更新できるようになります。

必須設定

クエリフラグ

WP_Query引数に「wpfilters」=> true を追加する必要があります。これにより、WPFiltersがフィルタリングロジックを適用し、URLからフィルタパラメータを読み取り、選択されたフィルタに一致する投稿IDを計算し、それに応じてクエリを更新するようにクエリがマークされます。

このフラグがない場合、WPFiltersはクエリを通常のフィルタリングされていないクエリとして扱い、完全に無視します。

注意: クエリ引数に「suppress_filters」=> true を使用しないでください。WPFiltersは、WordPressがget_posts()呼び出しを処理するのと同じように、抑制されたクエリを処理し、それらを完全にスキップします。

WPFiltersが正しく機能するには、クエリでフィルタの実行を許可する必要があります。

必須HTMLマークアップ

WPFiltersは、AJAXフィルタリング中にフロントエンドのJavaScriptが正しいページ要素を見つけて更新できるように、特定のCSSクラスとHTML構造に依存しています。

結果ラッパー: 投稿ループの出力は、wpfilters-resultsクラスを持つ要素でラップする必要があります。フィルタリングされたAJAXリクエストの後、WPFiltersはこのラッパー内のコンテンツをフィルタリングされた結果で置き換えます。

ページネーションラッパー: ページネーションリンクは、wpfilters-paginationクラスを持つ要素でラップする必要があります。これにより、JavaScriptはフィルタリング後にページネーションを見つけて更新できます。

これらのラッパークラスがない場合、AJAX更新が失敗したり、間違ったページ要素をターゲットにしたりして、フィルタインターフェイスが誤動作する可能性があります。

テンプレート例

次の例は、WPFiltersと連携する完全なカスタムページテンプレートを示しています。このテンプレートは、Twenty Twentyやカスタム子テーマのような、get_header()とget_footer()を使用するクラシックWordPressテーマ用に設計されています。

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

テンプレートの仕組み

wpfiltersクエリフラグ

WP_Queryの「wpfilters」=> true 引数は、このクエリをWPFilters処理用にマークします。このフラグが存在する場合、WPFiltersはURLからフィルタパラメータを読み取り、選択されたフィルタに一致する投稿IDを計算し、（AJAXリクエスト中に）一致する投稿のみを表示するようにpost__inを設定することにより、フィルタリングロジックを適用します。

結果ラッパー

<div class=”wpfilters-results”> 要素は、投稿ループ出力全体をラップします。このラッパーは、フロントエンドのJavaScriptがこのクラスを探して、フィルタリングされた結果を挿入する場所を見つけるため、非常に重要です。フィルタリングされたAJAXリクエストが完了すると、WPFiltersはこのラッパー内のコンテンツを新しいフィルタリングされた投稿で置き換えます。

一貫性を保つため、“投稿が見つかりませんでした”メッセージも wpfilters-results クラスを持つ要素にラップされます。これにより、投稿が見つかったかどうかにかかわらず、安定したターゲット要素が存在することが保証されます。

ページネーションラッパー

nav class=”wpfilters-pagination”> 要素は paginate_links() の出力をラップします。このラッパーにより、JavaScript はフィルタリング後にページネーションリンクを見つけて更新できます。このラッパーがないと、フィルタが変更されたときにページネーションが正しく更新されない可能性があります。

ページネーション変数処理

ページテンプレートはページネーションに page クエリ変数を使用しますが、アーカイブは paged を使用します。テンプレートコードは、どちらかの変数の最大値を取得することで両方を処理し、WordPress がどちらの変数を設定したかに関係なく、ページネーションが正しく機能することを保証します。

重要な考慮事項

クエリとフィルターソースを一致させる

フィルターオプションは、WP_Query に含まれる投稿タイプに基づいて自動的に生成されます。WPFilters は、クエリしている投稿タイプに関連するフィルターオプションのみを表示します。WP_Query に、フィルターが構築されているタクソノミーまたはカスタムフィールドデータを持つ投稿タイプが含まれていない場合、それらのフィルターオプションは表示されません。

たとえば、フィルター要素がカテゴリを表示するように構成されていても、WP_Query に page 投稿タイプしか含まれていない場合、ページは通常カテゴリ割り当てを持たないため、カテゴリフィルターは空で表示されます。同様に、WooCommerce 製品のカスタムタクソノミーフィルターがあるが、クエリに通常の投稿しか含まれていない場合、投稿は製品タクソノミーを使用しないため、フィルターオプションは表示されません。

ページネーションで URL パラメータを保持する

WPFilters は、フィルターの選択をクエリパラメータとして URL に追加します。ユーザーがページ間を移動するときに、フィルターがアクティブなままであるように、これらのパラメータを保持する必要があります。フィルターパラメータをページネーションリンクに保持するために、paginate_links() 関数を 'add_args' パラメータで拡張できます。

セキュリティ上の問題が発生しないように、安全で既知のパラメータキーのみを渡してください。検証なしに $_GET からすべての値を無差別にコピーしないでください。

ブロックテーマとフルサイト編集テーマ

従来の header.php および footer.php ファイルを持たないブロックテーマまたはフルサイト編集 (FSE) テーマを使用している場合、このテンプレートの例は記述どおりには機能しません。ブロックテーマの場合、クラシックテンプレートサポートを備えた子テーマを作成するか、ブロックテーマの同等の HTML テンプレートパーツとブロックパターンを使用する必要があります。

インストールとセットアップ

ファイル場所

テンプレートファイルをアクティブなテーマディレクトリに保存します。親テーマの場合は、次のように配置します: wp-content/themes/your-theme/wp-filters-query.php

保守性を高めるために、子テーマを使用してください: wp-content/themes/your-child-theme/wp-filters-query.php

ページにテンプレートを割り当てる

WordPress 管理画面で ページ → 追加 に移動します
サイドバーで、テンプレート オプションを見つけます
“WP Filters — カスタムクエリ” を選択します
ページを発行または更新します

フロントエンドでページにアクセスし、フィルターとページネーションをテストします。

概要

WPFilters をカスタム WP_Query と共に使用すると、コンテンツの表示方法とフィルタリング方法を完全に制御できます。クエリに適切にマークを付け、テンプレートを構造化することで、標準の WordPress アーカイブを超えた強力で動的なフィルタリングエクスペリエンスを構築できます。