Embed
CKEditor 4やCKEditor 5などのテキストエディタ内でさまざまな種類の埋め込みを実現するためのフレームワークを提供します。埋め込みタイププラグインを作成するためのAPIと、埋め込みボタンを管理するためのUIが含まれます。
embed
インストール
composer require 'drupal/embed:8.x-1.10'
composer require 'drupal/embed:8.x-1.9'
概要
Embedモジュールは、CKEditor 4やCKEditor 5などのWYSIWYGテキストエディタ内にさまざまな種類のコンテンツを埋め込むための基盤フレームワークを提供します。他のモジュールが拡張して特定の埋め込み機能を提供できるベースAPIとして機能します。
このモジュールは「埋め込みボタン」という概念を導入しています。これらのボタンはテキストエディタのツールバーに表示され、コンテンツ編集者が埋め込みコンテンツを挿入できるようにします。各ボタンは、どのような種類のコンテンツを埋め込めるか、どのように設定するかを定義する「埋め込みタイプ」プラグインに関連付けられています。
主な機能:
- カスタム埋め込みタイプを定義するためのプラグインシステム
- 埋め込みボタンを管理するための設定エンティティ
- CKEditor 4とCKEditor 5の完全な統合
- 埋め込みコンテンツのCSRF保護されたプレビューシステム
- CKEditor 5互換性のためのSVGサポート付きアイコン管理
- フィルター実装のためのDOM操作ユーティリティ
このモジュールは通常、特定の埋め込みタイプ実装を提供するEntity EmbedやMedia Embedなどのモジュールと組み合わせて使用されます。
Features
- さまざまな種類のコンテンツを埋め込める、カスタム埋め込みタイプを定義するためのプラグインベースのアーキテクチャ
- カスタムラベルとアイコンを持つ埋め込みボタンを作成・管理するための設定エンティティシステム
- 専用のプラグインベースを通じたCKEditor 4とCKEditor 5テキストエディタの両方との完全な統合
- 適切なフィルターフォーマットを使用して埋め込みコンテンツをレンダリングするCSRF保護されたプレビューエンドポイント
- base64エンコードデータとして保存されるカスタムアイコンをサポートするアイコン管理システム（CKEditor 5互換性のためSVGが必須）
- フィルタープラグインでDOM要素を操作するためのDOMヘルパーユーティリティ（DomHelperTrait）
- エディター設定での埋め込みボタンの利用可否を検証するアクセス制御システム
- エディターインスタンスに埋め込みコンテンツを挿入するためのAJAXコマンドシステム
- 埋め込みボタン設定からの自動CKEditor 5プラグイン派生
Use Cases
Entity Embedボタンの作成
'entity'埋め込みタイプを提供するEntity Embedモジュールをインストールします。管理 > 環境設定 > コンテンツオーサリング > 埋め込みボタン に移動します。「埋め込みボタンを追加」をクリックし、「Node」のようなラベルを入力し、埋め込みタイプとして「Entity」を選択し、埋め込み可能なエンティティタイプとバンドルを設定し、SVGアイコンをアップロードして保存します。その後、テキストフォーマットを編集してCKEditor 5ツールバーにボタンを追加し、必要なフィルターを有効にします。
カスタム埋め込みタイプの開発
モジュールのsrc/Plugin/EmbedTypeディレクトリにプラグインを実装してカスタム埋め込みタイプを作成します。EmbedTypeBaseを拡張し、idとlabelを持つ@EmbedTypeアノテーションを追加します。getDefaultIconUrl()を実装してデフォルトのボタンアイコンを提供します。オプションでbuildConfigurationForm()、validateConfigurationForm()、submitConfigurationForm()をオーバーライドしてボタン固有の設定を追加します。CKEditor 5統合のために、EmbedCKEditor5PluginBaseを拡張したCKEditor 5プラグインを作成します。
埋め込みコンテンツのプレビュー
このモジュールは/embed/preview/{filter_format}にプレビューエンドポイントを提供し、埋め込みコンテンツをレンダリングします。CKEditorプラグインはCSRF保護付きでこのエンドポイントを使用し、編集中に埋め込みアイテムのライブプレビューを表示します。プレビューは最終的にレンダリングされるコンテンツと同じフィルター処理を使用します。
Tips
- CKEditor 5互換性を確保するために、埋め込みボタンには常にSVGアイコンを使用してください
- Embedモジュールはフレームワークです - 実際の埋め込み機能にはEntity Embedや類似のモジュールをインストールしてください
- カスタム埋め込みタイプを開発する際は、適切なデフォルトのためにEmbedTypeBaseを拡張してください
- 埋め込みコンテンツを処理するフィルタープラグインを実装する際は、DomHelperTraitユーティリティメソッドを使用してください
- 埋め込みボタンは設定エンティティであり、設定管理でエクスポート/インポートできます
- このモジュールは、ボタンがエディターツールバーに追加される際に必要なフィルターが有効になっていることを検証します
Technical Details
Admin Pages 4
/admin/config/content/embed
設定済みのすべての埋め込みボタンをラベル、埋め込みタイプ、アイコンとともに一覧表示します。各ボタンの編集・削除操作を提供します。これは埋め込みボタンのメイン管理インターフェースです。
/admin/config/content/embed/button/add
新しい埋め込みボタンを作成するためのフォーム。ボタンラベル、マシン名、埋め込みタイプ、タイプ固有の設定、カスタムアイコンを設定できます。
/admin/config/content/embed/button/manage/{embed_button}
既存の埋め込みボタンを編集するためのフォーム。マシン名と埋め込みタイプは作成後に変更できません。
/admin/config/content/embed/settings
アップロードされたボタンアイコンの保存場所を制御するEmbedモジュールのグローバル設定。
権限 1
Hooks 1
hook_embed_type_plugins_alter
モジュールが検出後の埋め込みタイププラグイン定義を変更できるようにします。ラベルの変更、設定の追加、プラグインの動作変更に使用できます。
Troubleshooting 4
ボタンがSVGアイコンを使用していることを確認してください（CKEditor 5では必須）。ステータスレポートページでCKEditor 5互換性の警告を確認してください。ボタンを編集してSVGアイコンファイルをアップロードしてください。
Entity EmbedやMedia Embedなど、埋め込みタイププラグインを提供するモジュールをインストールしてください。Embedモジュールはフレームワークであり、機能するには埋め込みタイププラグインが必要です。
CSRFトークンがプレビューリクエストとともに送信されていることを確認してください。認証済みユーザーの場合、X-Drupal-EmbedPreview-CSRF-Tokenヘッダーに有効なトークンが含まれている必要があります。また、ユーザーがフィルターフォーマットを使用する権限を持っているか確認してください。
ボタンアイコンはbase64エンコードデータとして保存されていますが、URIを参照しています。ファイルがURIに存在しない場合、エンコードされたデータから自動的に再作成されます。アイコンが表示されない場合はキャッシュをクリアしてください。
Security Notes 4
- プレビューエンドポイントは、不正なコンテンツレンダリングを防ぐためにCSRF保護を使用しています。匿名ユーザーの場合、カスタムヘッダーの存在で十分です。認証済みユーザーの場合、トークン値が検証されます。
- 埋め込みボタン管理へのアクセスには「administer embed buttons」権限が必要です
- プレビューアクセスはフィルターフォーマット使用権限によって制御されます - ユーザーは使用権限を持つフォーマットでのみコンテンツをプレビューできます
- このモジュールは、エディターツールバーの埋め込みボタンが必要なフィルターを有効にしていることを検証し、設定の不一致を防ぎます