cocoonフック調査～widget_related_entries_argsの使い方と活用例

タナビーの高梨です。

WordPressのテーマ「Cocoon」には、テーマ改変なしでデザインや動作を拡張できる豊富なアクション・フィルターフックが用意されています。

分かる範囲で内容を調査したのでブログにまとめていこうと思います。

今回は関連記事ウィジェット表示時に取得クエリに渡される$argsを変更できるフィルターフック
👉widget_related_entries_args
です

フックの概要

発火条件

関連記事ウィジェットの表示タイミングで無条件に発火します

使いどころ

関連記事一覧を取得する際の取得方法を制御することができます。

関連記事一覧は$query = new WP_Query( $args );で取得されます。

この$argを制御することができます。

$argの初期値は設定などの条件によって異なりますが、例えばこのようになっています。

array(10) {
    ["posts_per_page"]=> string(1) "5"
    ["no_found_rows"]=> bool(true)
    ["action"]=> NULL
    ["offset"]=> int(0)
    ["ignore_sticky_posts"]=> bool(true)
    ["order"]=> string(4) "DESC"
    ["orderby"]=> string(4)"rand"
    ["post__not_in"]=> array(1) { [0]=> int(108) }
    ["tax_query"]=> array(2) {
        [0]=> array(1) {
            [0]=> array(5) {
                ["taxonomy"]=> string(8) "category"
                ["terms"]=> array(1) {[0]=> int(4) }
                ["include_children"]=> int(0)
                ["field"]=> string(7) "term_id"
                ["operator"]=> string(2) "IN"
            }
        }
        ["relation"]=> string(3) "AND"
    }
    ["post_type"]=> array(1) { [0]=> string(4) "post" }
}

これらに対して、削除、追加、変更など自由に編集することができます。

活用例：

・取得の順番を変更したい
・ページによって取得条件を変更したい

apply_filters呼び出し元のソースコード

$args = apply_filters('widget_related_entries_args', $args);

引数

$args：（array）WP_Queryに渡す配列

カスタマイズコード例

取得する際のソート順を昇順にする例です。

function customize_widget_related_entries_args ( $args ) {

    $args['order'] = 'ASC';

    return $args;

}
add_filter('widget_related_entries_args', 'customize_widget_related_entries_args' );

widget_entries_argsが優先されます。

注意点

・同様のフィルターwidget_entries_argsが存在し、widget_entries_args方が優先されます
つまり、両方を使用した場合はwidget_entries_argsの内容で上書きされる点に注意が必要です

・$argsの内容が不正になると関連記事が意図せず取得できなくなります

まとめ

・widget_related_entries_args は、関連記事ウィジェットの取得条件を柔軟に変更できるフィルターフックです。

並び順・件数・カテゴリ・投稿タイプなどを自由に変更できるため、サイト構成やデザインに合わせた関連記事表示を実現できます。

同様の仕組みを持つwidget_entries_argsやwidget_new_entries_argsもチェックしてみてください。