> For AI agents: the complete documentation index is available at https://nhanbe.id.vn/llms.txt, the full documentation bundle is available at https://nhanbe.id.vn/llms-full.txt.
# Hướng dẫn tạo Custom Page Template trong AEM 6.5
Hướng dẫn này được viết dựa trên cấu trúc thực tế của dự án `mysite`. Tên template mẫu sử dụng xuyên suốt là **`custom-page`**. Khi áp dụng cho template mới, thay `custom-page` bằng tên phù hợp (ví dụ: `article-page`, `landing-page`).
***
## Tổng quan kiến trúc
Một Custom Page Template hoàn chỉnh trong AEM gồm **2 phần chính** nằm ở 2 module khác nhau:
```
mysite/
├── ui.apps/ → Chứa Component Definition (code/markup)
└── ui.content/ → Chứa Template Definition (cấu hình, structure, policies)
```
### Sơ đồ phụ thuộc
```
Template (/conf/mysite/.../templates/custom-page)
└── sling:resourceType → Component (apps/mysite/components/custom-page)
└── sling:resourceSuperType → apps/mysite/components/page
└── sling:resourceSuperType → core/wcm/components/page/v3/page
```
***
## PHẦN 1 — Component Definition (`ui.apps`)
### 1.1. Component chính
**File:** `ui.apps/src/main/content/jcr_root/apps/mysite/components/custom-page/.content.xml`
```xml
```
> **Giải thích:**
>
> - `jcr:primaryType="cq:Component"` — Khai báo đây là một AEM Component.
> - `jcr:title` — Tên hiển thị trong Template Editor.
> - `sling:resourceSuperType="mysite/components/page"` — Kế thừa toàn bộ render logic từ base page component (header, footer, clientlibs, ContextHub). Không cần viết lại `body.html`, `head.html`, v.v.
> - `componentGroup=".hidden"` — Ẩn component này khỏi Component Browser (chỉ dùng làm page type).
***
### 1.2. Custom Header Libs
File này inject thêm các script/style vào `` của trang, chạy **sau** `customheaderlibs.html` của component cha.
**File:** `ui.apps/src/main/content/jcr_root/apps/mysite/components/custom-page/customheaderlibs.html`
```html
```
> **Giải thích:**
>
> - Dòng `data-sly-include` — Bắt buộc phải có để kế thừa base clientlibs (`mysite.base`) và ContextHub. Nếu bỏ qua, trang sẽ không load được CSS/JS.
> - `data-sly-use.schema` — Gọi Sling Model Java để render JSON-LD (SEO structured data). Nếu template không cần schema, xóa block `` này đi.
> - Để thêm custom CSS chỉ cho template này: thêm `` vào đây.
***
### 1.3. Page Dialog (Custom Properties Tab)
Dialog cho phép tác giả nhập thêm các trường tùy chỉnh (ngoài các trường mặc định của Core Component).
**File:** `ui.apps/src/main/content/jcr_root/apps/mysite/components/custom-page/_cq_dialog/.content.xml`
```xml
```
> **Giải thích:**
>
> - `sling:resourceSuperType="core/wcm/components/page/v3/page/cq:dialog"` — Kế thừa toàn bộ dialog gốc (Basic, SEO, Social Media, Cloud Services...). Tab mới sẽ được **merge** vào.
> - `name="./subTitle"` — Giá trị sẽ được lưu vào property `subTitle` trực tiếp trên node `jcr:content` của page.
> - `cq:showOnCreate="{Boolean}true"` — Trường này xuất hiện trong wizard "Create Page".
> - Có thể thêm nhiều field types: `select`, `checkbox`, `pathfield`, `datepicker`, v.v. bằng cách thay `sling:resourceType`.
***
## PHẦN 2 — Template Definition (`ui.content`)
### 2.1. Template Node chính
**File:** `ui.content/src/main/content/jcr_root/conf/mysite/settings/wcm/templates/custom-page/.content.xml`
```xml
```
> **Giải thích:**
>
> - `jcr:primaryType="cq:Template"` — Khai báo node là một Editable Template.
> - `cq:templateType` — Trỏ đến Template Type dùng làm nền tảng (ở dự án này là `/conf/mysite/settings/wcm/template-types/page`).
> - `status="enabled"` — Template có thể được sử dụng để tạo page. Dùng `"disabled"` để ẩn.
> - `jcr:title` và `jcr:description` — Hiển thị trong wizard "Create Page".
***
### 2.2. Template Structure (Bố cục cố định)
Định nghĩa các component **bắt buộc / không thể xóa** của template (header, footer, vùng editable).
**File:** `ui.content/src/main/content/jcr_root/conf/mysite/settings/wcm/templates/custom-page/structure/.content.xml`
```xml
```
> **Giải thích:**
>
> - `sling:resourceType="mysite/components/custom-page"` — Liên kết template với component đã tạo ở Phần 1.
> - `experiencefragment-header` / `experiencefragment-footer` — Không có `editable="{Boolean}true"` → Template Author không thể xóa, Content Author không thể sửa.
> - `editable="{Boolean}true"` — Đánh dấu component/container có thể được Template Author bật/tắt, Content Author thêm nội dung.
> - `cq:responsive/breakpoints` — Định nghĩa breakpoint cho Responsive Grid (layout editor).
***
### 2.3. Initial Content (Nội dung khởi tạo)
Nội dung được **copy** vào trang mới khi tác giả tạo page từ template này. Khác với Structure, nội dung này có thể bị xóa.
**File:** `ui.content/src/main/content/jcr_root/conf/mysite/settings/wcm/templates/custom-page/initial/.content.xml`
```xml
```
> **Lưu ý:** `initial` không có header/footer vì đây là nội dung trang (không phải structure). Header/footer đã được kế thừa từ `structure`.
***
### 2.4. Policy Mappings cho Template
Ánh xạ từng component trong structure tới policy cụ thể đã định nghĩa trong policies.xml.
**File:** `ui.content/src/main/content/jcr_root/conf/mysite/settings/wcm/templates/custom-page/policies/.content.xml`
```xml
```
> **Giải thích:**
>
> - `cq:policy` — Đường dẫn tương đối đến policy node trong `policies/.content.xml` (xem Phần 3).
> - Hierarchy của policy mappings phải **khớp với hierarchy node trong `structure`**.
> - `cq:policy="mysite/components/page/policy"` trên `jcr:content` — Gán policy cho page component (clientlibs).
***
## PHẦN 3 — Global Policies
Định nghĩa tập trung tất cả policy cho mọi component trong site. Template sẽ tham chiếu đến các policy này.
**File:** `ui.content/src/main/content/jcr_root/conf/mysite/settings/wcm/policies/.content.xml`
File này chứa toàn bộ policy definition theo cấu trúc:
```
/mysite/components/
├── page/
│ └── policy → Page clientlibs (mysite.dependencies, mysite.site)
├── container/
│ ├── policy_1574694950110 → Page Root (cho phép group: My Site - Content + Structure)
│ ├── policy_1574695586800 → Page Content (cho phép group: My Site - Content)
│ ├── policy_649128221558427 → Page Main ( element)
│ └── policy_1575040440977 → XF Root
├── title/
│ ├── policy_641475696923109 → Page Title (chỉ H1, no link)
│ └── policy_641528232375303 → Content Title (H2–H6)
├── text/
│ └── policy_641562756958017 → Content Text (RTE config)
├── image/
│ └── policy_651483963895698 → Content Image (widths, lazy load, crop ratios)
├── teaser/
│ └── policy_1575031387650 → Content Teaser (H3 title)
├── download/
│ └── policy_1575032193319 → Content Download
└── experiencefragment/
├── policy_header → Page Header ( element)
└── policy_footer → Page Footer (