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

タナビーの高梨です。

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

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

今回はFAQブロックがページ内にある場合に出力される構造化データ（JSON-LD）の内容を編集できる
cocoon_faq_entity
です。

フックの概要

フックの発火条件

ページ内にFAQブロックがあれば発火します。
ただし、こちらのページで解説しているcocoon_json_ld_faq_visibleのフィルターを通してfalse を返してFAQ構造化データの出力を抑制している場合は、このフックも呼び出されません。

使いどころ

このフックは、Cocoonが自動生成するFAQ構造化データの内容を追加・変更したい場合に活用できます。

例えば、

・管理画面上では入力していないけど、FAQに追加で質問と回答を含めたいとき
・FAQブロックに入力された内容をカスタムフィルターで編集したいとき

などに有効です。

構造化データの編集をプログラム側から柔軟に操作できるため、SEO向けに出力内容を精密にコントロールしたい場合に便利です。

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

$faq = apply_filters('cocoon_faq_entity', []);
  if (!empty($faq)) {
    $entity = [];

    foreach ($faq as $key => $value) {
      $entity[] = $value;
    }

    echo '<!-- '.THEME_NAME_CAMEL.' FAQ JSON-LD -->'.PHP_EOL;
    echo '<script type="application/ld+json">'.json_encode([
      '@context'   => 'https://schema.org',
      '@type'      => 'FAQPage',
      'mainEntity' => $entity
    ], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT).'</script>';
  }

cocoonのfunctions.php内でadd_filter(‘cocoon_faq_entry’)しており、その関数内でfaqの内容を展開しています。

追加したい場合はそこに割り込む形となります。

引数

$faq：（array）faqの内容。配列の各要素は @type: Question を基本とする形式。

カスタマイズコード例

以下は、元のFAQに1件の質問と回答を追加する例です。

function customize_cocoon_json_ld_faq_visible( $is_cocoon_json_ld_faq_visible ) {

    $faq[] = [
        '@type' => 'Question',
        'name' => '追加した質問です',
        'acceptedAnswer' => [
            '@type' => 'Answer',
            'text' => '追加した答えです',
        ]
    ];
    return $faq;

}
add_filter( 'cocoon_json_ld_faq_visible', 'customize_cocoon_json_ld_faq_visible', 10000 );

このコードにより、出力される構造化データは以下のようになります（一部抜粋）：

<script type="application/ld+json">{
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [

        ～～　元のFAQ内容　～～

        {
            "@type": "Question",
            "name": "追加した質問です",
            "acceptedAnswer": {
                "@type": "Answer",
                "text": "追加した答えです"
            }
        }
    ]
}</script>

注意点

・FAQブロックがページ内に存在しない場合は、そもそも構造化データが出力されないため、このフックも発火しません。

・cocoon_json_ld_faq_visible フィルターで構造化データ出力を false にした場合も、このフックは無効になります。

・JSON-LDの構造に沿った正しい形式で配列を追加するように注意しましょう。誤った構造で返すと、構造化データとして無効になります。

まとめ

cocoon_faq_entity は、Cocoonが出力するFAQの構造化データに対して、質問・回答の追加や内容変更を行うためのフィルターフックです。

FAQブロックに入力した内容以外も含めて構造化データに含めたい場合や、SEO対策としてより詳細なFAQデータを出力したい場合に活用できます。

テーマファイルを書き換えることなく、柔軟なカスタマイズができる便利なフックなので、必要に応じて使ってみてください。