enonic-controller-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enonic XP Controller Generator

Enonic XP 控制器生成器

Procedures

操作步骤

Step 1: Detect Enonic XP Project

Execute
```
node scripts/find-enonic-targets.mjs <workspace-root>
```
to locate the project root and existing components.
If the script exits with code 1 (no markers found), inform the user that no Enonic XP project was detected and stop.
Record the
```
sitePath
```
from stdout — all generated files target directories relative to this path.

Step 2: Determine Component Type

Identify which component type the user requires:
- Page — renders a full page, may declare one or more regions.
- Part — a leaf component with a config form, no regions.
- Layout — organizes other components via named regions.
- Response processor — a site-level filter that modifies the HTTP response (e.g., inject scripts).
If the request is ambiguous, ask the user to clarify the component type before proceeding.

Step 3: Gather Component Details

Ask for or infer the following:
- Component name (kebab-case, e.g.,
```
hero-banner
```
  ).
- Display name (human-readable, e.g.,
```
Hero Banner
```
  ).
- Language — TypeScript (
```
.ts
```
  , default) or JavaScript (
```
.js
```
  ). Read
```
references/compatibility.md
```
  for guidance on TS vs JS differences.
- Template engine — Thymeleaf (default) or Mustache.
- For pages/layouts: region names (default:
```
main
```
  for pages).
- For parts: form fields (name, type, occurrences).
- For response processors: page contribution target (
```
bodyEnd
```
  ,
```
headEnd
```
  , etc.) and the content to inject.

Step 4: Generate the XML Descriptor

Read
```
references/controller-reference.md
```
for the XML descriptor schema.

Create the descriptor file:

Page:
```
<sitePath>/pages/<name>/<name>.xml
```
Part:
```
<sitePath>/parts/<name>/<name>.xml
```
Layout:
```
<sitePath>/layouts/<name>/<name>.xml
```

Include
```
<display-name>
```
,
```
<description>
```
,
```
<form>
```
(with inputs for parts), and
```
<regions>
```
(for pages and layouts).

Step 5: Generate the Controller

Read the appropriate template from

assets/

```
assets/page-controller.template.ts
```
for pages.
```
assets/part-controller.template.ts
```
for parts.
```
assets/layout-controller.template.ts
```
for layouts.

Replace placeholders with the actual component name, config field mappings, region names, and library imports.
If JavaScript was requested, convert the ES module syntax to CommonJS (
```
require
```
/
```
exports
```
).
Read
```
references/controller-reference.md
```
for the Portal API surface (functions, import paths).

Place the controller at:

Page:
```
<sitePath>/pages/<name>/<name>.ts
```
(or
```
.js
```
)
Part:
```
<sitePath>/parts/<name>/<name>.ts
```
(or
```
.js
```
)
Layout:
```
<sitePath>/layouts/<name>/<name>.ts
```
(or
```
.js
```
)
Processor:
```
<sitePath>/processors/<name>.js
```

Step 6: Generate the View (if applicable)

For pages, parts, and layouts using Thymeleaf or Mustache, generate a paired
```
.html
```
view file in the same directory as the controller.
For pages and layouts, include
```
data-portal-region="<region-name>"
```
attributes on container elements.

For region iteration, use

data-th-each="component : ${region.components}"

with

data-portal-component="${component.path}"

Step 7: Wire Response Processors (if applicable)

If generating a response processor, check whether
```
<sitePath>/site.xml
```
exists.
If it exists, add a
```
<response-processor>
```
entry inside the
```
<processors>
```
block.
If it does not exist, create
```
<sitePath>/site.xml
```
with the processor declaration.

Step 8: Update build.gradle Dependencies

Check the project's
```
build.gradle
```
for existing library includes.
Add any missing dependencies:
- ```
com.enonic.xp:lib-portal:${xpVersion}
```
  — required for all controllers.
- ```
com.enonic.xp:lib-content:${xpVersion}
```
  — if the controller uses content queries.
- ```
com.enonic.lib:lib-thymeleaf:2.0.0
```
  — if using Thymeleaf rendering.
- ```
com.enonic.lib:lib-mustache:2.1.0
```
  — if using Mustache rendering.

Step 9: Validate Output

Verify the descriptor file name matches the parent directory name exactly.
Verify the controller file name matches the descriptor directory name.
Verify all region names in the controller/view match those declared in the XML descriptor.
Read
```
references/examples.md
```
to cross-check the generated code against known-good patterns.

步骤1：检测Enonic XP项目

执行

node scripts/find-enonic-targets.mjs <workspace-root>

命令定位项目根目录和现有组件。

如果脚本退出码为1（未找到项目标记），告知用户未检测到Enonic XP项目并终止流程。
记录标准输出中的
```
sitePath
```
——所有生成的文件都会放在该路径对应的相对目录下。

步骤2：确定组件类型

确认用户需要的组件类型：
- Page —— 渲染完整页面，可声明一个或多个区域。
- Part —— 带配置表单的叶子组件，无区域。
- Layout —— 通过命名区域组织其他组件。
- Response processor —— 站点级别的过滤器，用于修改HTTP响应（例如注入脚本）。
如果需求不明确，先请用户明确组件类型再继续。

步骤3：收集组件详情

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

步骤4：生成XML描述符

参考
```
references/controller-reference.md
```
中的XML描述符Schema。

创建描述符文件：

页面：
```
<sitePath>/pages/<name>/<name>.xml
```
Part：
```
<sitePath>/parts/<name>/<name>.xml
```
布局：
```
<sitePath>/layouts/<name>/<name>.xml
```

包含
```
<display-name>
```
、
```
<description>
```
、
```
<form>
```
（Part组件需包含输入项）和
```
<regions>
```
（页面和布局组件需要）标签。

步骤5：生成控制器

从

assets/

目录读取对应模板：

页面对应
```
assets/page-controller.template.ts
```
Part对应
```
assets/part-controller.template.ts
```
布局对应
```
assets/layout-controller.template.ts
```

用实际的组件名称、配置字段映射、区域名称和库导入替换占位符。
如果用户选择JavaScript，将ES模块语法转换为CommonJS（
```
require
```
/
```
exports
```
）。
参考
```
references/controller-reference.md
```
了解Portal API范围（函数、导入路径）。

将控制器文件放在对应路径：

页面：
```
<sitePath>/pages/<name>/<name>.ts
```
（或
```
.js
```
）
Part：
```
<sitePath>/parts/<name>/<name>.ts
```
（或
```
.js
```
）
布局：
```
<sitePath>/layouts/<name>/<name>.ts
```
（或
```
.js
```
）
处理器：
```
<sitePath>/processors/<name>.js
```

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

对于使用Thymeleaf或Mustache的页面、Part、布局组件，在控制器同级目录生成对应的
```
.html
```
视图文件。
页面和布局组件的容器元素需要添加
```
data-portal-region="<region-name>"
```
属性。

区域迭代使用

data-th-each="component : ${region.components}"

搭配

data-portal-component="${component.path}"

实现。

步骤7：注册响应处理器（如适用）

如果生成的是响应处理器，检查
```
<sitePath>/site.xml
```
是否存在。
如果存在，在
```
<processors>
```
块中添加
```
<response-processor>
```
条目。
如果不存在，创建
```
<sitePath>/site.xml
```
并添加处理器声明。

步骤8：更新build.gradle依赖

检查项目
```
build.gradle
```
中已有的库引入。
添加缺失的依赖：
- ```
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渲染。

步骤9：验证输出

确认描述符文件名与父目录名完全一致。
确认控制器文件名与描述符所在目录名一致。
确认控制器/视图中所有区域名称与XML描述符中声明的一致。
参考
```
references/examples.md
```
将生成的代码与已知的正确模式交叉校验。

Error Handling

错误处理

If
```
scripts/find-enonic-targets.mjs
```
exits with code 1 (
```
NO_PROJECT
```
), inform the user that no Enonic XP project was found and suggest creating the standard directory structure under
```
src/main/resources/site/
```
.
If a component with the same name already exists at the target path, warn the user and ask whether to overwrite or rename.
If the user reports a 404 on a part or missing regions, read
```
references/troubleshooting.md
```
to diagnose common causes.
If the generated controller fails at runtime with view resolution errors, verify the view file is co-located with the controller and the
```
resolve()
```
call uses the correct filename.

如果
```
scripts/find-enonic-targets.mjs
```
退出码为1（
```
NO_PROJECT
```
），告知用户未找到Enonic XP项目，建议在
```
src/main/resources/site/
```
下创建标准目录结构。
如果目标路径已存在同名组件，警告用户并询问是否覆盖或重命名。
如果用户反馈Part出现404或区域缺失，参考
```
references/troubleshooting.md
```
排查常见原因。
如果生成的控制器运行时出现视图解析错误，确认视图文件与控制器同目录，且
```
resolve()
```
调用使用了正确的文件名。