Paragraphs Entity Embed
Paragraph Entity を CKEditor WYSIWYG エディタフィールドに直接埋め込むことができます。
paragraphs_entity_embed
インストール
composer require 'drupal/paragraphs_entity_embed:^3.0'
概要
Paragraphs Entity Embed は、Paragraphs モジュールと CKEditor の橋渡しをし、コンテンツ編集者がリッチで構造化された Paragraph コンテンツをテキストエディタフィールド内に直接挿入できるようにします。このモジュールは、ユーザーが新しい Paragraph アイテムを作成するか、既存のものを WYSIWYG コンテンツ内で再利用できるシームレスなワークフローを実現します。
このモジュールは、Paragraph 参照のコンテナとして機能する「Embedded Paragraphs」というカスタム Entity タイプを提供します。ユーザーが CKEditor の Paragraphs ボタンをクリックすると、モーダルダイアログが開き、新しい Paragraph を作成するか、オートコンプリートで既存の埋め込み Paragraph を選択できます。埋め込まれた Paragraph は、特別な「embed」ビューモードを使用してテキストコンテンツ内にインラインでレンダリングされます。
このアプローチは、一貫性のある再利用可能なコンテンツコンポーネントを維持しながら、専用の Paragraph フィールドだけでなく本文テキスト内のどこにでも配置できる柔軟性を編集者に提供したいサイトに特に有用です。
Features
- WYSIWYG コンテンツに Paragraph を挿入するための専用ツールバーボタンを備えた CKEditor 統合
- 新しい Paragraph の作成または既存の埋め込み Paragraph の選択のためのモーダルダイアログインターフェース
- 以前に作成した埋め込み Paragraph を素早く検索して再利用するためのオートコンプリート機能
- 簡単に識別できるラベル付きの Paragraph 参照を保存するカスタム「Embedded Paragraphs」Entity タイプ
- コンテンツ表示時に埋め込み Paragraph を処理してレンダリングする Filter プラグイン
- 特定の埋め込みボタンで埋め込み可能な Paragraph タイプを制限する Paragraph タイプフィルタリング
- CKEditor で埋め込み Paragraph を素早く編集するためのダブルクリック編集サポート
- 埋め込み Paragraph を編集するための CKEditor コンテキストメニュー統合
- 埋め込み時の Paragraph の表示方法を制御する専用の「embed」ビューモード
- 埋め込み Paragraph 参照を管理するための標準 Paragraphs ウィジェットを拡張したフィールドウィジェット
Use Cases
記事テキスト内への CTA ブロックの埋め込み
コンテンツ編集者は、再利用可能な CTA（Call-to-Action）Paragraph コンポーネント（ボタン、画像、スタイル付きテキストを含む）を作成し、コンテンツの上部や下部だけでなく、記事本文テキスト内の任意の場所に挿入できます。
ブログ投稿への商品ハイライトの挿入
EC サイトでは、商品ティーザー Paragraph を定義し、ブログ著者が投稿コンテンツ内に商品ハイライトを直接埋め込むことができ、シームレスな読書体験を実現します。
複数ページにわたるお客様の声の再利用
お客様の声 Paragraph を一度作成し、複数のコンテンツで埋め込みます。オートコンプリート機能により、既存のお客様の声を再作成することなく簡単に見つけて再利用できます。
長文コンテンツへのインタラクティブ要素の追加
アコーディオン、タブ、メディアギャラリーなどの複雑な Paragraph タイプを持つサイトでは、編集者は固定フィールドの位置に制限されることなく、テキストコンテンツ内のどこにでもこれらのインタラクティブ要素を埋め込むことができます。
Tips
- 各 Paragraph タイプに専用の「Embed」ビューモードを作成し、テキストコンテンツ内のインライン表示に適したフィールドの表示とフォーマットを設定してください
- 埋め込み Paragraph を作成する際は説明的なラベルを使用し、再利用時にオートコンプリートで簡単に見つけられるようにしてください
- 適切な Paragraph 埋め込みパーミッションを持つコンテンツ編集者ロールを作成し、埋め込み Paragraph を作成・管理できるユーザーを制御することを検討してください
- デフォルトビューモードと Embed ビューモードの両方で埋め込み Paragraph のレンダリングをテストし、一貫したスタイリングを確保してください
Technical Details
Admin Pages 2
/admin/config/content/embed
Paragraphs 埋め込みボタンを含む埋め込みボタンを管理します。Paragraphs ボタンはモジュールのインストール時に自動的に作成され、ここで設定できます。
/admin/structure/paragraphs_entity_embed/{paragraphs_type}
埋め込み Paragraph Entity を直接編集するための管理インターフェース。
権限 5
Hooks 2
hook_entity_type_build
CKEditor ダイアログフォームを処理するためのカスタムフォームクラスを embedded_paragraphs Entity タイプに追加します
hook_preprocess_html
CKEditor ダイアログ内の iframe で Paragraph 埋め込みフォームを表示する際に、ページ要素（ツールバー、フッター、サイドバー）を非表示にします
Troubleshooting 4
テキストフォーマットのツールバー設定に Paragraphs ボタンが追加されていることを確認してください。環境設定 > テキストフォーマットとエディターに移動し、フォーマットを編集して、Paragraphs ボタンをアクティブなツールバーにドラッグしてください。
テキストフォーマットで「Display embedded paragraphs」フィルターを有効にしてください。また、フィルターの順序が正しいことを確認してください - Entity Embed フィルターは通常、HTML 補正の後に実行する必要があります。
Paragraph タイプが作成されていること、および埋め込みボタンが空の選択に Paragraph タイプをフィルタリングするように設定されていないことを確認してください。
サイト構築 > Paragraphs タイプ > [タイプ] > 表示管理で、Paragraph タイプの「Embed」ビューモードを設定してください。「Embed」ビューモードを選択し、表示するフィールドを設定してください。
Security Notes 3
- 「administer paragraphs entity embed」パーミッションは制限付きとしてマークされており、信頼できる管理者にのみ付与してください
- ユーザーが埋め込み Paragraph を挿入するには、テキストフォーマットへのアクセスと適切な Paragraph 埋め込みパーミッションの両方が必要です
- 埋め込み Paragraph コンテンツは、親コンテンツタイプと同じアクセス制御の対象となります