Custom Elements
デカップルドフロントエンドアーキテクチャ向けに、DrupalエンティティをカスタムHTML要素（Web Components）としてレンダリングするフレームワークを提供します。
custom_elements
インストール
composer require 'drupal/custom_elements:^3.3'
概要
Custom Elementsモジュールは、Drupalデータ（エンティティ、フィールド）をカスタムエレメントマークアップにレンダリングするための包括的なフレームワークを提供します。カスタムエレメントは、Web Componentsや、Vue.js、Reactなどの各種JavaScriptフロントエンドフレームワークを使用するフロントエンドコンポーネントで簡単にレンダリングできます。
これにより、Drupalは高レベルのテーマコンポーネントをレンダリングし、実際のレンダリングはフロントエンドアプリケーションが処理できるようになります。このモジュールは、プログレッシブデカップリング（カスタムエレメントと従来のDrupal出力の混在）と完全なデカップリング（カスタムエレメントマークアップまたはJSONによるAPIレスポンス）の両方をサポートします。
主な機能には、エンティティビューモードごとのカスタムエレメント出力のUI設定、キャッシュメタデータを持つネストされたカスタムエレメントツリーを構築するためのAPI、HTMLマークアップまたはJSON表現へのシリアライズ、データをカスタムエレメントにレンダリングする方法をカスタマイズするための拡張可能なプロセッサシステムが含まれます。
Features
- フロントエンドフレームワークで使用するために、DrupalエンティティをカスタムHTML要素（Web Components）としてレンダリング
- Custom Elements Displayエンティティを介した、エンティティタイプ、バンドル、ビューモードごとのカスタムエレメント出力のUIベース設定
- 2つのシリアライズ形式：HTMLマークアップ（Web Componentスタイルまたは Vue 3スタイル）とJSON（明示的形式またはレガシー形式）
- レイアウトセクションとリージョンからカスタムエレメントを構築するためのLayout Builder統合
- フィールドの複雑さに基づいてフィールドを属性またはスロットにインテリジェントにマッピングする自動処理モード
- 個々のフィールド出力をきめ細かく制御するためのプラガブルなCustom Element Field Formatter
- エンティティとフィールドをカスタムエレメントにレンダリングする方法をカスタマイズするための拡張可能なプロセッサシステム
- JSON構造プレビュー、マークアップコードプレビュー、Nuxt.jsフロントエンドプレビュー用のプレビュープロバイダー
- 適切なキャッシュメタデータバブリングを伴うネストされたカスタムエレメントのサポート
- カスタムエレメントディスプレイを管理するためのエンティティタイプごとの動的パーミッション
Use Cases
Web Componentsによるプログレッシブデカップリング
通常のDrupalレンダリングレスポンスの一部としてカスタムエレメントを使用し、Web ComponentsまたはJavaScriptがブラウザでレンダリングを引き継ぎます。特定のエンティティビューモードで「Force custom elements rendering」を有効にし、テーマでcustom_elements/mainライブラリにWeb Component JavaScriptを追加します。
Vue.js/Nuxtによる完全なデカップリング
Drupalがヘッドレスコンテンツ管理システムとして機能しながら、Vue.js/Nuxtを使用して完全にデカップルドされたフロントエンドを構築します。Lupus Custom Elements Rendererを使用してJSON APIレスポンスを提供します。スロット構文の互換性のためにVue 3マークアップスタイルを設定します。Nuxtプレビュープロバイダーにより、ライブプレビューでコンテンツを編集できます。
Layout Builder統合
DrupalのLayout Builderを使用して複雑なページレイアウトを構築しながら、カスタムエレメントとして出力します。各レイアウトセクションは<drupal-layout>エレメントになり、リージョンがスロットになります。リージョン内のブロックはネストされたカスタムエレメントとしてレンダリングされます。
エンティティ参照フィールドのレンダリング
参照エンティティ（メディア、Paragraphs、その他のコンテンツなど）をネストされたカスタムエレメントとしてレンダリングします。「Custom element: Rendered entity」フォーマッターを使用し、設定可能なビューモードとプロパティを親エレメントにマージするオプションのフラット化機能があります。
画像スタイル処理を伴う画像フィールド
画像スタイル処理を伴う画像フィールドを出力します。画像フォーマッターはスタイル適用された画像のURLとaltテキスト、幅、高さ属性を生成します。フラット化オプションを有効にすると、画像プロパティを親エレメントの個別の属性として出力できます。
API開発とデバッグ
Custom Elements Display編集フォームのJSONプレビュープロバイダーを使用して、フロントエンドに送信されるJSON構造を正確に確認できます。明示的JSON形式はpropsとslotsを明確に分離し、フロントエンドでの消費を容易にします。
Tips
- 「custom_elements」で始まる名前のビューモードは自動的にカスタムエレメントレンダリングが有効になります
- エンティティ参照およびファイルフォーマッターの「Flatten」オプションを使用すると、参照エンティティのプロパティを親エレメントに直接マージできます
- プロセッサ優先度システムにより、カスタムモジュールは優先度の高いプロセッササービスを登録することでデフォルトのフィールド処理をオーバーライドできます
- キャッシュメタデータはネストされたカスタムエレメントを通じて適切にバブリングされ、正しいキャッシュ無効化を保証します
- settings.phpでCustomElement::$removeFieldPrefix静的プロパティを設定すると、出力キーから「field_」プレフィックスをグローバルに削除できます
Technical Details
Admin Pages 1
/admin/config/system/custom-elements
マークアップスタイル、JSON形式、デフォルトレンダリングモードを含むカスタムエレメントレンダリングのグローバル設定を行います。
権限 2
Hooks 2
hook_custom_element_entity_defaults_alter
カスタムエレメントが処理される前にデフォルト値を準備できるようにします。エンティティからカスタムエレメントを生成する際に呼び出され、モジュールがデフォルトのタグ名、プレフィックス、または属性を設定できるようにします。
hook_custom_element_entity_alter
生成後、レンダリング前にカスタムエレメントを変更できるようにします。すべてのフィールド処理が完了した後に呼び出され、最終的な修正を可能にします。
Troubleshooting 4
そのビューモードのエンティティの「表示管理」タブで「Force custom elements rendering」が有効になっていることを確認するか、ビューモード名が「custom_elements」で始まっていることを確認してください（これにより自動的にレンダリングが有効になります）。
エンティティビューディスプレイとCustom Elements Displayの両方で「Use Layout Builder」が有効になっている必要があります。両方の設定を確認し、Layout Builderモジュールがインストールされていることを確認してください。
/admin/config/system/custom-elementsでJSONシリアライズ形式設定を確認してください。「Explicit」形式はprops/slotsを分離し、「Legacy」形式はそれらを混在させます。既存のサイトはアップグレード後にレガシー形式になっている可能性があります。
バージョン3.xは設定ベースのレンダリングを使用します。エンティティビューモード用のCustom Elements Displayを作成し、「Automatic Processing」オプションを有効にして2.xの動作を再現してください。drupal.org/list-changes/custom_elementsで変更履歴を参照してください。
Security Notes 3
- Custom Elements displayはDrupalのフィールドアクセスシステムを尊重します - ユーザーがアクセスできないフィールドは出力に含まれません
- JSON出力はマークアップレンダリング時のXSSを防ぐために適切なエスケープを使用します
- このモジュールは通常のエンティティビューレンダリングを通じてアクセスできないデータを公開しません