Custom Tokens
サイト管理者がユーザー定義のコンテンツを持つカスタムトークンを作成し、Token APIを通じてDrupalサイト全体で使用できるようにします。
token_custom
インストール
composer require 'drupal/token_custom:8.x-1.0'
概要
Custom Tokensモジュールは、Drupal内でカスタムトークンを作成・管理するための完全な管理インターフェースを提供します。トークンは処理時に動的なコンテンツに置換される再利用可能なプレースホルダーであり、このモジュールはコードを書くことなくユーザーが独自のカスタムトークンを定義できるようにToken APIを拡張します。
カスタムトークンはタイプ（カテゴリ）に整理され、関連するトークンを論理的にグループ化できます。各トークンには、フィルター済みHTMLを含むサイトで利用可能な任意のテキストフォーマットをサポートするフォーマット済みテキストコンテンツが含まれます。モジュールは翻訳を完全にサポートしており、トークン名、説明、コンテンツを複数の言語に翻訳できます。
カスタムトークンがトークン置換をサポートするコンテンツや設定フィールドで使用されると、モジュールは自動的にトークンプレースホルダーを定義されたコンテンツに置換します。これにより、再利用可能なテキストスニペット、連絡先情報、法的免責事項、または複数の場所で一貫して表示する必要があるその他のコンテンツの管理に最適です。
Features
- トークンを論理的に整理するためのカスタムトークンタイプ（カテゴリ）を作成
- トークン対応フィールドで使用するためのマシン名を持つカスタムトークンを定義
- 利用可能な任意のテキストフォーマット（プレーンテキスト、Basic HTML、Full HTMLなど）を使用したフォーマット済みテキストコンテンツのサポート
- Drupalの翻訳システムを通じたトークンの説明とコンテンツの完全な翻訳サポート
- hook_token_info()とhook_tokens()を介したDrupalのToken APIとの自動統合
- トークンの作成、更新、削除時に自動的にキャッシュを無効化するキャッシュ対応実装
- トークンとトークンタイプの表示、作成、編集、削除に対するパーミッションベースのアクセス制御
- トークンとタイプを管理するための操作を備えた管理一覧ページ
- 既存のトークンが使用しているトークンタイプの削除を防止
Use Cases
再利用可能な連絡先情報
住所、電話番号、メールアドレスなどの会社の連絡先詳細用のトークンを作成します。[custom:company-address]や[custom:support-email]などのトークンをサイト全体で使用します。連絡先情報が変更された場合、1か所でトークンを更新するだけで、すべての場所で自動的に更新されます。
法的免責事項とボイラープレートテキスト
法的免責事項、著作権表示、または利用規約のスニペットをトークンとして保存します。[custom:copyright-notice]や[custom:privacy-disclaimer]をコンテンツタイプ、ブロック、またはメールテンプレートに挿入して、サイト全体で一貫した法的テキストを確保します。
動的コンテンツスニペット
プロモーションメッセージ、季節の挨拶、キャンペーンコードなど、頻繁に変更されるコンテンツ用のトークンを作成します。コンテンツ編集者は、トークンが表示されるページに触れることなく[custom:promo-message]トークンのコンテンツを更新できます。
多言語コンテンツトークン
多言語サイトでは、各言語に翻訳されたコンテンツを持つトークンを作成します。モジュールは現在の言語コンテキストに基づいて正しい翻訳を自動的に提供し、[custom:welcome-message]が英語、スペイン語、フランス語などで適切に表示されることを保証します。
整理されたトークンカテゴリ
目的別にトークンを整理するカスタムトークンタイプを作成します：ビジネス情報用の「company」（[company:address]、[company:hours]）、法的テキスト用の「legal」（[legal:terms]、[legal:privacy]）、マーケティング用の「promo」（[promo:current-offer]）。これによりトークンブラウザでの発見性が向上します。
メールテンプレート変数
WebformやCommerceなどのモジュールで設定されたメールテンプレートでカスタムトークンを使用します。[custom:email-footer]や[custom:support-hours]などのトークンは、すべてのメール通信で一貫して使用でき、中央で更新できます。
Tips
- トークンの目的を示す説明的なマシン名を使用してください。例えば「phone1」ではなく「company-phone」のように
- トークンを論理的に整理するために複数のトークンタイプを作成してください。例えば、「contact」、「legal」、「marketing」コンテンツ用に別々のタイプを作成
- トークンコンテンツはテキストフォーマットをサポートしているため、フォーマットされたHTML、リンク、その他のリッチコンテンツを含めることができます
- Tokenモジュールは利用可能なすべてのカスタムトークンを表示するトークンブラウザを提供しています。トークンをサポートするフィールドからアクセスできます
- トークンのコンテンツを更新すると、キャッシュクリア後すぐに変更が反映されます。そのトークンを使用しているコンテンツを再保存する必要はありません
- カスタムトークンは、Pathautoパターン、Metatag値、Webformメールなど、Tokenモジュールが統合されている場所であればどこでも機能します
- 多言語サイトでは、標準の翻訳ワークフローを通じてトークンコンテンツを翻訳し、言語間で一貫したメッセージングを維持してください
Technical Details
Admin Pages 8
/admin/structure/token-custom
サイトで定義されたすべてのカスタムトークンを一覧表示します。このページから既存のトークンを表示、編集、削除したり、新しいトークンを追加できます。一覧には各トークンのマシン名、タイプ、名前、説明、生のコンテンツが表示されます。
/admin/structure/token-custom/add
新しいカスタムトークンを作成します。複数のトークンタイプが存在する場合は、まずトークンが属するタイプを選択します。トークンは[type:machine-name]の形式でトークン対応フィールドで使用できます。
/admin/structure/token-custom/manage/{token_custom}/edit
既存のカスタムトークンを編集します。マシン名は既存のトークン参照の破損を防ぐため、作成後は変更できません。
/admin/structure/token-custom/manage/{token_custom}/delete
カスタムトークンを削除するための確認ページ。トークンを削除すると、そのトークンを使用しているコンテンツは置換コンテンツではなく生のトークンプレースホルダーが表示されます。
/admin/structure/token-custom/type
サイトで定義されたすべてのカスタムトークンタイプ（カテゴリ）を一覧表示します。トークンタイプはトークンを整理するための名前空間を提供します。デフォルトの「Custom」タイプがインストール時に提供されます。
/admin/structure/token-custom/type/add
カスタムトークンを整理するための新しいトークンタイプを作成します。マシン名はトークンの名前空間プレフィックスになります。例えば、マシン名「company」でタイプを作成すると、[company:address]のようなトークンが使用可能になります。
/admin/structure/token-custom/type/manage/{token_custom_type}/edit
既存のトークンタイプの名前と説明を編集します。マシン名は作成後は変更できません。
/admin/structure/token-custom/type/manage/{token_custom_type}/delete
トークンタイプを削除するための確認ページ。トークンが割り当てられているタイプは削除できません。まずそのタイプを使用しているすべてのトークンを削除するか、別のタイプに再割り当てしてからタイプを削除する必要があります。
権限 3
Hooks 2
hook_token_info
カスタムトークンタイプとトークンをToken APIに登録します。このhookは、すべてのTokenCustomTypeエンティティをトークンタイプとして、すべてのTokenCustomエンティティをそれぞれのタイプ内の利用可能なトークンとして公開するために実装されています。
hook_tokens
カスタムトークンの実際の置換値を提供します。トークンが置換される際、このhookは対応するTokenCustomエンティティを読み込み、フォーマット済みコンテンツを返します。翻訳を処理し、適切なキャッシュメタデータを追加します。
Troubleshooting 5
drush crまたは管理 > 環境設定 > パフォーマンス > すべてのキャッシュをクリアを使用してすべてのキャッシュをクリアします。トークンのマシン名が正確に一致していることを確認してください（大文字小文字を区別）。フィールドまたはコンテキストがトークン置換をサポートしていることを確認してください。
トークンが属しているトークンタイプは削除できません。まずそのタイプを使用しているすべてのトークンを削除するか、トークンを編集して別のタイプに割り当ててから、タイプを削除してください。
サイトキャッシュと静的トークンキャッシュをクリアしてください。モジュールはキャッシュ無効化を実装していますが、手動でのキャッシュクリアが必要な場合があります。トークンタイプとトークンの両方が有効になっていることを確認してください。
トークンコンテンツに正しいテキストフォーマットが選択されていることを確認してください。トークンが「Plain text」フォーマットで作成された場合、HTMLはエスケープされます。トークンを編集し、「Basic HTML」や「Full HTML」などの適切なフォーマットを選択してください。
トークンを作成するには、少なくとも1つのトークンタイプが存在する必要があります。デフォルトの「Custom」タイプが削除された場合は、まず管理 > サイト構築 > Custom tokens > Custom Token Types > Add Token Typeで新しいトークンタイプを作成してください。
Security Notes 4
- 「administer custom tokens」パーミッションは、トークンにサイトでレンダリングされるHTMLコンテンツを含めることができるため、制限付きとしてマークされています。このパーミッションは信頼できるロールにのみ付与してください。
- トークンコンテンツはテキストフォーマットのパーミッションを尊重します。トークンを作成するユーザーは、アクセス権があるテキストフォーマットのみを使用できます。
- トークンに保存するコンテンツには注意してください。トークンが使用される場所によっては、匿名ユーザーに表示される可能性があります。
- 「administer custom token types」パーミッションは、サイト上のすべてのカスタムトークンの整理に影響するため、制限付きです。