• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

「プラグイン API/アクションフック一覧/pre get posts」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(Page Requests)
26行目: 26行目:
  
 
<div id="Page Requests">
 
<div id="Page Requests">
===Page Requests===
+
===ページリクエスト===
 
</div>
 
</div>
 
<tt>pre_get_posts</tt> は 単一のページのリクエスト(ページテンプレート)に用いるべきではありません。なぜなら 'is_page'、'is_singular'、 'pagename'、および他のプロパティは(パーマリンク設定を使っているかどうかによる)、既に parse_query() メソッドによってセットされているからです。 参照:クエリの概要[[Query_Overview|Query Overview]]。これらの設定に精通していてそれらを調整しない限り、ページテンプレート [[Page_Templates|page template]] 自体に新しい [[Class_Reference/WP_Query|new WP_Query]]  を使用して、1つのページ要求のためのメイン·クエリを変更することを提案しています。
 
<tt>pre_get_posts</tt> は 単一のページのリクエスト(ページテンプレート)に用いるべきではありません。なぜなら 'is_page'、'is_singular'、 'pagename'、および他のプロパティは(パーマリンク設定を使っているかどうかによる)、既に parse_query() メソッドによってセットされているからです。 参照:クエリの概要[[Query_Overview|Query Overview]]。これらの設定に精通していてそれらを調整しない限り、ページテンプレート [[Page_Templates|page template]] 自体に新しい [[Class_Reference/WP_Query|new WP_Query]]  を使用して、1つのページ要求のためのメイン·クエリを変更することを提案しています。

2015年7月1日 (水) 21:48時点における版

このページ「プラグイン API/アクションフック一覧/pre get posts」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

このフックはクエリー変数オブジェクトの生成後、実際にクエリーが実行される前に呼び出されます。


pre_get_posts アクションは、開発者は $query オブジェクトへの参照によるアクセス手段を提供します($query への変更はオリジナルのオブジェクトに直接反映されます - 返り値は必要ありません)。

書き方

<?php add_action( 'pre_get_posts', 'function_name' ); ?>

"function_name" は呼び出される関数名です。

注意

変数は参照で渡されます

関数に渡される $query オブジェクトは 参照により渡されます。グローバル変数を宣言したり値を返す必要はありません。関数内から行われた変更はオリジナルに直ちに反映されます。

ページリクエスト

pre_get_posts は 単一のページのリクエスト(ページテンプレート)に用いるべきではありません。なぜなら 'is_page'、'is_singular'、 'pagename'、および他のプロパティは(パーマリンク設定を使っているかどうかによる)、既に parse_query() メソッドによってセットされているからです。 参照:クエリの概要Query Overview。これらの設定に精通していてそれらを調整しない限り、ページテンプレート page template 自体に新しい new WP_Query を使用して、1つのページ要求のためのメイン·クエリを変更することを提案しています。

対象となるクエリーの識別

pre_get_postsを使用する際は、変更しようとしているクエリーに注意してください。便利なツールのひとつはis_main_queryです。変更するクエリーをメインクエリーのみに制限するのに使えます。Use it in combination with other conditional tags to only alter the main query on the pages you want.

管理画面での使われ方に注意

このフィルターは管理画面のクエリーにも影響を与えます。変更が投稿編集画面に影響を与えていないか確認してください。例えば、`! is_admin()` をチェックしないと、`is_main_query()` and `is_post_type_archive('custom')` だけでは `edit.php?post_type=custom` 用のクエリーも変更されてしまいます。

条件分岐関数に注意

pre_get_postsWP_Queryがセットアップされる前に実行されます。WP_Queryに依存するいくつかのテンプレートタグや条件分岐関数は動作しません。例えば、is_front_page()は動作しませんが、is_home()は動作します。このような場合は、pre_get_postsフックに渡されるクエリー変数を直接参照する必要があるでしょう($queryのサンプルはこのページにあります)。

オフセットとページ送り

WordPressのクエリーでoffset引数を使うと、ページ送りに不具合を引き起こすことがあります。ページ送りを保護しつつオフセットを使用するには、手動でページ送りを処理する必要がありますので、ご注意ください。詳細は、CodexのMaking_Custom_Queries_using_Offset_and_Pagination(英語)をお読みください。

使用例

メインページから特定のカテゴリーを除外する

これは特定のカテゴリーに属する投稿を除外して表示する方法です。例えば、ブログの'ホーム'に表示させたくない投稿のカテゴリーが2つ(未分類 '1'もうひとつ '1347') とあるとすると、プラグイン内(訳注:テーマのfunctions.phpでもいい?)で以下のようにします:

function exclude_category( $query ) {
    if ( $query->is_home() && $query->is_main_query() ) {
        $query->set( 'cat', '-1,-1347' );
    }
}
add_action( 'pre_get_posts', 'exclude_category' );

ホームページ上に唯一のカテゴリを表示

Place this code in functions.php to cause the home page to display posts only from one category.

function my_home_category( $query ) {
    if ( $query->is_home() && $query->is_main_query() ) {
        $query->set( 'cat', '123' );
    }
}
add_action( 'pre_get_posts', 'my_home_category' );

Change "123" to the category ID you wish to display.

ホームページからIDにより単一の投稿を除外

Excludes an array of single post I.D's from your home page

function exclude_single_posts_home($query) {
  if ($query->is_home() && $query->is_main_query()) {
    $query->set('post__not_in', array(7,11));
  }
}

add_action('pre_get_posts', 'exclude_single_posts_home');


検索結果から固定ページを除外

読者がブログを検索する時、その目的は恐らくページではなく投稿の中身でしょう。ですから、検索結果からページを除外することが好ましいことがあります。そこで投稿からの検索結果に限定するための、アクションフックを作ることもができます。

以下の例がその方法です:

function search_filter($query) {
  if ( !is_admin() && $query->is_main_query() ) {
    if ($query->is_search) {
      $query->set('post_type', 'post');
    }
  }
}

add_action('pre_get_posts','search_filter');

検索結果にカスタム投稿タイプを含める

function search_filter($query) {
  if ( !is_admin() && $query->is_main_query() ) {
    if ($query->is_search) {
      $query->set('post_type', array( 'post', 'movie' ) );
    }
  }
}

add_action('pre_get_posts','search_filter');

投稿タイプを指定して表示件数を変更

WordPressは、ループページに表示される投稿の数をコントロールするための、1つのグローバル設定を含みます (管理画面:「設定」→「表示設定」→「1ページに表示する最大投稿数」で設定した値です)。この数値である posts_per_page の設定を、ケース・バイ・ケースで変更または優先させる為のアクションフックを作成することができます。とりわけこれはクエリが実行される前に実行されます。つまりパフォーマンスに与える影響がないのです!

以下の例は、特定の投稿体部のアーカイブに対して、1ページに表示される投稿数 (posts_per_page) を変更させる手法を示します。

function hwl_home_pagesize( $query ) {
    if ( is_admin() || ! $query->is_main_query() )
        return;

    if ( is_home() ) {
        // Display only 1 post for the original blog archive
        $query->set( 'posts_per_page', 1 );
        return;
    }

    if ( is_post_type_archive( 'movie' ) ) {
        // Display 50 posts for a custom post type called 'movie'
        $query->set( 'posts_per_page', 50 );
        return;
    }
}
add_action( 'pre_get_posts', 'hwl_home_pagesize', 1 );

フィードのページ毎の投稿数を変更する

You can override the number of posts to show up in a specific feed using the posts_per_rss setting.

function bdn_feed_set_posts_per_rss( $query ) {

	if( !$query->is_main_query() || !is_feed() )
		return;
	
	//set conditional

	$query->set( 'posts_per_rss', 50 );

}


WP_Queryオブジェクトの例

参考として、このフックで吐き出されたWP_Query オブジェクト ($query) の一例を挙げます。更なる詳細は、 Class_Reference/WP_Query を参照してください。

WP_Query Object
(
    [query_vars] => Array
        (
            [page] => 
            [pagename] => blog
            [error] => 
            [m] => 0
            [p] => 0
            [post_parent] => 
            [post_type] =>
            [subpost] => 
            [subpost_id] => 
            [attachment] => 
            [attachment_id] => 0
            [name] => 
            [static] => 
            [page_id] => 0
            [second] => 
            [minute] => 
            [hour] => 
            [day] => 0
            [monthnum] => 0
            [year] => 0
            [w] => 0
            [category_name] => 
            [tag] => 
            [cat] => 
            [tag_id] => 
            [author_name] => 
            [feed] => 
            [tb] => 
            [paged] => 0
            [comments_popup] => 
            [meta_key] => 
            [meta_value] => 
            [preview] => 
            [s] => 
            [sentence] => 
            [fields] => 
            [category__in] => Array
                (
                )

            [category__not_in] => Array
                (
                )

            [category__and] => Array
                (
                )

            [post__in] => Array
                (
                )

            [post__not_in] => Array
                (
                )

            [tag__in] => Array
                (
                )

            [tag__not_in] => Array
                (
                )

            [tag__and] => Array
                (
                )

            [tag_slug__in] => Array
                (
                )

            [tag_slug__and] => Array
                (
                )

        )

    [tax_query] => 
    [meta_query] => 
    [post_count] => 0
    [current_post] => -1
    [in_the_loop] => 
    [comment_count] => 0
    [current_comment] => -1
    [found_posts] => 0
    [max_num_pages] => 0
    [max_num_comment_pages] => 0
    [is_single] => 
    [is_preview] => 
    [is_page] => 
    [is_archive] => 
    [is_date] => 
    [is_year] => 
    [is_month] => 
    [is_day] => 
    [is_time] => 
    [is_author] => 
    [is_category] => 
    [is_tag] => 
    [is_tax] => 
    [is_search] => 
    [is_feed] => 
    [is_comment_feed] => 
    [is_trackback] => 
    [is_home] => 1
    [is_404] => 
    [is_comments_popup] => 
    [is_paged] => 
    [is_admin] => 
    [is_attachment] => 
    [is_singular] => 
    [is_robots] => 
    [is_posts_page] => 1
    [is_post_type_archive] => 
    [query_vars_hash] => 41032f87127fba65fb6743b1e97d8662
    [query_vars_changed] => 
    [thumbnails_cached] => 
    [query] => Array
        (
            [page] => 
            [pagename] => blog
        )

    [queried_object] => stdClass Object
        (
            [ID] => 16
            [post_author] => 1
            [post_date] => 2012-01-31 17:23:57
            [post_date_gmt] => 2012-01-31 17:23:57
            [post_content] => 
            [post_title] => Blog
            [post_excerpt] => 
            [post_status] => publish
            [comment_status] => open
            [ping_status] => open
            [post_password] => 
            [post_name] => blog
            [to_ping] => 
            [pinged] => 
            [post_modified] => 2012-01-31 17:23:57
            [post_modified_gmt] => 2012-01-31 17:23:57
            [post_content_filtered] => 
            [post_parent] => 0
            [guid] => 

記事

コード・ドキュメンテーション

  • クラス: WP_Query - WP_Query クラスの詳細な全容
  • クラス: WP_Comment_Query - コメント関連のクエリのためのクラス
  • クラス: WP_User_Query - ユーザー関連のクエリのためのクラス
  • オブジェクト: $wpdb - $wpdb オブジェクトの使い方全容
  • 関数: set_query_var()
  • 関数: get_query_var()
  • 関数: query_posts() - 追加のカスタムクエリを作成
  • 関数: get_post() - 項目の ID を取得しデータベース内にあるその投稿のレコードを返す
  • 関数: get_posts() - 投稿の配列を返すことに特化した関数
  • 関数: get_pages() - ページの配列を返すことに特化した関数
  • 関数: have posts() - クエリが投稿を返すか否かを判断する条件関数
  • 関数: the_post() - クエリ後に自動的にループを設定する
  • 関数: rewind_posts() - 現状のループをリセットする
  • 関数: setup_postdata() - ループ内で個別の結果を得るためのクエリデータを設定する
  • 関数: wp_reset_postdata() - 直前のクエリを復元する (通常はループ内の別のループの後に用いられる)
  • 関数: wp_reset_query()
  • 関数: is_main_query() - 変更されるクエリがメインのクエリであることを確認する
  • アクションフック: pre_get_posts - WordPressクエリが実行される前に変更する
  • アクションフック: the_post - post クエリの後で post オブジェクトを変更する
  • フィルターフック: found_posts - WP_Query オブジェクトの found_posts 値を変更する


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Plugin_API/Action_Reference/pre_get_posts最新版との差分