Token Filter
フォーマット済みテキストフィールド内のグローバルおよびEntityトークンを実際の値に置換するテキストフィルターモジュールです。
token_filter
インストール
composer require 'drupal/token_filter:^2.2'
composer require 'drupal/token_filter:^2.1'
概要
Token Filterは、DrupalのTokenシステムとテキストフォーマットを統合するシンプルなモジュールです。コンテンツがレンダリングされる際に、トークンプレースホルダー（[site:name]や[node:title]など）を対応する値に自動的に置換する入力フィルターを提供します。
このモジュールはTokenモジュールとシームレスに連携し、CKEditor 5内でToken Browserを提供します。これにより、コンテンツ編集者はWYSIWYGエディターインターフェースから直接、利用可能なトークンを簡単に参照して挿入できます。フィルターはグローバルトークン（サイト名や現在の日付などサイト全体の値）とEntity固有のトークン（Nodeタイトル、作成者名など）の両方をサポートしています。
コンテンツ編集時、トークンは保存されたテキスト内でプレースホルダーのまま維持され、レンダリング時にのみ実際の値に置換されます。これにより、動的コンテンツは常に最新の状態を自動的に保ちます。
Features
- レンダリング時にグローバルトークン（サイト名、現在の日付、現在のユーザーなど）を値に置換するテキストフィルター
- 表示中のEntity（Nodeタイトル、作成者など）からコンテキストに応じたトークンをサポートするEntityトークン置換
- CKEditor 5のToken Browserツールバー統合により、コンテンツ編集者がWYSIWYGエディターで直接トークンを参照・挿入可能
- 空トークンの処理を設定可能 - 置換できないトークンをそのまま残すか、出力から削除するかを選択
- 既存のToken Browserツールバー設定に対するCKEditor 4からCKEditor 5への自動移行サポート
- filter_tokensからtoken_filterへの自動フィルターIDマッピングによるDrupal 7からDrupal 10/11への移行サポート
- テキストフォーマットヘルプページでToken Browserへのリンクと共に利用可能なトークンを表示するFilter tips統合
Use Cases
コンテンツ内の動的サイト情報
ページコンテンツ内でサイト名、スローガン、URLを動的に表示します。例えば、「[site:name] © [current-date:custom:Y]」を含むフッターブロックを作成すると、年が自動更新され、サイト名の変更も反映されます。
記事での著者表示
「[node:author:display-name]」や「[node:created:medium]」などのEntityトークンを使用して、記事テンプレートに著者情報を含め、コンテンツの作成者と作成日時を自動的に表示します。
パーソナライズされたユーザーメッセージ
「おかえりなさい、[current-user:display-name]さん！」のような現在のユーザートークンを使用して、ブロックやページにウェルカムメッセージやユーザー固有のコンテンツを作成します。
一貫性のある相互参照コンテンツ
「[node:title]」や「[node:url:absolute]」などを使用してコンテンツ内で現在のページのプロパティを参照し、コンテンツの名前が変更された場合に自動更新される自己参照リンクやメタデータを作成します。
Token Browserを使用したテンプレートベースのコンテンツ
コンテンツ編集者はCKEditorのToken Browserボタンを使用して、トークン構文を覚えることなく利用可能なトークンを簡単に挿入できます。ブラウザはタイプ別に整理されたすべての利用可能なトークンを説明付きで表示します。
Drupal 7からの移行
filter_tokensフィルターを使用していたDrupal 7からの移行サイトは、テキストフォーマット設定が自動的にtoken_filterを使用するように更新され、トークン置換機能が保持されます。
Tips
- [site:name]、[current-date:*]、[current-user:*]などのグローバルトークンは、コンテキストに関係なくどこでも機能するコンテンツに使用してください。
- [node:*]などのEntityトークンは、token filterがそのEntityがレンダリングされるコンテキストでコンテンツを処理する場合にのみ機能します。
- 残りのトークンプレースホルダーのないクリーンな出力が必要な場合は「Replace empty values」を有効にしますが、開発中は誤設定されたトークンを見つけやすくするために無効にしてください。
- CKEditor 5のToken Browserはクリックで挿入機能をサポートしています - ブラウザでトークンをクリックするだけでカーソル位置に挿入されます。
- パフォーマンス向上のため、トークンフィルターをフィルター処理順序の早い位置に配置することを検討してください。トークンが他のフィルターのコンテンツ処理に影響する可能性があるためです。
- トークンの値はコンテンツ保存時ではなくレンダリング時に置換されるため、[current-date:*]のような動的トークンは常に現在の値を表示します。
Technical Details
Admin Pages 1
/admin/config/content/formats/manage/{format}
テキストフォーマットを編集する際、Token Filter設定がフィルター設定セクションに表示されます。ここでトークン置換フィルターを有効にし、その動作を設定します。
Hooks 2
hook_preprocess_field
トークン置換のための現在のEntityコンテキストを設定します。Fieldがレンダリングされる際、このhookは親Entityをキャプチャし、トークンフィルターが処理中にEntity固有のトークンにアクセスできるようにstatic変数に格納します。
hook_migration_plugins_alter
d7_filter_format移行時にDrupal 7のfilter_tokensフィルターIDをDrupal 10/11のtoken_filter IDにマッピングするために移行プラグインを変更します。
Troubleshooting 5
使用しているテキストフォーマットで「Replaces global and entity tokens with their values」フィルターが有効になっていることを確認してください。コンテンツフィールドがそのテキストフォーマットを使用していることも確認してください。
Entityトークンはレンダリングされたentity fieldのコンテキストでのみ機能します。Entityがレンダリングされていないブロックやその他のコンテキストでは機能しません。Entity以外のコンテキストではグローバルトークンを使用してください。
テキストフォーマット設定を編集し、CKEditor 5ツールバーに「Token browser」ボタンを追加してください。Token FilterとTokenモジュールの両方が有効になっていることを確認してください。
これは「Replace empty values」が無効になっている場合の期待される動作です。解決できないトークンを出力から削除したい場合は、フィルター設定でこのオプションを有効にしてください。
Token Browser CKEditor 5プラグイン設定を構成して、表示するトークンタイプを制限してください。テキストフォーマットを編集し、Token Browser設定で特定のトークンタイプを選択してください。
Security Notes 3
- Token FilterはTYPE_TRANSFORM_IRREVERSIBLEフィルタータイプを使用しており、変換は元に戻せません - 元のトークンプレースホルダーは出力で置換されます。
- このモジュールは公式のDrupalセキュリティアドバイザリーカバレッジを持ち、セキュリティのベストプラクティスに従っていることを示しています。
- トークン置換はBubbleableMetadataを介した適切なcacheメタデータ処理でレンダリング中に行われ、トークンの値が変更された際にキャッシュされたコンテンツが適切に無効化されます。