テンプレートファイルのSuggestionを追加する方法

こんにちは。
先日Japan ITWeekに参加したものの、1日で声を潰してしまった久保田です。
今日はテーマ開発には欠かせないテンプレートファイルについてのお話です。

テンプレートファイルとは

テンプレートファイルはHTMLのマークアップをカスタマイズしたい場合などに使用します。

通常は以下のようなデバッグ機能を使用して、 現在使用されているテンプレートファイルと同名のファイルを作成して上書きします。
例えばpageのマークアップを変更したい場合には、page.html.twigをカスタムテーマ内に作成します。

あるいは特定の場面だけマークアップを変更したい場合には、 あらかじめSuggestionsの中にあるファイル名の中から条件に該当するものを探し
その名前のテンプレートファイルを作成します。
例えばフロントページのマークアップだけ変更する場合は、page--front.html.twigをカスタムテーマ内に作成します。

上手くいかないときもある

しかしときにはSuggestionsの中にあるファイル名の候補だけではうまく対応できない場合があります。

例えば完全会員制のサイトで、ログイン前のユーザ（匿名ユーザー）が閲覧するページだけ変更したいようなケースだと、
匿名ユーザーのときにだけ現れるファイル名候補がないため、先ほどの例のようにはいきません。

もちろんpreprocessなどを駆使して、1つのテンプレートファイル内に匿名ユーザーと認証済みの2パターンを記述することもできますが、ファイルの可読性が落ちますし、分岐する条件がもっと増えるとより見づらくなってしまいます。。

hook_theme_suggestions_HOOK_alter を使おう

そんなときには hook_theme_suggestions_Hook_alter を使うことで解決できます。
このhookの中で独自のテンプレート名をSuggestionsに追加することができます。

例えば上述の匿名ユーザーのpageテンプレートを変更したい場合には、

/**
 * Implements hook_theme_suggestions_page_alter().
 */
function MY_THEME_NAME_theme_suggestions_page_alter(&$suggestions, &$variables) {
  // 匿名ユーザー用のサジェスチョンを追加する.
  if (\Drupal::currentUser()->isAnonymous()) {
    $suggestions[] = 'page__anonymous';
  }
}

のようにカスタムテーマ内のtemplate.phpに記述します。
匿名ユーザーでサイトを見てみると、

このように、Suggestionsの中にpage--anonymous.html.twigが追加されています。
あとはtemplatesフォルダの中にpage--anonymous.html.twigを作成してマークアップを記述することで
テンプレートを上書きすることができます。

ちなみにhook_theme_suggestions_HOOK_alterはtemplate.phpだけでなく、
カスタムモジュールのxxx.moduleファイルに実装しても機能します。

このように既存のSuggestionsでは上手く実装できない場合は、
ぜひhook_theme_suggestions_HOOK_alterを活用してみてください。