Twigテンプレートの命名規則

03/05/2020, by maria

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

テンプレートを追加したら、Drupalが新しいテンプレートを検出するためにキャッシュを再構築する必要があります。

Twigテンプレートをデバッグして、特定の要素のマークアップの出力にどのテンプレートが使用されているかを確認できます。Twigデバッグの詳細はこちら。

このページでは、基本HTML構造、ページ、リージョン、ブロック、ノード、フィールド、その他の主要コンポーネントに使用される規則を一覧表示します。（hook_theme_suggestions_HOOK_alter関数を使用して独自のテンプレート名候補を作成できることを知っておくと役立ちます。）

HTML（<head>テンプレート）

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

基本テンプレート：html.html.twig（基本の場所：core/modules/system/templates/html.html.twig）

基本テンプレートをオーバーライドする方法の例をいくつか示します：

html--[internalviewpath].html.twig
html--node--[nodeid].html.twig
html.html.twig

html.html.twig APIドキュメントを参照してください。

Pageテンプレート

テンプレート：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です。
内部パスをパスエイリアスと混同しないでください。パスエイリアスは考慮されません。

推奨されるテンプレートファイルのリストは、内部パスに基づいて具体性の順に並べられています。現在のパスの各要素に対して1つの候補が作成されますが、数値要素は後続の候補には引き継がれません。たとえば、「http://www.example.com/node/1/edit」は次の候補になります：

page--node--edit.html.twig
page--node--1.html.twig
page--node.html.twig
page.html.twig

page.html.twig APIドキュメントを参照してください。また、下のメンテナンスページテンプレートも参照してください。

Regions

テンプレート：region--[region].html.twig
基本テンプレート：region.html.twig（基本の場所：core/modules/system/templates/region.html.twig）

リージョンテンプレートは、ブロックシステムまたはhook_page_top()やhook_page_bottom()などの関数からのコンテンツがページのリージョンにある場合に使用されます。使用可能なリージョン名は、テーマの.info.ymlファイルで定義されます。

region.html.twig APIドキュメントを参照してください。

Blocks

テンプレート：block--[module|--[delta].html.twig
基本テンプレート：block.html.twig（基本の場所：core/modules/block/templates/block.html.twig）

block--[module]--[delta].html.twig
block--[module].html.twig
block.html.twig

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

たとえば、「block--block--1.html.twig」は、ブロック管理画面で追加された最初のユーザー送信ブロックに使用されます。これは、ブロックモジュールによって識別子1で作成されたためです。リージョン固有のブロックテンプレートはDrupal 8では使用できません。

「custom」という名前のカスタムモジュールと「my-block」というデルタで作成されたブロックがある場合、テーマフックの候補は「block--custom--my-block.html.twig」になります。

Viewsを使った別の例：ビュー名「front_news」と表示ID「block_1」でViewsによって作成されたブロックがある場合、テーマフックの候補は次のようになります：block--views-block--front-news-block-1.html.twig（表示IDまたはビュー名にアンダースコアがある場合は、1つのハイフンに変換する必要があることに注意してください）

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

block.html.twig APIドキュメントを参照してください。

Nodes

テンプレート：node--[content-type|nodeid]--[viewmode].html.twig
基本テンプレート：node.html.twig（基本の場所：core/modules/node/templates/node.html.twig）

テーマフックの候補は、最も具体的なテンプレートから最も具体的でないテンプレートの順にリストされたこれらの要素に基づいて作成されます。Drupalは見つけた最も具体的なテンプレートを使用します：

node--[nodeid]--[viewmode].html.twig
node--[nodeid].html.twig
node--[content-type]--[viewmode].html.twig
node--[content-type].html.twig
node--[viewmode].html.twig
node.html.twig

コンテンツタイプのマシン名のアンダースコア（_）はハイフン（-）に置き換えられることに注意してください。

node.html.twig APIドキュメントを参照してください。

Taxonomy terms

テンプレート：taxonomy-term--[vocabulary-machine-name|tid].html.twig
基本テンプレート：taxonomy-term.html.twig（基本の場所：core/modules/taxonomy/templates/taxonomy-term.html.twig）

taxonomy-term--[tid].html.twig
taxonomy-term--[vocabulary-machine-name].html.twig
taxonomy-term.html.twig

ボキャブラリのマシン名のアンダースコアはハイフンに置き換えられることに注意してください。

taxonomy-term.html.twig APIドキュメントを参照してください。

Fields

テンプレート：field--[[type|name]|[entity-type]--[field-name|content-type]].html.twig
基本テンプレート：field.html.twig（基本の場所：core/modules/system/templates/field.html.twig）

field--node--[field-name]--[content-type].html.twig
field--node--[field-name].html.twig
field--node--[content-type].html.twig
field--[field-name].html.twig
field--[field-type].html.twig
field.html.twig

フィールドのマシン名のアンダースコア（_）はハイフン（-）に置き換えられることに注意してください。また、カスタムフィールド名には「field-」を含めることを忘れないでください。例：field--field-phone.html.twig。

field.html.twig APIドキュメントを参照してください。

Comments

テンプレート：comment--[comment-field-name]--[node-type].html.twig
基本テンプレート：comment.html.twig（基本の場所：core/modules/comment/templates/comment.html.twig）

特定のノードタイプのコメントをサイト上の他のコメントとは異なる形式にするために、comment--[comment-field-name]--[node-type].html.twigファイルを作成するサポートが追加されました。たとえば、記事タイプのノードで行われたコメントは「comment--field-comments--article.html.twig」になります。

comment.html.twig APIドキュメントを参照してください。

Comment wrappers

テンプレート：field--node--[comment-field-name]--[content-type].html.twig
基本テンプレート：field--comment.html.twig

Forums

テンプレート：forums--[[container|topic]--forumID].html.twig
基本テンプレート：forums.html.twig（基本の場所：core/modules/forum/templates/forums.html.twig）

フォーラムコンテナの場合：

forums--containers--[forumid].html.twig
forums--[forumid].html.twig
forums--containers.html.twig
forums.html.twig

フォーラムトピックの場合：

forums--topics--[forumid].html.twig
forums--[forumid].html.twig
forums--topics.html.twig
forums.html.twig

forums.html.twig APIドキュメントを参照してください。

Maintenance page

テンプレート：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：システムがオフラインのとき、maintenance-page--offline.html.twigが検出されない。

Search result

テンプレート：search-result--[search-type].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」の使用につながります。これを「search-result--user.html.twig」につながる「example.com/search/user/bob」と比較してください。モジュールは、タイプの候補を追加することで検索タイプを拡張できます。

search-result.html.twig APIドキュメントを参照してください。

Views

すべてのビューテンプレートは、ビュー、ビューディスプレイID、ビューディスプレイタイプ、またはそれらの組み合わせを使用して、さまざまな名前でオーバーライドできます。

各ビューには少なくとも2つのテンプレートが使用されます。最初のテンプレートはすべてのビューで使用されます：views-view.html.twig。

2番目のテンプレートは、ビュー用に選択されたスタイルによって決定されます。ビューの特定の側面も使用されるスタイルを変更できることに注意してください。たとえば、サマリービューを提供する引数は、スタイルを特別なサマリースタイルの1つに変更できます。

すべてのビューのデフォルトのスタイルはviews-view-unformatted.html.twigです。

多くのスタイルは、その後、各行の実際の表示を行スタイルでレンダリングします。デフォルトの行スタイルはviews-view-fields.html.twigです。

テンプレート：

views-view--[viewid]--[view-display-id].html.twig
views-view--[viewid]--[view-display-type].html.twig
views-view--[view-display-type].html.twig
views-view--[viewid].html.twig
views-view.html.twig

基本テンプレート：views-view.html.twig（基本の場所：core/themes/stable/templates/views/views-view.html.twig）

たとえば、ビューの「views-view.html.twig」テンプレートをオーバーライドする場合、次のテンプレート名が有効です：

views-view--[viewid]--[view-display-id].html.twig
views-view--[viewid]--page.html.twig
views-view--block.html.twig
views-view--[viewid].html.twig
views-view.html.twig

views-view-field.html.twigに基づくテンプレートには、ビュー内の単一のフィールドを表示するために、ビューフィールドID（置換テンプレートのように）が接尾辞として付けられます：

views-view-field--[viewid]--[view-display-id]--[fieldid].html.twig
views-view-field--[viewid]--page--[fieldid].html.twig
views-view-field--block--[fieldid].html.twig
views-view-field--[fieldid].html.twig
views-view-field.html.twig

次の場合に試行されるすべてのテンプレートの例を次に示します：

foobarという名前のビュー。スタイル：unformatted。行スタイル：fields。ディスプレイ：page。

views-view--foobar--page.html.twig
views-view--page.html.twig
views-view--foobar.html.twig
views-view.html.twig

views-view-unformatted--foobar--page.html.twig
views-view-unformatted--page.html.twig
views-view-unformatted--foobar.html.twig
views-view-unformatted.html.twig

views-view-fields--foobar--page.html.twig
views-view-fields--page.html.twig
views-view-fields--foobar.html.twig
views-view-fields.html.twig

パレット - カラフルに🎨