WordPressで作ったページテンプレートがwp-adminのドロップダウンに出てこない場合、まず疑うべきは「子テーマが有効化されているか」です。テンプレートファイルの書き方が間違っているのではなく、親テーマの方がアクティブになっているだけ、というケースが意外とあります。今回はこれに気づくまでしばらく原因不明で詰まりました。
背景
TakeCraftブログのトップページを、wp-adminのエディタではなく「フルカスタムテンプレート」(構造が固定されたHTMLをテンプレートファイルに直接書く方式)で作る作業をしていました。Laravelなどのフレームワークでビューファイルを作る感覚に近いだろうと想像はしていたのですが、実際に手を動かしてみると、WordPress独自の2段階の仕組みがあることに気づいたんですよね。
ページテンプレートの仕組みは2段階
WordPressのページテンプレートは、次の2つの設定が組み合わさって動きます。
1. テンプレートファイル自体の登録: テーマフォルダ内の.phpファイルの先頭に、次のようなコメントを書く
<?php
/**
* Template Name: フルカスタム - トップ（ブランドサイト風）
*/ファイル名は何でも構いません。このTemplate Nameコメントの有無だけで、WordPressがそのファイルを「テンプレートの選択肢」として自動的に検出します。wp-admin上で何か登録する操作は不要です。
2. どのページにそのテンプレートを使うか: ページ側に_wp_page_templateという別の設定があり、これが実際に表示時に使われるテンプレートを決めます。固定ページ編集画面の右サイドバー「ページ属性」→「テンプレート」のドロップダウンで選ぶか、コマンドでも設定できます。
wp post update <ページID> --page_template=page-top.phpLaravelで言えば、1が「ビューファイルをresources/viewsに置く」作業、2が「コントローラーでview('top')のように呼び出す」作業に近い感覚です。この対応関係が分かると、WordPressのテンプレートの仕組みがすっと理解できました。
テンプレートがドロップダウンに出てこないときの確認
Template Nameコメントを書いたはずのファイルが、なぜかページ編集画面のドロップダウンに出てこなくて。まず以下のコマンドで、WordPress自身がテンプレートをどう認識しているかを確認しました。
wp eval "print_r(wp_get_theme()->get_page_templates());"
wp theme listget_page_templates()が空配列を返していたので、テンプレートファイルの書き方そのものよりも、アクティブテーマの方を疑うべきだと判断しました。wp theme listで確認すると、子テーマ(cocoon-child-master)を使っているつもりが、親テーマ(cocoon-master)の方がアクティブになっていました。
wp theme activate cocoon-child-masterこれで子テーマが有効化され、ドロップダウンにテンプレートが表示されるようになりました。テンプレートファイルの書き方自体は最初から合っていて、原因はテーマの有効化忘れというシンプルなものでした(笑)。
the_content()を使わずにLPを作った理由
今回のトップページ・アプリ一覧・LPページのようなフルカスタムページでは、wp-adminのGutenbergエディタで本文(the_content())を書く方式は採用せず、テンプレートファイルに直接HTMLを書き込む方式にしました。
理由は、デザインがすでに固まっている移植作業だったことです。Gutenbergのブロックエディタで同じレイアウトを再現するより、HTMLを直接書く方が速く、構造も崩れにくいと判断しました。また、コードとしてgitで管理できるため、変更履歴も残ります。逆に、通常のブログ記事のような「本文がどんどん増える」ページでは、この方式は向いていないと思います。
まとめ
WordPressのページテンプレートは「テンプレートファイルの登録(Template Nameコメント)」と「ページへの適用(_wp_page_template)」という2段階の仕組みで動いています。Laravelなどのフレームワーク経験がある人ほど、ビューファイルとコントローラーの関係に対応づけて理解すると早いかなと思います。テンプレートが選択肢に出てこないときは、ファイルの書き方を疑う前に、まずアクティブテーマを確認してみてください。
よくある質問
Template Nameコメントを書いたファイル名は自由ですか？
はい、ファイル名は任意です。Template Name:から始まるコメントが書かれていることが、WordPressがテンプレートとして認識する条件です。
get_page_templates()が空配列を返すのは他にどんな原因がありますか？
僕の環境ではアクティブテーマの問題でしたが、テーマフォルダの配置やファイルのパーミッションなど、環境によって他の原因もあり得ます。まずはwp theme listでアクティブテーマを確認するのがおすすめです。
フルカスタムページでもGutenbergエディタは使えますか？
テンプレート側でHTMLを直接書く設計にした場合、the_content()を呼んでいなければGutenbergで書いた内容は表示に反映されません。今回のLPのような構造固定のページでは、意図的にこの方式を選びました。
コメント