同じ部品の見出しを場所ごとに変える:get_template_part の 3 つ目の引数 $args の使い方

機能追加
広告WordPress・PHP を学べる本

Amazonのアソシエイトとして、WordPress functions.phpは適格販売により収入を得ています。

あるサイトで、料金の固定ページや別の種類の記事の下ですでに使っていた予約・問い合わせの案内の枠を、コラムの記事の下にも出すことになりました。

コラムの記事でも同じ枠を出したいのですが、見出しとリード文は、コラムに合う文言にしたいと考えました。

部品をコピーして 2 つにすると、ボタンや連絡先を直すときに、両方を直すことになります。

そこで、WordPress 5.5 から使える get_template_part() の 3 つ目の引数 $args で、見出しとリード文だけを渡すことにしました。

この記事では、部品の名前を template-parts/contact-box、投稿タイプを my_column などの例の名前にしています。

get_template_part の 3 つの引数

get_template_part() は、テーマの中の部品のファイルを読み込む関数です。

WordPress 5.5 から、3 つ目の引数で、部品に値を渡せるようになりました。

引数 例 役目
1 つ目 $slug 'template-parts/contact-box' 部品のファイル(.php は付けない)。テーマのフォルダから見た場所
2 つ目 $name null 部品の別の形の名前。'column' を渡すと、先に contact-box-column.php を探す。null なら contact-box.php だけを読む
3 つ目 $args array( 'title' => '…' ) 部品に渡す値の配列(5.5 から)。部品の中では $args という名前で使える

3 つ目の引数だけを使いたいときも、2 つ目は飛ばせません。

別の形の部品は使わないので、2 つ目には null を渡します。

5.5 からは、部品のファイルが見つからなかったときに false を返すようにもなりました。

1. 部品の側:$args を受け取る

/wp-content/themes/(テーマのフォルダ)/template-parts/contact-box.php
<?php
// 予約・問い合わせの案内の枠
// 見出しとリード文は、呼ぶ側から $args で変えられる。渡されなければ既定の文言を出す。
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
$box_title = $args['title'] ?? 'ご予約・お問い合わせ';
$box_lead  = $args['lead'] ?? 'ご相談・ご予約は、お気軽にどうぞ。';
?>
<section class="contact-box">
    <h2 class="contact-box__title"><?php echo esc_html( $box_title ); ?></h2>
    <p class="contact-box__lead"><?php echo esc_html( $box_lead ); ?></p>
    <ul class="contact-box__buttons">
        <li><a class="button" href="<?php echo esc_url( home_url( '/contact' ) ); ?>">Web で予約する</a></li>
    </ul>
</section>
書き方 役目
$args 呼ぶ側が 3 つ目の引数で渡した配列。渡さなかったときは空の配列
$args['title'] ?? '既定の文言' title が渡されていればそれを、なければ既定の文言を使う。キーがなくても警告は出ない
esc_html() 渡された文言を、HTML として安全な形にして出す。部品の側で必ず通す
esc_url() リンクの URL を安全な形にして出す

部品の側で既定の文言を持っておくと、今まで引数なしで呼んでいた所は、何も変えなくて済みます。

2. 呼ぶ側:記事の下で見出しを変える

single.php(本文の下)
<?php
// 本文の下に、案内の枠を出す
if ( 'my_article' === get_post_type() ) :
    // 今までの記事:見出しとリード文は、部品の既定の文言のまま
    get_template_part( 'template-parts/contact-box' );
endif;
if ( 'my_column' === get_post_type() ) :
    // コラムの記事:見出しとリード文だけ変える
    get_template_part( 'template-parts/contact-box', null, array(
        'title' => 'コラムを読んで気になった方へ',
        'lead'  => 'コラムの内容についても、お気軽にご相談ください。',
    ) );
endif;
?>
書き方 役目
get_post_type() 表示している記事の投稿タイプ
get_template_part( 'template-parts/contact-box' ) 引数なし。部品の既定の見出しとリード文が出る(今までどおり)
null(2 つ目) 別の形の部品は使わない、という意味
array( 'title' => …, 'lead' => … ) コラムの記事のときだけ、見出しとリード文を渡す

ボタンや連絡先は、部品の中に書いてあります。

直すときは、部品のファイル 1 つを直せば、全部の場所に効きます。

3. 固定ページの側:本文の最後に足す

料金の固定ページでは、テンプレートを変えずに、the_content のフィルターで本文の最後に枠を足していました。

functions.php(またはテーマから読むファイル)
<?php
// 固定ページ(料金のページ)の本文の最後に、同じ枠を出す
function my_page_contact_box( $content ) {
    if ( ! is_page( 'price' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content;
    }
    ob_start();
    get_template_part( 'template-parts/contact-box', null, array(
        'title' => 'このプランで申し込む',
        'lead'  => 'メニューや料金のご相談も、お気軽にどうぞ。',
    ) );
    return $content . ob_get_clean();
}
add_filter( 'the_content', 'my_page_contact_box', 20 );
書き方 役目
is_page( 'price' ) スラッグが price の固定ページのときだけ
in_the_loop()・is_main_query() メインの本文のときだけ。サイドなどのほかの場所では足さない
ob_start()・ob_get_clean() get_template_part() はそのまま出力するので、いったん文字として受け取る
$content . ob_get_clean() 本文の後ろに枠をつなげて返す

同じ部品を、テンプレートからも、フィルターからも呼べます。

5.5 より前の set_query_var との違い

5.5 より前は、set_query_var() で値を設定してから部品を呼ぶ書き方がよく使われていました。

5.5 より前の書き方(比べるため)
<?php
// 5.5 より前の書き方(呼ぶ側)
set_query_var( 'box_title', 'コラムを読んで気になった方へ' );
get_template_part( 'template-parts/contact-box' );

// 5.5 より前の書き方(部品の側)
$box_title = get_query_var( 'box_title' );
if ( '' === $box_title ) {
    $box_title = 'ご予約・お問い合わせ';
}
こと $args(5.5 から)/ set_query_var()(5.5 より前)
渡し方 $args:get_template_part() の 3 つ目の引数
set_query_var():呼ぶ前に set_query_var() で設定する
部品の中での受け取り方 $args:$args['title']
set_query_var():get_query_var( 'box_title' )(同じ名前の変数 $box_title としても見える)
値が残る範囲 $args:その 1 回の呼び出しの中だけ
set_query_var():メインのクエリに残り、あとで呼ぶ部品にも見える
名前のぶつかり $args:気にしなくてよい
set_query_var():クエリの変数(page・name など)と同じ名前にすると、ほかの処理に影響することがある
使える WordPress $args:5.5 から
set_query_var():古いバージョンでも使える

今の WordPress なら、渡した値がその場だけで終わる $args のほうが、ほかへの影響を考えずに済みます。

?? と ! empty() の違い

既定の文言に切り替える書き方は、2 つあります。

空の文字('')を渡したときに、結果が変わります。

渡したもの 結果(?? の形 / ! empty() の形)
渡さない ??:既定の文言
! empty():既定の文言
'新しい見出し' ??:新しい見出し
! empty():新しい見出し
''(空) ??:空のまま(見出しが空になる)
! empty():既定の文言

?? の形は $args['title'] ?? '既定の文言'、! empty() の形は ! empty( $args['title'] ) ? $args['title'] : '既定の文言' です。

このサイトの部品は、空のときも既定の文言になる ! empty() の形で書いています。

空のときも既定の文言にする書き方
<?php
// 空の文字が渡されたときも、既定の文言にしたいとき
$box_title = ! empty( $args['title'] ) ? $args['title'] : 'ご予約・お問い合わせ';

確認した結果

このサイトの作業環境(本番から複製したもの・WordPress 7.1.3・PHP 8.3)で確認しました。

ページで見た

それぞれのページを、URL に ?nc=(乱数)を付けて、キャッシュを通さずに開きました。

ページ 結果
コラムの記事 200。本文の下・カテゴリーの上に枠が 1 つ出た。見出しは「コラムを読んで気になった方へ」、リード文もコラム用の文言に変わった
別の種類の記事(引数なしで呼んでいる所) 200。枠が 1 つ出た。見出しとリード文は、部品の既定の文言のまま
料金の固定ページ(フィルターで足している所) 200。枠が 1 つ出た。見出しとリード文は、そのページ用の文言のまま(今までどおり)

どのページにも、PHP の Fatal error や Warning は出ていませんでした。

値の渡り方

検証用スクリプトで作業環境の WordPress を読み込み、小さな部品のファイルを、get_template_part() が中で使う load_template() で読み込みました。

試したこと 結果
引数なし $args は空の配列。既定の文言が出た
array( 'title' => '新しい見出し' ) 新しい見出しが出た
array( 'title' => '' ) ?? は空、! empty() は既定の文言
$args で渡したあと、引数なしでもう一度呼ぶ 既定の文言に戻った(値は残らない)
set_query_var() で設定してから呼ぶ 部品の中で、同じ名前の変数として見えた
そのあと、何もせずにもう一度呼ぶ set_query_var() の値が、まだ見えた(残っている)
ない部品を get_template_part() で呼ぶ false が返った

検証用スクリプトは、DB には何も書いていません。

気をつけること

5.5 より前の WordPress では、3 つ目の引数は使えません(渡しても部品には届きません)。

  • 見出しに HTML(太字など)を含めたいときは、esc_html() では文字として出てしまいます。そのときは wp_kses_post() などに変えます(このサイトでは文言だけなので、試していません)
  • 部品の中で、id 属性を決まった値で書いていると、同じページで 2 回使ったときに id が重なります。このサイトでは 1 ページに 1 つだけなので、そのままにしています
  • 子テーマを使っているときは、get_template_part() は子テーマの部品を先に探します

まとめ

テーマの中に set_query_var() で部品へ値を渡している所が残っていれば、$args で渡す形に書き換えます。部品をコピーして 2 つにしている所も、1 つにまとめて、違う文言だけを $args で渡します。

参考

SiteBeacon(サイトビーコン)

サイトが止まったら、すぐに気づける。

ホームページを 5 分ごとにチェックして、止まったとき・エラーが出たとき・SSL やドメインの期限が近いときに、メールでお知らせします。2 サイトまでは、ずっと無料で使えます。

SiteBeacon を見る サイトを直す相談をする

監視で気づいたあとの直す作業も、同じ担当がお受けします。