Entity Embed
CKEditorと設定可能な表示オプションを使用して、テキストコンテンツ内に任意のEntityを埋め込むことができます。
entity_embed
インストール
composer require 'drupal/entity_embed:8.x-1.7'
composer require 'drupal/entity_embed:8.x-1.6'
概要
Entity Embedは、コンテンツ編集者がCKEditor WYSIWYGエディタを使用して、任意のEntity（Node、Media、File、User、Taxonomy Termなど）をテキストコンテンツに直接埋め込むことができる強力なDrupalモジュールです。このモジュールは、Drupalのテキストフィルタリングシステムを拡張し、フォーマットされたテキストフィールド内の埋め込みEntityを認識してレンダリングします。
このモジュールは、埋め込みEntityの表示方法を制御するための柔軟なプラグインシステムを提供し、さまざまなField FormatterやView Modeをサポートしています。DrupalのFilterおよびEditorシステムとシームレスに統合され、管理者がどのEntityを埋め込み可能にし、コンテンツ内でどのように表示するかを設定できます。
Entity EmbedはCKEditor 4（非推奨）とCKEditor 5の両方をサポートし、Entity Browserとの統合による高度なEntity選択機能を提供し、カスタマイズ用の包括的なHook APIを含んでいます。このモジュールは、Entityの翻訳、配置オプション、キャプション、および再帰的レンダリング保護を処理します。
Features
- CKEditorを使用して、リッチテキストコンテンツ内に任意のDrupal Entity（Node、Media、File、User、Taxonomy Termなど）を埋め込み可能
- 設定された各埋め込みボタンに専用のツールバーボタンを持つCKEditor 5のサポート
- Field FormatterまたはView Modeを使用してEntityをレンダリングできる複数のDisplay Pluginシステム
- オートコンプリートの代わりにビジュアルなEntity選択を可能にするEntity Browserとの統合
- Drupalのfilter_alignフィルタと併用した場合の配置サポート（左、中央、右）
- Drupalのfilter_captionフィルタと併用した場合の埋め込みEntityへのキャプションサポート
- data-langcode属性による言語コードトラッキングを使用した翻訳対応の埋め込み
- 埋め込み可能なコンテンツタイプを制限する設定可能なBundle制限
- 利用可能な表示オプションを制御するボタンごとのDisplay Plugin制限
- アクセシビリティのためのMedia画像のaltおよびtitleテキストのオーバーライド機能
- 設定可能な深度制限（デフォルト20）を持つ再帰的レンダリング保護
- テンプレートでのプログラマティックな埋め込み用にentity_embed()関数を提供するTwig拡張
- Display Plugin、コンテキスト、およびビルド出力を変更するための包括的なHook API
- レガシーのdata-view-mode属性から新しいDisplay Plugin形式への自動マイグレーション
Use Cases
本文コンテンツへのMedia埋め込み
コンテンツ編集者は、記事の本文フィールドにMedia Entity（画像、動画、ドキュメント）を直接埋め込むことができます。CKEditorのEntity埋め込みボタンをクリックし、Mediaアイテムを検索して選択し、表示形式（サムネイル、フルなど）を選択し、オプションで配置とキャプションを追加してから埋め込みます。Mediaはテキストコンテンツと一緒にインラインでレンダリングされます。
関連コンテンツのインライン参照
本文コンテンツ内に他のNodeへの参照を埋め込んで、豊かで相互接続されたコンテンツを作成します。例えば、ブログ投稿内に商品Nodeをティーザー表示で埋め込み、記事を離れることなく商品詳細をインラインで表示します。
再利用可能なコンテンツブロックの構築
一般的なコンテンツスニペット（吹き出し、著者プロフィール、プロモーションバナー）用のBlock Content Entityを作成し、複数のページに埋め込みます。Block Entityへの変更は、埋め込まれているすべての場所に自動的に反映されます。
カスタムEntityの埋め込み
Contribまたはカスタムモジュールで作成されたカスタムEntity（イベント、場所、チームメンバー）を埋め込みます。カスタムEntity Type用の埋め込みボタンを設定し、表示用の適切なView Modeを選択します。
Entity BrowserによるビジュアルなEntity選択
オートコンプリートの代わりにビジュアルなギャラリースタイルの選択インターフェースを使用するようにEntity Browserを使用する埋め込みボタンを設定します。編集者が選択前にコンテンツを閲覧してプレビューする必要があるMedia中心のサイトに便利です。
テンプレートでのプログラマティックな埋め込み
entity_embed() Twig関数を使用して、エディタの操作なしにテンプレートにEntityを埋め込みます: {{ entity_embed('node', 123, 'entity_reference:entity_reference_entity_view', {view_mode: 'teaser'}) }}
Tips
- 異なるEntity Type用に別々の埋め込みボタンを設定して（Media用に1つ、Node用に1つ）、ツールバーを整理し、編集者の選択範囲を制限します
- 埋め込みボタンにBundle制限を使用して、編集者が不適切なコンテンツタイプを埋め込むのを防ぎます（例: ブログ埋め込みボタンは「記事」Nodeのみに制限）
- Entity Browser設定でレビューステップを有効にして、表示オプションを設定する前に編集者が選択を確認できるようにします
- entity_embed.settingsのrendered_entity_mode設定は、View ModeをトップレベルでDisplay Pluginドロップダウンを簡素化できます
- Media画像のaltおよびtitleテキストのオーバーライドは、特別な値'""'（2つのダブルクォート）を使用して明示的に空のaltテキストを設定し、Mediaのaltテキストを継承することと区別します
- hook_entity_embed_display_plugins_for_context_alterを使用して、埋め込まれている特定のEntityに基づいて利用可能な表示オプションを動的にフィルタリングします
- 埋め込みEntityは、ターゲットを絞ったスタイリング用に「embedded-entity」CSSクラスでレンダリングされます
Technical Details
Admin Pages 3
/admin/config/content/embed
Entity埋め込みボタンを含むすべての設定済み埋め込みボタンを一覧表示します。ここからCKEditorツールバーに表示される埋め込みボタンを追加、編集、または削除できます。
/admin/config/content/embed/add
テキストコンテンツにEntityを埋め込むための新しい埋め込みボタンを作成します。このフォームでは、Entity Type、Bundle制限、Display Plugin、およびオプションのEntity Browser統合を設定できます。
/admin/config/content/formats/manage/{format_id}
Entity EmbedフィルタとCKEditorボタン配置を含むテキストフォーマット設定を構成します。
Hooks 7
hook_entity_embed_display_plugins_alter
Entity Embed Display Pluginの定義をグローバルに変更します。Display Plugin定義を修正、追加、または削除するために使用します。
hook_entity_embed_display_plugins_for_context_alter
コンテキストに基づいてEntity Embed Display Pluginをフィルタリングします。特定のEntityや埋め込みボタンで利用できないようにすべきPluginを削除するために使用します。
hook_entity_embed_context_alter
埋め込みEntityがレンダリングされる前にコンテキスト配列を変更します。Display Pluginに渡されるコンテキスト値の変更を可能にします。
hook_ENTITY_TYPE_embed_context_alter
hook_entity_embed_context_alterのEntity Type固有のバリアント。ENTITY_TYPEをEntity Typeのマシン名に置き換えます（例: hook_node_embed_context_alter）。
hook_entity_embed_alter
埋め込みEntityが構築された後のRender Arrayを変更します。これはDisplay PluginがBuild Arrayを生成した後に呼び出されます。
hook_ENTITY_TYPE_embed_alter
hook_entity_embed_alterのEntity Type固有のバリアント。ENTITY_TYPEをEntity Typeのマシン名に置き換えます。
hook_entity_embed_values_alter
値がWYSIWYGエディタに送信される前に変更します。埋め込みダイアログフォームの送信時に呼び出されます。
Troubleshooting 7
テキストフォーマットで「Display embedded entities」フィルタが有効になっていることと、テキストフォーマット設定でCKEditorツールバーに埋め込みボタンが追加されていることを確認してください。
entity_embedフィルタが有効になっていないか、処理されていません。テキストフォーマットで「Display embedded entities」フィルタを有効にしてください。フィルタ処理順序を確認してください - entity_embedはfilter_align、filter_caption、filter_html_image_secureの後に実行する必要があります。
「Limit allowed HTML tags」フィルタを使用している場合、必要なすべての属性を持つdrupal-entityタグがホワイトリストに登録されていることを確認してください: data-entity-type、data-entity-uuid、data-entity-embed-display、data-entity-embed-display-settings、data-align、data-caption、data-embed-button、alt、title。
Entity Typeに互換性のあるEntity Embed Display Pluginがないか、埋め込みボタン設定で利用可能なPluginが制限されている可能性があります。埋め込みボタン設定を確認し、Entity TypeにView Modeまたは互換性のあるField Formatterがあることを確認してください。
互換性のあるDisplay Pluginを持つEntity Browserインスタンスのみが利用可能です。「modal」または「standalone」ディスプレイを使用するBrowserはフィルタリングされます。「iframe」または他の互換性のあるディスプレイを持つEntity Browserを作成または設定してください。
現在のユーザーが埋め込みEntityの表示権限を持っていないか、Entityが削除されている可能性があります。Entity権限を確認し、Entityがまだ存在することを確認してください。
Entityが自身の埋め込みを含んでいるか、循環参照チェーンを作成しています。このモジュールには組み込みの保護（制限: 20回の再帰）がありますが、コンテンツを確認して循環埋め込みを削除する必要があります。
Security Notes 5
- Entity埋め込みはDrupalのEntityアクセスシステムを尊重します - 現在のユーザーが表示権限を持っている場合にのみEntityがレンダリングされます
- フィルタは欠落または削除されたEntityを適切に処理し、エラーの代わりにプレースホルダーを表示します
- キャプション内のHTMLはXSS攻撃を防ぐために保存前にエスケープされます
- コンテンツのステージングとマイグレーションの問題を防ぐために、埋め込みにはEntity IDよりもEntity UUIDが優先されます
- このモジュールは、エディタダイアログとフィルタ処理の両方で埋め込みEntityが存在し、アクセス可能であることを検証します