Twig - includeタグとは
Twigテンプレートファイルの中に、別のテンプレートファイルを組み込むことができる。
どういうとき使うか？
問合せボタンやサイドバーのパーツといった共通部分をインクルードファイルにしておき、各ページで共有する。
こうしておけば共通部分に変更があったときに、そのインクルードファイルを修正すれば、それらが読み込まれているすべてのページに反映することができる。
テンプレートファイルをインクルードする on Drupal 7
例）phpのinclude関数を利用する
<div class="page-sidebar">
<?php include dirname(__FILE__) . '/includes/sidebar_part01.inc'; ?>
</div>
例）DrupalテーマAPIを利用する
<div class="page-sidebar">
<?php
$args = array('tid' => $term->tid);
print theme('sidebar_part01', $args);
?>
</div>
Twig - includeタグでインクルードする on Drupal 8
引数には、Drupalルートからのパスを指定する。（相対パスは使用不可）
{% include "themes/custom/my_theme/templates/inquiry-box.html.twig" %}
一方、ファイル名のみを指定することが可能。
{% include "inquiry-box.html.twig" %}
ファイル名のみを指定した場合、Drupalのテーマ継承のルールに従ってファイルがロードされる。
directory変数を利用する
テンプレートファイルのパスを補完する際、directory変数が便利。
{% include directory ~ '/templates/inquiry-box.html.twig' %}
もちろん、includeタグ以外でも利用できる。
<img src="/{{ directory }}/images/logo.svg" alt="logo" />
active_theme_path()を利用する
Twig関数active_theme_path()は、アクティブな公開テーマパスを出力する。
{% include active_theme_path() ~ '/templates/custom/solution-inquiry-box.html.twig' %}
Drupal7のpath_to_theme()に相当するものと言うと伝わりやすいかもしれません。
Twigネームスペースを使用する
Twigネームスペースは、＠テーマ名、 または＠モジュール名が使用できる。
テーマ直下、またはモジュール直下のtemplatesディレクトリパスまでが補完される。
例）twigネームスペースによるテーマパスの指定
{% include "@my_theme/custom/inquiry-box.html.twig" %}
一方、画像ファイルなどをインクルードしたいときはactive_theme_path()などを使いましょう。
変数を渡す
インクルードしたテンプレートは、親テンプレートのコンテキストと変数がそのまま渡される。
例）インクルード先のテンプレートに変数を渡す
{% set vars = {'foo': 'bar'} %}
{% include 'inquiry-box.html.twig' %}
渡されたコンテキスト・変数一覧の確認方法
{{ dump(_context|keys) }}を使えば自動的に渡っているコンテキスト一覧が確認可能。
withキーワード
withキーワードを使用すると、テンプレートに渡す変数を直接指定することができる。
{% include "inquiry-box.html.twig" with {'var01' : 'value01'} %
この場合、withキーワードで指定した変数と一緒に、親テンプレートの変数・コンテキストが合わせて渡される。
onlyキーワード
親テンプレートの変数・コンテキストを渡したくなければ、onlyキーワードを指定する。
例）withで指定した変数以外を制限する
{% include 'template.html.twig' with {'foo': 'bar'} only %}
例）変数・コンテキストを一切渡さない
{% include 'template.html.twig' only %}
onlyキーワードを使う理由としては、単にコンテキストによる影響を無効するだけでなく、パフォーマンスもわずかに向上すると言われている。
ファイルを読み込めなかったときのリカバリ
ignore missingキーワード
テンプレートファイルが存在しない場合、致命的エラーとなり、白い画面にエラーメッセージが吐かれてしまう。
しかし、ignore missingキーワードを指定しておくと、エラーメッセージを吐かずに空の文字列を返すようになる。
{{ include 'sidebar.html', ignore missing with {} only }}
キーワードの列挙順序は、with,onlyよりも前に記述する必要あり。
テンプレートファイル名の複数候補を指定する
配列でテンプレートファイル名を複数指定することが可能。
その場合、配列の先頭からテンプレートの存在可否が検証されて、最初に見つかったテンプレートがインクルードされる。
{% include(['status-messages-custom.html.twig','status-messages.html.twig']) %}
ただし、1件もヒットしなければ、やはり致命的エラーになるが、ignore missingキーワードを設定しておけばテンプレートが1つも存在しなければエラーを回避できる。