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. 确定用户需要哪种组件类型：
   • 页面 — 渲染完整页面，可以声明一个或多个区域。
   • Part — 带配置表单的叶组件，不包含区域。
   • 布局 — 通过命名区域组织其他组件。
   • 响应处理器 — 修改 HTTP 响应的站点级过滤器（例如，注入脚本）。
2. 如果请求不明确，请先询问用户要使用哪种组件类型，再继续操作。

步骤 3：收集组件详情

1. 询问用户或推断以下信息：
   • 组件名称（kebab-case，例如 hero-banner）。
   • 显示名称（易于理解的名称，例如 Hero Banner）。
   • 语言 — TypeScript（.ts，默认）或 JavaScript（.js）。请阅读 references/compatibility.md，了解 TS 和 JS 之间的差异。
   • 模板引擎 — Thymeleaf（默认）或 Mustache。
   • 对于页面/布局：区域名称（页面默认值：main）。
   • 对于 Part：表单字段（名称、类型、出现次数）。
   • 对于响应处理器：页面内容注入目标（bodyEnd、headEnd 等）及要注入的内容。

步骤 4：生成 XML 描述符

1. 阅读 references/controller-reference.md，了解 XML 描述符架构。
2. 创建描述符文件：
   • 页面：<sitePath>/pages/<name>/<name>.xml
   • Part：<sitePath>/parts/<name>/<name>.xml
   • 布局：<sitePath>/layouts/<name>/<name>.xml
3. 加入 <display-name>、<description>、<form>（为 Part 配置输入项）以及 <regions>（用于页面和布局）。

步骤 5：生成控制器

1. 从 assets/ 中读取相应模板：
   • 页面使用 assets/page-controller.template.ts。
   • Part 使用 assets/part-controller.template.ts。
   • 布局使用 assets/layout-controller.template.ts。
2. 将占位符替换为实际组件名称、配置字段映射、区域名称和库导入项。
3. 如果用户选择 JavaScript，请将 ES 模块语法转换为 CommonJS（require/exports）。
4. 阅读 references/controller-reference.md，了解 Portal API 的函数和导入路径。
5. 将控制器放置在：
   • 页面：<sitePath>/pages/<name>/<name>.ts（或 .js）
   • Part：<sitePath>/parts/<name>/<name>.ts（或 .js）
   • 布局：<sitePath>/layouts/<name>/<name>.ts（或 .js）
   • 处理器：<sitePath>/processors/<name>.js

步骤 6：生成视图（如适用）

1. 对于使用 Thymeleaf 或 Mustache 的页面、Part 和布局，在控制器所在目录中生成配对的 .html 视图文件。
2. 对于页面和布局，在容器元素上加入 data-portal-region="<region-name>" 属性。
3. 遍历区域时，使用 data-th-each="component : ${region.components}" 和 data-portal-component="${component.path}"。

步骤 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() 调用使用了正确的文件名。