enonic-controller-generator

Enonic XP コントローラー生成ツール

手順

ステップ 1：Enonic XP プロジェクトを検出する

1. node scripts/find-enonic-targets.mjs <workspace-root> を実行して、プロジェクトルートと既存のコンポーネントを特定します。
2. スクリプトがコード 1 で終了した場合（マーカーが見つからない場合）、Enonic XP プロジェクトが検出されなかったことをユーザーに伝え、終了します。
3. 標準出力から sitePath を記録します。生成するすべてのファイルは、このパスを基準とするディレクトリに配置します。

ステップ 2：コンポーネントの種類を決定する

1. ユーザーが必要としているコンポーネントの種類を特定します。
   • ページ — ページ全体をレンダリングし、1 つ以上のリージョンを宣言できます。
   • パーツ — 設定フォームを持つ末端コンポーネントで、リージョンはありません。
   • レイアウト — 名前付きリージョンを使って他のコンポーネントを配置します。
   • レスポンスプロセッサー — HTTP レスポンスを変更するサイトレベルのフィルターです（例：スクリプトを挿入する）。
2. リクエストが曖昧な場合は、作業を進める前にコンポーネントの種類を確認します。

ステップ 3：コンポーネントの詳細を収集する

1. 次の項目をユーザーに確認するか、推測します。
   • コンポーネント名（kebab-case、例：hero-banner）。
   • 表示名（人が読める名前、例：Hero Banner）。
   • 言語 — TypeScript（.ts、デフォルト）または JavaScript（.js）。TS と JS の違いについては references/compatibility.md を読みます。
   • テンプレートエンジン — Thymeleaf（デフォルト）または Mustache。
   • ページ／レイアウトの場合：リージョン名（デフォルト：ページでは main）。
   • パーツの場合：フォームフィールド（名前、型、出現回数）。
   • レスポンスプロセッサーの場合：ページへの出力先（bodyEnd、headEnd など）と挿入するコンテンツ。

ステップ 4：XML 記述子を生成する

1. XML 記述子のスキーマについて references/controller-reference.md を読みます。
2. 記述子ファイルを作成します。
   • ページ：<sitePath>/pages/<name>/<name>.xml
   • パーツ：<sitePath>/parts/<name>/<name>.xml
   • レイアウト：<sitePath>/layouts/<name>/<name>.xml
3. <display-name>、<description>、<form>（パーツの入力項目を含む）、および <regions>（ページとレイアウト用）を含めます。

ステップ 5：コントローラーを生成する

1. assets/ から適切なテンプレートを読みます。
   • ページには assets/page-controller.template.ts。
   • パーツには assets/part-controller.template.ts。
   • レイアウトには assets/layout-controller.template.ts。
2. プレースホルダーを実際のコンポーネント名、設定フィールドのマッピング、リージョン名、ライブラリのインポートに置き換えます。
3. JavaScript が指定された場合は、ES モジュール構文を CommonJS（require／exports）に変換します。
4. Portal API の仕様（関数、インポートパス）について references/controller-reference.md を読みます。
5. コントローラーを次の場所に配置します。
   • ページ：<sitePath>/pages/<name>/<name>.ts（または .js）
   • パーツ：<sitePath>/parts/<name>/<name>.ts（または .js）
   • レイアウト：<sitePath>/layouts/<name>/<name>.ts（または .js）
   • プロセッサー：<sitePath>/processors/<name>.js

ステップ 6：ビューを生成する（該当する場合）

1. Thymeleaf または Mustache を使うページ、パーツ、レイアウトについては、コントローラーと同じディレクトリに対応する .html ビューファイルを生成します。
2. ページとレイアウトでは、コンテナー要素に data-portal-region="<region-name>" 属性を含めます。
3. リージョンを反復処理する場合は、data-portal-component="${component.path}" とともに data-th-each="component : ${region.components}" を使用します。

ステップ 7：レスポンスプロセッサーを接続する（該当する場合）

1. レスポンスプロセッサーを生成する場合は、<sitePath>/site.xml が存在するか確認します。
2. 存在する場合は、<processors> ブロック内に <response-processor> エントリを追加します。
3. 存在しない場合は、プロセッサー宣言を含む <sitePath>/site.xml を作成します。 ステップ 8：build.gradle の依存関係を更新する
4. プロジェクトの build.gradle に既存のライブラリのインクルードがあるか確認します。
5. 不足している依存関係を追加します。
   • com.enonic.xp:lib-portal:${xpVersion} — すべてのコントローラーで必須です。
   • com.enonic.xp:lib-content:${xpVersion} — コントローラーでコンテンツクエリを使用する場合に必要です。
   • com.enonic.lib:lib-thymeleaf:2.0.0 — Thymeleaf によるレンダリングを使用する場合に必要です。
   • com.enonic.lib:lib-mustache:2.1.0 — Mustache によるレンダリングを使用する場合に必要です。
   • com.enonic.lib:lib-asset:${libVersion} — コントローラーでアセット URL を生成する場合に必要です（XP 7.15 以降で非推奨となった portalLib.assetUrl の代わりに使用します）。

ステップ 9：出力を検証する

1. ディスクリプタのファイル名が親ディレクトリ名と完全に一致していることを確認します。
2. コントローラーのファイル名がディスクリプタのディレクトリ名と一致していることを確認します。
3. コントローラー／ビュー内のすべてのリージョン名が XML ディスクリプタで宣言されているものと一致していることを確認します。
4. 生成されたコードを既知の正しいパターンと照合するため、references/examples.md を読みます。

エラー処理

• scripts/find-enonic-targets.mjs がコード 1（NO_PROJECT）で終了した場合、Enonic XP プロジェクトが見つからなかったことをユーザーに伝え、src/main/resources/site/ の下に標準のディレクトリ構造を作成するよう提案します。
• 同じ名前のコンポーネントが対象パスにすでに存在する場合、ユーザーに警告し、上書きするか名前を変更するか尋ねます。
• ユーザーからパートで 404 が発生する、またはリージョンが不足していると報告された場合は、一般的な原因を診断するために references/troubleshooting.md を読みます。
• 生成されたコントローラーの実行時にビュー解決エラーが発生する場合、ビューのファイルがコントローラーと同じディレクトリにあること、および resolve() の呼び出しで正しいファイル名を使用していることを確認します。