Twig Tweak

Drupal開発に便利な関数とフィルターを提供するTwig拡張モジュールです。Twigテンプレート内でEntity、Block、Views、メニューなどを直接レンダリングできます。

twig_tweak
175,501 sites
258
drupal.org
api theme development utility
Twig theming templating rendering blocks Views entities fields menus images debugging development filters functions
Drupal 9 Drupal 10 Drupal 11

インストール

Drupal 11, 10 v3.4.1
composer require 'drupal/twig_tweak:^3.4'
Drupal 9 v3.3.0
composer require 'drupal/twig_tweak:^3.3'

概要

Twig TweakはTwigテンプレートエンジンを拡張し、Drupal開発向けに設計された包括的な関数とフィルターのセットを提供する強力なモジュールです。DrupalのPHPベースのアーキテクチャとTwigのテンプレート構文の間を橋渡しし、テーマ開発者がpreprocess hookでPHPコードを書くことなく、テンプレート内で直接Drupalの機能にアクセスできるようにします。

このモジュールは、Block、Entity、Field、Views、メニュー、画像、フォームなどをレンダリングするための20以上のTwig関数を提供します。また、Tokenの置換、画像スタイルの適用、URL生成、キャッシュメタデータの処理などの一般的な操作のための17以上のフィルターも含まれています。すべての関数はDrupalのrender arrayシステムとキャッシュメタデータを適切に処理し、最適なパフォーマンスと正確なキャッシュ動作を保証します。

開発目的として、Twig Tweakには変数検査用のdrupal_dump()とdd()、Xdebug統合用のdrupal_breakpoint()、TwigテンプレートのリントとデバッグのためのDrushコマンドなどのデバッグ関数が含まれています。モジュールはパフォーマンスを考慮して設計されており、関数が使用されないときのオーバーヘッドを最小限に抑えるために遅延読み込みサービスを使用しています。

Features

  • drupal_block()を使用してTwigテンプレート内でBlock pluginを直接レンダリング。カスタム設定とコンテキストマッピングをサポート
  • drupal_view()でViewsのdisplayを埋め込み、drupal_view_result()で条件付きレンダリングのためにViewsの結果を確認
  • drupal_entity()で任意のEntity typeをレンダリング。view mode、言語コード、アクセスチェックをサポート
  • drupal_entity_form()でEntityの編集/作成フォームを表示。カスタムform modeもサポート
  • drupal_field()でEntityの個別Fieldをレンダリング。view modeまたはカスタム表示オプションを使用
  • drupal_menu()でメニューを構築してレンダリング。深さ、レベル、展開の設定が可能
  • drupal_image()でファイルID、UUID、またはURIから画像をレンダリング。画像スタイルとレスポンシブ画像をサポート
  • drupal_config()でDrupalの設定値にアクセスし、drupal_token()でTokenを置換
  • drupal_url()とdrupal_link()でURLとリンクを生成。アクセスチェックを含む
  • drupal_region()でテーマのリージョンをレンダリングし、カスタムページレイアウトを作成
  • drupal_messages()でステータスメッセージを表示、drupal_breadcrumb()でパンくずリストを表示
  • drupal_contextual_links()で任意の要素にコンテキストリンクを追加
  • drupal_dump()/dd()でSymfony VarDumper統合による変数のデバッグ
  • drupal_breakpoint()でテンプレート内にXdebugブレークポイントを設定
  • image_styleフィルターでURIに画像スタイルを適用
  • file_uriとfile_urlフィルターでEntityとFieldからファイルURIとURLを抽出
  • entity_urlとentity_linkフィルターでEntityのURLとリンクを生成
  • translationフィルターで多言語サイト向けにEntityの翻訳を取得
  • cache_metadataフィルターで適切なキャッシュのためにキャッシュメタデータを抽出してバブルアップ
  • childrenフィルターでrender arrayの子要素をフィルタリング
  • preg_replaceフィルターで正規表現による置換を実行
  • token_replaceフィルターで文字列内のTokenを置換
  • transliterateフィルターでUnicodeをASCIIに変換
  • truncateフィルターで文字列を安全に切り詰め
  • data_uriフィルターでインライン埋め込み用のデータURIを作成
  • TwigテンプレートのリントとデバッグのためのDrushコマンド（twig-tweak:lintとtwig-tweak:debug）
  • カスタム関数、フィルター、テストを追加するためのhookによる拡張可能なアーキテクチャ

Use Cases

カスタムページテンプレートでBlock pluginをレンダリング

drupal_block()を使用して、Block layoutで設定することなくテンプレート内にBlock pluginを直接埋め込みます。例: {{ drupal_block('system_branding_block', {use_site_name: true}) }} でサイトブランディングをレンダリングします。コンテキストが必要なBlockの場合はcontext_mappingを使用: {{ drupal_block('plugin_id', {context_mapping: {node: '@node.node_route_context:node'}}) }}

コンテキストフィルター付きでViewsをテンプレートに埋め込む

drupal_view()を使用してテンプレートにViewsのdisplayを埋め込み、オプションでコンテキストフィルターの引数を渡します。例: {{ drupal_view('articles', 'block_1', node.id) }} で現在のNodeのIDをコンテキストフィルターとしてViewを埋め込みます。まず結果があるか確認: {% if drupal_view_result('related', 'block_1')|length > 0 %}{{ drupal_view('related', 'block_1') }}{% endif %}

EntityのFieldをレンダリングして関連コンテンツを表示

参照されたEntityから特定のFieldをレンダリング: {{ drupal_field('field_image', 'node', node.id, 'teaser') }}。カスタム表示設定の場合: {{ drupal_field('field_image', 'node', 1, {type: 'image_url', settings: {image_style: 'large'}}) }}

画像スタイルを使用したレスポンシブ画像の作成

drupal_image()でスタイル付きの画像をレンダリング: {{ drupal_image('public://hero.jpg', 'wide', {alt: 'Hero image'|t}, responsive=true) }}。Fieldからの画像にはフィルターと組み合わせ: {% set uri = node.field_image|file_uri %}{% if uri %}{{ drupal_image(uri, 'thumbnail') }}{% endif %}

特定の深さでカスタムメニューを構築

レベルと展開を制御してメニューをレンダリング: {{ drupal_menu('main', 2, 3) }} でメインメニューをレベル2から深さ3でレンダリングします。完全に展開したメニューにはexpand=trueを使用: {{ drupal_menu('main', expand=true) }}

テンプレートで多言語コンテンツを処理

translationフィルターを使用して翻訳されたEntityを取得: {{ media|translation.field_description|view }}。フィルターはデフォルトで現在の言語コンテキストを使用するか、言語コードを受け入れます: {{ node|translation('fr') }}

cache_metadataフィルターで適切なキャッシュを確保

Entityの生の値にアクセスする際、古いコンテンツを防ぐためにキャッシュメタデータをバブルアップ: <img src="{{ node.field_image|file_url }}" />{{ content.field_image|cache_metadata }}。これにより、画像が変更されたときにレンダーキャッシュが確実に無効化されます。

開発中にテンプレートで変数をデバッグ

dd()（drupal_dumpのエイリアス）を使用して変数を検査: {{ dd(node) }} でNodeオブジェクトをダンプします。引数なしで呼び出すとすべてのテンプレート変数をダンプ: {{ dd() }}。最良の出力を得るにはsymfony/var-dumperパッケージが必要です。drupal_breakpoint()を使用してXdebugブレークポイントをトリガーできます。

データURIを使用してインラインSVGアイコンを作成

data_uriフィルターを使用してSVGアイコンをインラインで埋め込み: <img src="{{ source(directory ~ '/images/icon.svg')|data_uri('image/svg+xml') }}" />。小さなグラフィックの追加HTTPリクエストを排除します。

フロントエンド編集用にEntityフォームをレンダリング

Entity編集フォームを表示: {{ drupal_entity_form('node', node.id) }}。デフォルト値で新規Entityフォームを作成: {{ drupal_entity_form('node', values={type: 'article', title: 'New Article'}) }}。必要に応じてcheck_access=falseを使用して権限チェックをバイパスします。

テンプレートで設定値にアクセス

Drupal設定を直接読み取り: {{ drupal_config('system.site', 'name') }} でサイト名を出力します。preprocess hookなしで設定を表示するのに便利です。

アクセスチェック付きで条件付きリンクを生成

アクセス権を持つユーザーにのみ表示されるリンクを作成: {{ drupal_link('Edit'|t, '/node/' ~ node.id ~ '/edit', check_access=true) }}。ユーザーに権限がない場合、リンクはレンダリングされません。

Tips

  • 可読性を向上させるためにオプションパラメータには名前付き引数を使用: {{ drupal_entity('block', 'sidebar_block', check_access=false) }}
  • drupal_view_result()関数はレンダリングされたViewではなく結果オブジェクトを返します - 結果が存在するかどうかの確認にのみ使用してください
  • Block plugin IDはDrushで確認できます: drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));"
  • Block content Entityの場合、drupal_entity('block_content', id)またはdrupal_block('block_content:<uuid>')のいずれかを使用 - 後者はblock.html.twigラッパーを含みます
  • file_uriとfile_urlフィルターはOEmbedリモートメディアを含むMedia Entityをサポートし、外部リソースのリモートURLを返します
  • Entityをレンダリングする際、check_accessパラメータはデフォルトでTRUEです - 他の場所でアクセスを確認した場合にのみFALSEに設定してください
  • drupal_field()はLayout Builderを使用したview modeでは動作しません - 代わりにEntityのレンダリング出力を使用してください
  • drupal_dump()とdd()関数からより良い出力を得るためにsymfony/var-dumperをインストールしてください
  • coreのwithoutフィルターの逆としてwithフィルターを使用してプロパティを追加: {{ content.field_image|with('#title', 'Photo'|t) }}
  • キャッシュキーはview builderによって自動的に追加されます - 通常、手動でキャッシュを管理する必要はありません

Technical Details

Hooks 3
hook_twig_tweak_functions_alter

モジュールとテーマがTwig Tweakが提供するTwig関数を追加または変更できるようにします。関数はTwigFunctionオブジェクトとして追加されます。

hook_twig_tweak_filters_alter

モジュールとテーマがTwig Tweakが提供するTwigフィルターを追加または変更できるようにします。フィルターはTwigFilterオブジェクトとして追加されます。

hook_twig_tweak_tests_alter

モジュールとテーマがカスタムTwigテストを追加できるようにします。テストはTwigTestオブジェクトとして追加されます。

Drush Commands 2
drush twig-tweak:debug

現在のDrupalインストールで利用可能なすべてのTwig関数、フィルター、テストをシグネチャとともにリスト表示します。テンプレート名前空間のローダーパスを表示します。

drush twig-tweak:validate

Twigテンプレートの構文を検証し、見つかったエラーを出力します。個別のファイル、ディレクトリ、またはSTDINから読み取ることができます。twig-tweak:lintのエイリアスです。

Security Notes 4
  • PHPフィルター（|php）はデフォルトで無効になっており、コードインジェクションのリスクがあるため本番環境では無効のままにしてください
  • check_access=falseを使用する場合は、コンテンツへの不正アクセスを防ぐために他の方法でユーザー権限を確認してください
  • $settings['twig_tweak_enable_php_filter']設定をユーザーがアクセス可能な設定に公開しないでください
  • drupal_form()は機密性の高い操作を実行する可能性のあるフォームをレンダリングするため、適切なアクセス制御を確保して注意して使用してください