ANNAIマガジン
twig
この記事は「 Twig Template naming conventions 」の翻訳です。
この記事の目次

Drupalは特定の命名規則に基づいてテンプレートを読み込みます。これにより、テンプレートにテーマを追加して特定の名前を付けることで、テンプレートを上書きすることができます。

テンプレートを追加後、Drupalが新しいテンプレートを発見するためには、キャッシュを削除して再構築する必要があります。

Twigテンプレートをデバッグすることで、ある特定の要素のマークアップを出力するために使用されているテンプレートを特定できます。 詳しくはTwigのデバッグをご覧ください。

このページには、基本HTML構造、ページ、リージョン、ブロック、ノード、フィールド、その他のコアコンポーネントに使用されている規則がリスト化されています。 (関数hook_theme_サジェスチョンs_HOOK_alterを使用してカスタムテンプレート名のサジェスチョンを作成することが可能であることを理解しておいてください。)

HTML (<head> テンプレート)

HTMLテンプレートは、<head>タグ、<title>タグ、および<body>タグを含むHTMLページの基本構造のマークアップを提供します。

ベーステンプレート:html.html.twig
ベーステンプレートの位置:core / modules / system / templates / html.html.twig

ベーステンプレートを上書きする方法の例を次に示します。

  1. html--internalviewpath.html.twig
  2. html--node--id.html.twig
  3. html.html.twig

詳細はhtml.html.twig APIの ドキュメントをご覧ください。

ページテンプレート

パターン: page--[front|internal/path].html.twig
ベーステンプレート: page.html.twig
ベーステンプレートの位置: core/modules/system/templates/page.html.twig

サジェスチョンは多数あり、フロントページが優先されます。残りの部分は、現在のページの内部パスに基づいています。フロントページは、[管理]> [設定]> [システム]> [サイト情報]で設定できます。

http://example.com/admin/config/system/site-information)。フロントページテンプレートはpage-front.html.twigです。内部パスとパスエイリアスを混同しないでください。パスエイリアスは、考慮されません。

suggestされるテンプレートファイルのリストは、内部パスに基づいて特定の順になっています。現在のパスのすべての要素に対して1つのサジェスチョンが行われますが、数値要素は後続のサジェスチョンには反映されません。たとえば、「http://www.example.com/node/1/edit 」と入力すると、次のような候補が表示されます。

  1. page--node--edit.html.twig
  2. page--node--1.html.twig
  3. page--node.html.twig
  4. page.html.twig

詳細はpage.html.twig API のドキュメント と  メンテナンスページのテンプレート をご覧ください。

リージョンテンプレート

パターン: region--[region].html.twig
ベーステンプレート: region.html.twig
ベーステンプレートの位置: core/modules/system/templates/region.html.twig

リージョンテンプレートは、ページリージョンにコンテンツがある場合、ブロックシステムかhook_page_build()のような関数のいずれかから使用されます。可能なリージョン名は、テーマの.info.ymlファイルによって決まります。

詳細はregion.html.twig APIの ドキュメントをご覧ください。

ブロックテンプレート

パターン: block--[module|-delta]].html.twig
ベーステンプレート: block.html.twig
ベーステンプレートの位置: core/modules/block/templates/block.html.twig

  1. block--module--delta.html.twig
  2. block--module.html.twig
  3. block.html.twig

「module」はモジュールの名前であり、「delta」はモジュールによってブロックに割り当てられた内部IDです。

たとえば、ブロック管理画面からユーザが最初に追加したブロックには、idとして1がブロックモジュールによって割り当てられます。そのため「block-block-1.html.twig」が使用されます。リージョン固有ブロックテンプレートはDrupal 8では利用できません

「custom」というカスタムモジュールと「my-block」というデルタで作成されたブロックがある場合、テーマフックのサジェスチョンは「block--custom--my-block.html.twig」と呼ばれます。

Viewsで作成したブロックの1つの例として、ビュー名が "front_news"で、ディスプレイIDが "block_1"のビューで作成されたブロックの場合、テーマフックのサジェスチョンは次のようになります。

block--views-block--front-news-block-1.html.twig(表示IDまたはビュー名にアンダースコアがある場合は、それらを単一のダッシュに変換する必要があります。)

このコンテキストでは、モジュール名で大文字と小文字が区別されることに注意してください。たとえば、モジュールが 'MyModule'と呼ばれる場合、このモジュールの最も一般的なテーマフックのサジェスチョンは "block--MyModule.html.twig"です。

詳細はblock.html.twig APIのドキュメントをご覧ください

ノードテンプレート

パターン: node--[type|nodeid]--[viewmode].html.twig
ベーステンプレート: node.html.twig
ベーステンプレートの位置: core/modules/node/templates/node.html.twig

テーマフックのサジェスチョンは、最も対象範囲の狭いのテンプレートから順にファイルを検索していき、最初に見つかったテンプレートを使用します。 例えばノードの場合は以下のファイルが順に検索され、対象範囲の狭い(リストの番号の若い)テンプレートが優先して使用されます。

  1. node--nodeid--viewmode.html.twig
  2. node--nodeid.html.twig
  3. node--type--viewmode.html.twig
  4. node--type.html.twig
  5. node--viewmode.html.twig
  6. node.html.twig

コンテンツタイプのマシン名に下線がハイフンに置き換えられていることに注意してください。
詳細はnode.html.twig APIのドキュメントをご覧ください。

タクソノミータームテンプレート

パターン: taxonomy-term--[vocabulary-machine-name|tid].html.twig
ベーステンプレート: taxonomy-term.html.twig
ベーステンプレートの位置: core/modules/taxonomy/templates/taxonomy-term.html.twig

テーマフックのサジェスチョンは、最も対象範囲の狭いのテンプレートから順にファイルを検索していき、最初に見つかったテンプレートを使用します。 例えばタクソノミーの場合は以下のファイルが順に検索され、対象範囲の狭い(リストの番号の若い)テンプレートが優先して使用されます。

  1. taxonomy-term--tid.html.twig
  2. taxonomy-term--vocabulary-machine-name.html.twig
  3. taxonomy-term.html.twig

ボキャブラリのマシン名の下線はハイフンに置き換えられていることに注意してください。
taxonomy-term.html.twig APIのドキュメントをご覧ください。

フィールドテンプレート

パターン: field--[type|name[--content-type]|content-type].html.twig
ベーステンプレート: field.html.twig
ベーステンプレートの位置: core/modules/system/templates/field.html.twig

テーマフックのサジェスチョンは、最も対象範囲の狭いのテンプレートから順にファイルを検索していき、最初に見つかったテンプレートを使用します。 例えばフィールドの場合は以下のファイルが順に検索され、対象範囲の狭い(リストの番号の若い)テンプレートが優先して使用されます。

  1. field--field-name--content-type.html.twig
  2. field--content-type.html.twig
  3. field--field-name.html.twig
  4. field--field-type.html.twig
  5. field.html.twig

フィールドのマシン名に下線がハイフンに置き換えられていることに注意してください。カスタムフィールド名に「field-」を含めることも忘れないでください(例:field--field-phone.html.twig.)。

詳細はfield.html.twig APIのドキュメントをご覧ください。

コメントテンプレート

パターン: comment--node-[type].html.twig
ベーステンプレート: comment.html.twig
ベーステンプレートの位置: core/modules/comment/template/comment.html.twig

comment--node-type.html.twigファイルを作成して、サイト内の他のコメントとは異なる、ある特定のノードタイプのコメントをオーバーライドするための機能が追加されました。たとえば、記事タイプのノードに対して行われたコメントは「comment--node-article.html.twig」です。

comment.html.twig APIのドキュメントをご覧ください。

コメントラッパーテンプレート

パターン: comment-wrapper--node-[type].html.twig
ベーステンプレート: comment-wrapper.html.twig

上記と同様ですが、ラッパーテンプレート用です。

フォーラムテンプレート

パターン: forums--[[container|topic]--forumID].html.twig
ベーステンプレート: forums.html.twig
ベーステンプレートの位置: core/modules/forum/templates/forums.html.twig

テーマフックのサジェスチョンは、最も対象範囲の狭いのテンプレートから順にファイルを検索していき、最初に見つかったテンプレートを使用します。 例えばフォーラムの場合は以下のファイルが順に検索され、対象範囲の狭い(リストの番号の若い)テンプレートが優先して使用されます。

フォーラムコンテナ:

  1. forums--containers--forumID.html.twig
  2. forums--forumID.html.twig
  3. forums--containers.html.twig
  4. forums.html.twig

フォーラムトピックス:

  1. forums--topics--forumID.html.twig
  2. forums--forumID.html.twig
  3. forums--topics.html.twig
  4. forums.html.twig

詳細はforums.html.twig APIのドキュメントをご覧ください。

メンテナンスページテンプレート

パターン: maintenance-page--[offline].html.twig
ベーステンプレート: maintenance-page.html.twig
ベーステンプレートの位置: core/modules/system/templates/maintenance-page.html.twig

これは、データベースに障害が発生した場合に適用されます。エラーメッセージなしでユーザーフレンドリーなページを表示するのに便利です。これにはメンテナンスページを設定する必要があります。

詳細はmaintenance-page.html.twig APIのドキュメントをご覧ください。

データベースが利用できない場合、現在、maintenance-page-offline.html.twigファイルはレンダリングされていないことに注意してください。追跡中の問題:#2720109: "Theming" page--maintenance--offline - fatal errors

検索結果テンプレート

パターン: search-result--[searchType].html.twig
ベーステンプレート: search-result.html.twig
ベーステンプレートの位置: core/modules/search/templates/search-result.html.twig

search-result.html.twigは、個々の検索結果のデフォルトのラッパーです。検索のタイプ??に応じて、さまざまなサジェスチョンが行われます。たとえば、「example.com/search/node/Search+Term」と入力すると、「search-result--node.html.twig」が使用されます。

これを「example.com/search/user/bob」が入力された場合に使用される「search-result--user.html.twig」と比較してみてください。モジュールは検索タイプを拡張して、そのタイプのサジェスチョンを追加することができます。

詳細はsearch-result.html.twig APIのドキュメントをご覧ください。

この記事を書いた人 : Kentaro Inoue

ANNAI株式会社
マーケティングマネージャー
サービスの設計・企画、マーケティング、採用戦略の立案などを担当。普段は新潟で猫と一緒に、時々海外からリモートで働いています。好きなモジュールはRulesとFlagです。

関連コンテンツ