Twig Template Suggester
Drupal コアがカバーしていない要素に対して広範なテンプレートサジェスチョンを提供し、Block、フォーム、メニュー、ユーザー、Taxonomy Term などの精密なテーマ制御を可能にします。
twigsuggest
概要
Twig Template Suggester は、コアがネイティブでサポートしていないさまざまな要素に対して追加のテンプレートサジェスチョンを提供することで、Drupal コアのテンプレートサジェスチョンシステムのギャップを埋めます。これにより、テーマ開発者はリージョン、View モード、Bundle、Entity タイプなどのコンテキストに基づいて、より具体的なテンプレートを作成できます。
このモジュールは、Block（リージョン、Bundle、プロバイダー別）、ページおよび HTML ドキュメント（Node タイプ別）、ユーザー（ロールおよび View モード別）、Field（View モード別）、フォーム（フォーム ID およびリージョン別）、コンテナ（タイプおよびコンテキスト別）、メニュー（リージョンおよび名前別）、Taxonomy Term（View モード別）、Book ツリー（リージョン別）、ローカルアクションリンク（ルート別）のテンプレートサジェスチョンを自動的に登録します。
開発者ユーティリティとして、モジュールの重みを 100 に設定し、サジェスチョンが最後に処理されるようにすることで、テンプレートサジェスチョンに対する最終的な決定権を持ちます。また、すべてのテンプレートでアセットパスを便利に構築できるグローバル変数 {{ base_path }} を提供します。
Features
- リージョン別の Block テンプレートサジェスチョン（block--[region].html.twig、block--[region]--[block_id].html.twig）
- カスタム/コンテンツ Block 用の Bundle 別 Block テンプレートサジェスチョン（block--bundle--[bundle].html.twig）
- プロバイダーおよびベースプラグインとリージョンの組み合わせによる Block テンプレートサジェスチョン
- Node タイプ別の HTML およびページテンプレートサジェスチョン（html--node--[type].html.twig、page--node--[type].html.twig）
- 最高ロール、ユーザー ID、View モード別のユーザーテンプレートサジェスチョン（user--[role]--[view_mode].html.twig）
- View モード、Entity タイプ、Bundle の組み合わせによる Field テンプレートサジェスチョン
- フォーム ID、要素 ID、リージョン別のフォームテンプレートサジェスチョン（form--[form_id].html.twig）
- 要素 ID およびタイプ別のフォーム要素と input テンプレートサジェスチョン
- タイプ、View 名/ディスプレイ、マネージドファイル Field、親ステータス別のコンテナテンプレートサジェスチョン
- リージョンおよびメニュー名別のメニューテンプレートサジェスチョン（menu--[region].html.twig）
- View モードおよび Bundle 別の Taxonomy Term テンプレートサジェスチョン
- リージョン別の Book ツリーテンプレートサジェスチョン
- リンクルート別のメニューローカルアクションテンプレートサジェスチョン
- Entity 固有のレイアウトテンプレートの修正（コア Issue #2881195 の回避策）
- Block からの重複テンプレートサジェスチョンを削除
- アセットパス用のすべてのテンプレートで {{ base_path }} 変数を提供
Use Cases
リージョン固有の Block スタイリング
各リージョンに異なる Block スタイルを作成します。たとえば、サイドバーの Block はヘッダーの Block とは異なるスタイリングが必要な場合があります。block--sidebar.html.twig や block--header.html.twig などのテンプレートを作成して、特定のリージョン内のすべての Block をターゲットにします。
Node タイプ固有のページレイアウト
異なるコンテンツタイプに完全に異なるページレイアウトを適用します。広いコンテンツエリアを持つ記事用に page--node--article.html.twig を作成し、異なる構造のランディングページ用に page--node--landing_page.html.twig を作成します。
ロールベースのユーザープロファイルテーマ
ユーザーロールに基づいてユーザープロファイルを異なる方法で表示します。管理者プロファイル用に user--administrator--full.html.twig を作成したり、一般メンバー用に user--member.html.twig を作成したりできます。
View モード対応の Field テンプレート
View モードによって同じ Field を異なるスタイルにします。たとえば、画像 Field は「full」View モードでは大きく、「teaser」ではサムネイルになる場合があります。field--field_image--full.html.twig と field--field_image--teaser.html.twig を作成します。
フォームごとまたはリージョンごとのフォームスタイリング
特定のフォームまたはリージョン内のすべてのフォームに独自のスタイリングを適用します。ログインフォーム用に form--user_login_form.html.twig を使用したり、サイドバーリージョンに配置されたすべてのフォーム用に form--sidebar.html.twig を使用したりできます。
リージョン別のメニュースタイリング
配置場所に基づいてメニューを異なるスタイルにします。ヘッダーのメインナビゲーションは水平（menu--header.html.twig）で、フッターの同じメニューは垂直リスト（menu--footer.html.twig）としてスタイリングできます。
Taxonomy Term の View モードテンプレート
異なるコンテキストで Taxonomy Term を異なる方法で表示します。完全な Term ページ用に taxonomy_term--tags--full.html.twig を作成し、Term リスト用に taxonomy_term--tags--teaser.html.twig を作成します。
コンテンツタイプ固有の HTML ラッパー
コンテンツタイプに基づいて異なる body クラスやメタ情報を適用します。html--node--article.html.twig を作成して、記事専用の schema.org マークアップやトラッキングコードを追加します。
Tips
- 開発中は Twig デバッグを有効にして、ページソースの HTML コメントで利用可能なすべてのテンプレートサジェスチョンを確認してください
- テンプレートファイル名にはダッシュを使用してください（例：block--sidebar--main-menu.html.twig）- サジェスチョン名のアンダースコアに対応します
- {{ base_path }} 変数はすべてのテンプレートで使用可能です - テーマアセットの参照に便利です：{{ base_path ~ directory }}/images/logo.svg
- Block タイプ固有のテンプレートについては、より完全なカバレッジのために Block Type Templates モジュールを Twig Template Suggester と併用することを検討してください
- テンプレートサジェスチョンは具体性の順に並んでいます - より具体的なサジェスチョンは後に表示され、優先されます
- メニューリージョンサジェスチョンでは、テーマの Block テンプレートで 'region' 属性を設定する必要があることを忘れないでください
Technical Details
Hooks 17
hook_theme_suggestions_block
リージョン、Bundle（コンテンツ Block 用）、プロバイダー、ベースプラグイン、メニュー名の組み合わせに基づいて Block のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_layout_alter
Display Suite 設定が存在する場合、レイアウト ID にダブルアンダースコアを追加することで Entity 固有のレイアウトテンプレートを修正します。デフォルトでは無効で、settings.php で有効にします。
hook_theme_suggestions_container
タイプ、View コンテキスト、マネージドファイルラッピング、親ステータス、グループ、Webform キーに基づいてコンテナ要素のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_form_alter
要素 ID、フォーム ID、リージョンに基づいてフォームのテンプレートサジェスチョンを追加します。リージョン属性が設定されている場合、リージョン固有のフォームテンプレートをサポートします。
hook_theme_suggestions_form_element
要素 ID、タイプ、Webform ID に基づいてフォーム要素のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_input
要素 ID に基づいて input 要素のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_user
ユーザー ID、View モード、最高ロールに基づいてユーザー Entity のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_html
現在の Node タイプに基づいて HTML ラッパーのテンプレートサジェスチョンを追加します。
hook_theme_suggestions_page
現在の Node タイプに基づいてページテンプレートのサジェスチョンを追加します。
hook_theme_suggestions_field
View モード、Entity タイプ、Bundle の組み合わせに基づいて Field のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_field_alter
Entity Reference のターゲットタイプを Field テンプレートサジェスチョンとして追加します。
hook_theme_suggestions_taxonomy_term
View モード、Bundle、Term ID に基づいて Taxonomy Term のテンプレートサジェスチョンを追加します。
hook_theme_suggestions_book_tree
リージョンに基づいて Book ツリーのテンプレートサジェスチョンを追加します。
hook_theme_suggestions_block_alter
サジェスチョンリストをクリーンに保つため、Block から重複したテンプレートサジェスチョンを削除します。
hook_theme_suggestions_menu_alter
リージョンに基づいてメニューのテンプレートサジェスチョンを追加します。特定のメニューとリージョン内のすべてのメニューの両方をサポートします。
hook_theme_suggestions_menu_local_action_alter
リンクのルート名に基づいてメニューローカルアクションのテンプレートサジェスチョンを追加し、段階的に具体的なサジェスチョンを構築します。
hook_preprocess
すべてのテンプレートに base_path 変数を追加し、Twig でのアセットパスの構築を容易にします。
Troubleshooting 5
/admin/config/development/settings で Twig デバッグが有効になっていることを確認してください。drush cr ですべての Cache をクリアしてください。利用可能なサジェスチョンを示す HTML コメントについては、ページソース（ブラウザインスペクタではなく）を確認してください。
テンプレートファイル名がサジェスチョンと正確に一致していることを確認してください（ファイル名ではハイフンではなくアンダースコアを使用）。テンプレートがテーマの templates ディレクトリにあることを確認してください。新しいテンプレートを追加した後は Cache をクリアしてください。
Block リージョンサジェスチョンは、Block レイアウト UI（/admin/structure/block）経由で Block を配置する必要があります。プログラムでレンダリングされた Block にはリージョン情報がない場合があります。
レイアウト修正はデフォルトで無効です。settings.php で有効にしてください：$config['twigsuggest.settings']['alternate_ds_suggestions'] = TRUE; これはすべての DS 設定で機能するとは限りません。
Twig Template Suggester は最後に実行されるようにモジュールの重みを 100 に設定しています。別のモジュールがより高い重みを持っている場合、そのサジェスチョンが優先されます。system.module テーブルでモジュールの重みを確認してください。