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

タナビーの高梨です。

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

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

今回はウィジェットの人気記事の<div>などに任意のクラスを追加できるフィルターフック
👉get_additional_widget_entry_cards_classes
です。

フックの概要

フックの発火条件

ダッシュボード＞外観＞ウィジェットで下記が設定されていればそれぞれで必ず発火します。

・[c]人気記事

・[c]新着記事

・[c]ナビカード

使いどころ

このフックを利用すると、ウィジェット内の以下のタグにクラスを追加できます。

このフックで追加されるクラスは3種類のウィジェットに共通で付与されます。
したがって、「人気記事だけ」「新着記事だけ」などの個別装飾には使えません。

活用できるケースは、例えば以下のように共通クラスを一括付与したいときです。

・すべてのカードリストに共通のCSSを当てたい

・一括でJSで拾いたい

個別にスタイルを変えたい場合はすでについている固有クラスをそのまま使うのが正解です。

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

function get_additional_widget_entry_cards_classes($atts){
    ///  省略  ///
    return apply_filters('get_additional_widget_entry_cards_classes', $classes);
}

function generate_popular_entries_tag($atts){
    ///  省略  ///
    $cards_classes = get_additional_widget_entry_cards_classes($atts);
    ///  省略  ///
}
function generate_widget_entries_tag($atts){
    ///  省略  ///
    $cards_classes = get_additional_widget_entry_cards_classes($atts);
    ///  省略  ///
}

function get_navi_card_wrap_tag($atts){
    ///  省略  ///
    $navi_card_class = get_additional_widget_entry_cards_classes($atts);
    ///  省略  ///
}

引数

$classes：（string）クラス名のリスト。

※body_class_additionalではarrayですが、こちらはstringです。

カスタマイズコード例

以下は無条件に各タグに’additionalClass’というクラスを追加する例です。

function customize_get_additional_widget_entry_cards_classes( $classes ) {

    $classes .= ' additionalClass';

    return $classes;

}
add_filter( 'get_additional_widget_entry_cards_classes', 'customize_get_additional_widget_entry_cards_classes' );

注意点

・個別制御は不可
フィルターに $atts やウィジェット種別が渡ってこないため、人気記事だけ／新着だけ といった分岐はこのフック単体ではできません。

・戻り値は文字列
array ではなく string を返す仕様です。
追加時は 先頭に半角スペース を付けて結合しないと、クラス名が連結されて壊れます。

・共通付与専用と割り切る
このフックの現実的な用途は“3種類まとめて同じクラスを足す”こと。
細かな出し分けが必要なら、このフックではなくCSSセレクタや別フック（あるいはテンプレートの上書き）の検討が必要。

まとめ

・get_additional_widget_entry_cards_classes は、人気・新着・ナビカードのカードリストに共通クラスを一括付与するためのフィルター。

・個別装飾には使えない（フィルターに種別情報が来ない）ため、個別の見た目調整は既存の固有クラスで対応する。

・返り値は 文字列。半角スペースを付けてクラスを結合するのを忘れない。

共通クラスで一括調整・計測・JSフックを仕込みたいときにだけ使う、という割り切りがベストです。