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

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

プラグイン API/アクションフック一覧/pre get posts

提供: WordPress Codex 日本語版
< プラグイン API‎ | アクションフック一覧
2013年7月22日 (月) 23:22時点におけるDjkaz (トーク | 投稿記録)による版 (英語で残っていた部分を和訳完了。)

移動先: 案内、 検索

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


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

書き方

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

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

注意

変数は参照で渡されます

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

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

pre_get_postsを使用する際は、変更しようとしているクエリーに注意してください。便利なツールのひとつはis_main_queryです。変更するクエリーをメインクエリーのみに制限するのに使えます。

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

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

条件分岐関数に注意

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

オフセットとページ送り

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

使用例

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

これは特定のカテゴリーに属する投稿を除外して表示する方法です。例えば、ブログの'ホーム'に表示させたくない投稿のカテゴリーが２つ（未分類 '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' );

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

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

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

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 );

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] =>
このページ「プラグイン API/アクションフック一覧/pre get posts」はまだ書きかけで、情報が不足しています。続きを書いて WordPress を手助けしましょう.


最新英語版： WordPress Codex » pre_get_posts （最新版との差分）

「http://wpdocs.osdn.jp/wiki/index.php?title=プラグイン_API/アクションフック一覧/pre_get_posts&oldid=5650」から取得