Embedded Content

HTML権限を必要とせずに、エディターがリッチテキストコンテンツ内にスタイル付きの設定可能なコンポーネントを挿入できるCKEditor 5プラグインシステムを提供します。

embedded_content
1,121 sites
26
drupal.org
gui api field
ckeditor5 wysiwyg editor content embed components plugins rich text
Drupal 9 Drupal 10 Drupal 11

インストール

Drupal 11, 10, 9 v2.0.3
composer require 'drupal/embedded_content:^2.0'

概要

Embedded Contentは、CKEditor 5内にカスタムコンポーネントを埋め込むための柔軟なシステムを提供することで、コンテンツエディターと開発者の間のギャップを埋める強力なモジュールです。エディターは直感的なツールバーボタンを通じて事前設定されたスタイル付きコンポーネントを挿入でき、開発者はどのコンポーネントを利用可能にし、どのようにレンダリングするかを完全に制御できます。

このモジュールは、開発者が設定フォームとレンダリングロジックを定義するEmbeddedContentプラグインを作成するプラグインアーキテクチャを使用します。これらのプラグインは、任意のCKEditor 5テキストフォーマットに追加できる設定可能なツールバーボタンを通じて利用可能になります。コンテンツが保存されると、モジュールはコンポーネントデータをカスタムHTML要素（<embedded-content>）として保存し、テキストフィルターによって処理されて最終出力がレンダリングされます。

主な利点：エディターはスタイル付きコンポーネントを使用するために「Full HTML」権限を必要としない、開発者は複雑なインタラクティブ要素を作成できる、CKEditor 5統合により編集中に埋め込みコンテンツの即時ビジュアルプレビューが提供される。

Features

  • スタイル付きコンポーネントを埋め込むためのカスタムツールバーボタンを備えたCKEditor 5統合
  • 設定可能なフォームとレンダリングロジックを持つカスタム埋め込みコンテンツタイプを作成するための開発者向けプラグインシステム
  • <embedded-content>および<embedded-content-inline>タグをレンダリングされたHTMLに処理するテキストフィルター
  • カスタムアイコン、ラベル、ダイアログ設定を持つ埋め込みコンテンツボタンを管理するための管理UI
  • ブロックレベルとインライン埋め込みコンテンツの両方をサポート
  • 幅、高さ、レンダラータイプ（モーダルまたはオフキャンバス）を含む設定可能なダイアログ/モーダル設定
  • ツールバーボタン用のSVGアイコンカスタマイズ
  • ワイルドカードパターンと正規表現条件を使用したプラグインフィルタリング
  • 設定された各ボタンに対する動的な権限生成
  • CKEditor 5エディター内での埋め込みコンテンツのライブプレビュー
  • ウィジェットツールバーを通じた既存の埋め込みコンテンツの編集機能

Use Cases

コールアウトボックスとアラート

エディターがカスタムテキスト付きのスタイル付きコールアウトボックス（情報、警告、成功、エラー）を挿入できるEmbeddedContentプラグインを作成します。エディターがタイプを選択してコンテンツを入力すると、モジュールはCSSクラス権限を必要とせずに一貫したスタイルのアラートボックスをレンダリングします。

ソーシャルメディア埋め込み

エディターがソーシャルメディアのURLを貼り付けると、埋め込み投稿としてレンダリングされるプラグインを構築します。設定フォームがURLを検証し、buildメソッドが適切なスタイリングを持つ埋め込みコードを出力します。

データ可視化ウィジェット

チャート、テーブル、その他のデータ可視化用のプラグインを作成します。エディターがフォームを通じてデータを設定し、プラグインがJavaScriptライブラリを使用してインタラクティブなチャートをレンダリングします。すべて直接HTMLアクセスなしで可能です。

商品またはコンテンツ参照

エディターが商品カード、記事ティーザー、その他のエンティティ参照をカスタム表示オプション付きで検索・埋め込みできるプラグインを構築します。生のエンティティ埋め込みよりもガイド付きのエクスペリエンスを提供します。

インタラクティブコンポーネント

アコーディオン、タブ、その他のインタラクティブUIコンポーネント用のプラグインを開発します。エディターがフォームを通じてセクションを設定し、モジュールが関連するJavaScriptビヘイビアを持つ適切なHTML構造を出力します。

シンタックスハイライト付きコードスニペット

設定フォームでコードエディターを提供し、エディターがコードを貼り付けて言語を選択できるプラグインを作成します。buildメソッドがPrismやHighlight.jsなどのライブラリを使用してシンタックスハイライトされたコードブロックを出力します。

Tips

  • 異なるコンテンツタイプまたはユーザーロール用に別々のボタンを作成して、異なるエディターに利用可能なプラグインを制御できます
  • より邪魔にならない編集エクスペリエンスのために、特にシンプルなプラグインにはオフキャンバスダイアログレンダラーを使用してください
  • プラグイン条件は、単純なワイルドカードを超えた複雑なマッチングシナリオ用の正規表現パターンをサポートしています
  • テキスト内に流れるインライン要素の場合、プラグインのisInline()メソッドを実装してtrueを返すようにしてください
  • フロントエンドレンダリングに必要なCSS/JSライブラリをアタッチするには、プラグインのgetAttachments()メソッドを使用してください
  • massageFormValues()メソッドにより、フォーム値を保存前に変換でき、クリーンアップや正規化に便利です
  • プラグインのbuild()メソッドでのキャッシュへの影響を考慮してください。特に動的またはユーザー固有のコンテンツをレンダリングするプラグインの場合に重要です

Technical Details

Admin Pages 5
Embedded content /admin/config/content/embedded-content

Embedded Contentモジュールのメイン管理ページ。ボタン設定へのアクセスを提供します。

Embedded content設定 /admin/config/content/embedded-content/button

設定されたすべての埋め込みコンテンツボタンを一覧表示します。各ボタンは、エディターが埋め込みコンテンツを挿入するために使用できるツールバーアイテムを表します。リストにはボタンのラベル、マシン名、ステータスが表示されます。

埋め込みコンテンツボタンを追加 /admin/config/content/embedded-content/button/add

CKEditor 5ツールバーに表示される新しい埋め込みコンテンツボタンを作成するフォーム。ボタンの外観、動作、アクセスできるプラグインを設定します。

埋め込みコンテンツボタンを編集 /admin/config/content/embedded-content/button/{embedded_content_button}

既存の埋め込みコンテンツボタン設定を編集します。追加フォームと同じフォームフィールドに加えて、アイコンプレビューセクションがあります。

埋め込みコンテンツボタンを削除 /admin/config/content/embedded-content/button/{embedded_content_button}/delete

埋め込みコンテンツボタンを削除するための確認フォーム。これにより、そのボタンを使用しているすべてのテキストフォーマットからツールバーボタンが削除されます。

権限 2
Embedded contentを管理

埋め込みコンテンツボタン設定の管理を許可します。ボタン管理ページにアクセスするために必要です。

[ボタンラベル] 埋め込みコンテンツボタンを使用

設定された各ボタンに対して動的に生成される権限。ユーザーが特定のツールバーボタンを使用して埋め込みコンテンツを挿入することを許可します。各ボタンに対して1つの権限が作成されます（例：「use default embedded content button」）。

Hooks 1
hook_embedded_content_info_alter

プラグインマネージャーによって検出された埋め込みコンテンツプラグイン定義をモジュールが変更できるようにします。

Troubleshooting 5
ダイアログに埋め込みコンテンツプラグインが表示されない

EmbeddedContentプラグインを提供するモジュールを有効にしていることを確認してください。コアモジュールにはデフォルトでプラグインが含まれていません。例としてembedded_content_testモジュールを有効にするか、カスタムモジュールで独自のプラグインを作成できます。

ツールバーボタンがCKEditor 5に表示されない

以下を確認してください：1) 埋め込みコンテンツボタンが/admin/config/content/embedded-content/buttonで設定されている、2) テキストフォーマット設定でボタンがツールバーにドラッグされている、3) そのテキストフォーマットで「Embedded Content」フィルターが有効になっている、4) ユーザーがその特定のボタンを使用する権限を持っている。

プラグインが利用可能なのにダイアログに表示されない

ボタン設定の「プラグイン条件」フィールドを確認してください。パターンが指定されている場合、プラグインIDはそのいずれかにマッチする必要があります。すべての利用可能なプラグインを表示するには、フィールドを空のままにしてください。

プレビューに「設定が正しくありません」エラーが表示される

埋め込みコンテンツが存在しなくなったか無効になったプラグインを参照している可能性があります。埋め込みコンテンツを削除し、有効なプラグインで再度挿入してください。

フロントエンドで埋め込みコンテンツがレンダリングされない

「Embedded Content」テキストフィルターがテキストフォーマットで有効になっており、正しい順序で配置されていることを確認してください。カスタムHTMLタグに干渉する可能性のあるフィルターの後、出力をサニタイズするフィルターの前に実行される必要があります。

Security Notes 3
  • 埋め込みコンテンツプラグインは、XSS攻撃を防ぐためにbuild()メソッドですべての設定値を検証およびサニタイズする必要があります
  • モジュールはプラグイン設定をデータ属性にJSONとして保存します。プラグインは検証なしにこのデータを信頼してはいけません
  • 特定のボタン権限を持つユーザーのみがそのツールバーボタンを使用でき、きめ細かいアクセス制御を提供します