` bao quanh component khi render | ### Dialog Skeleton (Granite Coral UI) ```tree cq:dialog (sling:resourceType="cq/gui/components/authoring/dialog") └ content → granite/ui/components/coral/foundation/container └ items └ tabs → granite/ui/components/coral/foundation/tabs └ items └ mainTab (jcr:title="Properties") → .../foundation/container └ items └ columns → .../foundation/fixedcolumns └ items └ column → .../foundation/container └ items └

``` ### Form Field Resource Types & Properties **Prefix chung:** `granite/ui/components/coral/foundation/form/` - `textfield` · `textarea` · `pathfield` · `select` · `checkbox` · `switch` - `numberfield` · `datepicker` · `radiogroup` · `hidden` · `fileupload` - `multifield` · `colorfield` - Rich Text: `cq/gui/components/authoring/dialog/richtext` - Tag Picker: `cq/gui/components/coral/common/form/tagfield` **Common Field Properties:** ```xml name="./propertyName" fieldLabel="Title" fieldDescription="Enter text" required="{Boolean}true" emptyText="Placeholder" value="true" uncheckedValue="false" rootPath="/content/dam" composite="{Boolean}true" ``` ### Dialog Validation (Granite UI) **1. Đăng ký validator trong Clientlib (`cq.authoring.dialog`):** ```javascript (function ($, $document) { "use strict"; $.validator.register({ selector: "[data-validation='myproject.productcode']", validate: function (el) { var val = el.val(); if (!val) { return; } // Bỏ qua nếu rỗng, để required kiểm tra if (!/^[A-Z]{2}-\d{4}$/.test(val)) { return "Định dạng mã sản phẩm phải là AB-1234"; } } }); })(jQuery, jQuery(document)); ``` **2. Khai báo trên dialog field XML:** ```xml ``` **3. Cross-field Revalidation (JavaScript):** ```javascript $document.on("change", "[name='./startDate']", function () { $(this).closest("form").find("[name='./endDate']").trigger("change"); }); ``` **4. Server-side Validation đối ứng trong Sling Model:** ```java @PostConstruct protected void init() { this.valid = (productCode != null && PATTERN.matcher(productCode).matches()); if (productCode != null && !valid) { LOG.warn("Invalid productCode '{}' at {} - validation bypassed", productCode, resource.getPath()); } } ``` ### Conditional Show/Hide trong Dialog **Dropdown Show/Hide:** ```xml ``` _Checkbox tương tự với class:_ `cq-dialog-checkbox-showhide` và target `.target-class`. ### Page Properties Visibility ```xml cq:showOnCreate="{Boolean}true" cq:hideOnEdit="{Boolean}true" renderReadOnly="{Boolean}true" allowBulkEdit="{Boolean}true" ``` ### EditConfig (`cq:EditConfig`) File: `_cq_editConfig.xml` ```xml ``` - `cq:actions`: `text:` | `-` (dấu phân cách) | `edit` | `delete` | `insert` | `copymove` - `cq:listeners`: `afteredit` / `afterinsert` = `REFRESH_PAGE` hoặc `REFRESH_SELF` - `cq:inplaceEditing`: `editorType="text|title|plaintext"` ### Accessibility Contract (Accordion Component) ```html

``` *** ## 4. HTL (Sightly) ### Calling Sling Models ```html

${cta.title}

${cta.text}

...

``` ### Block Statements | Statement | Purpose | | -------------------------------------------------- | ------------------------------------------------------------------------ | | `data-sly-use.name="..."` | Khởi tạo Sling Model, Java use-class, hoặc HTL template | | `data-sly-set.name="${...}"` | Gán biến tạm thời trong scope | | `data-sly-test="${...}"` | Render thẻ khi điều kiện đúng (if) | | `data-sly-test.name="${...}"` | Kiểm tra điều kiện và lưu kết quả vào biến để tái sử dụng | | `data-sly-list.item="${list}"` | Vòng lặp: lặp qua các phần tử con của collection | | `data-sly-repeat.item="${list}"` | Vòng lặp: lặp lại chính thẻ HTML chứa nó | | `data-sly-unwrap` | Bỏ thẻ HTML bao ngoài, chỉ render nội dung bên trong | | `data-sly-resource="${path @ resourceType='...'}"` | Include một JCR resource khác vào trang | | `data-sly-include="script.html"` | Include một file HTL/JSP khác vào vị trí hiện tại | | `data-sly-template.name="${@ param}"` | Định nghĩa template có thể tái sử dụng | | `data-sly-call="${name @ param=value}"` | Gọi template đã định nghĩa | | `data-sly-element="${model.tag}"` | Đổi tên thẻ HTML động (ví dụ: `h1`, `h2`, `div`) | | `data-sly-attribute.href="${model.url}"` | Gán thuộc tính HTML động | | `data-sly-text="${model.content}"` | Thay thế toàn bộ text bên trong thẻ | | `` | Thẻ ẩn dùng làm container cho các logic directive mà không sinh thẻ HTML | **Loop Variables (tự động sinh ra khi lặp):** ```text itemList.index # Index 0-based itemList.count # Thứ tự 1-based itemList.first # Boolean: phần tử đầu tiên itemList.last # Boolean: phần tử cuối cùng itemList.middle # Boolean: phần tử ở giữa itemList.odd # Boolean: vị trí lẻ (1, 3, 5) itemList.even # Boolean: vị trí chẵn (2, 4, 6) ``` ### Display Contexts & Expressions ```html ${model.richText @ context='html'} ${model.targetUrl @ context='uri'} ${model.jsonSchema @ context='unsafe'} ${model.jsString @ context='scriptString'} ${'{0} of {1}' @ format=[item.count, total]} ${items @ join=', '} ${'Learn More' @ i18n} ${model.date @ format='dd MMM yyyy'} ``` ### Global Objects ```text properties # ValueMap của resource hiện tại pageProperties # ValueMap của jcr:content của page hiện tại inheritedPageProperties # ValueMap kế thừa từ các page cha currentPage # Đối tượng Page hiện tại currentStyle # Resolved Policy của component hiện tại resource # Resource hiện tại resourceResolver # ResourceResolver hiện tại wcmmode # Chế độ WCM (wcmmode.edit, wcmmode.preview, wcmmode.disabled) request # SlingHttpServletRequest ``` ### Common Patterns ```html

${item.title}

Không có dữ liệu hiển thị.

${properties['jcr:title']} Link luôn hợp lệ Bỏ qua kiểm tra link ``` *** ## 5. Client-Side Libraries (Clientlibs) ### Cấu trúc thư mục & `.content.xml` ```tree /apps//clientlibs/clientlib-site/ ├── .content.xml ├── css.txt ├── js.txt ├── css/ │ ├── base.less │ └── components.less ├── js/ │ └── site.js └── resources/ # Static assets (fonts, images) phục vụ trực tiếp ``` File `.content.xml`: ```xml ``` - `categories`: Tên định danh clientlib để gọi trong HTL. - `allowProxy="{Boolean}true"`: Cho phép truy cập clientlib dưới `/apps` thông qua URL `/etc.clientlibs/`. - `dependencies`: Clientlib phụ thuộc, tải thành các file riêng biệt trước clientlib này. - `embed`: Nhúng toàn bộ mã nguồn của clientlib được chỉ định vào trong cùng file này. ### Định dạng `css.txt` / `js.txt` ```text #base=css variables.less base.less components.less ``` ### Proxy Path Translation ```text Thư mục gốc JCR: /apps/myproject/clientlibs/clientlib-site ↓ (Tự động bỏ tiền tố /apps) URL phục vụ: /etc.clientlibs/myproject/clientlibs/clientlib-site.css Static Resources: /etc.clientlibs/myproject/clientlibs/clientlib-site/resources/fonts/custom.woff2 ``` ### Include trong HTL ```html ``` ### Dispatcher Rule & Debug Consoles **Dispatcher allow rule:** ```text /0100 { /type "allow" /path "/etc.clientlibs/*" /extension '(css|js|png|jpg|svg|woff|woff2)' } ``` **Debug URLs:** - `?debugClientLibs=true`: Tải từng file lẻ không nén để xem lỗi JS/CSS cụ thể. - `/libs/granite/ui/content/dumplibs.html`: Danh sách toàn bộ clientlib trên hệ thống. - `/libs/granite/ui/content/dumplibs.test.html?categories=myproject.site`: Kiểm tra resolve các file CSS/JS của category. - `/libs/granite/ui/content/dumplibs.validate.html`: Tìm kiếm các category bị trùng lặp. - `/libs/granite/ui/content/dumplibs.rebuild.html`: Xóa cache và build lại toàn bộ clientlibs. *** ## 6. Editable Templates & Policies ### Architecture Paths ```tree /conf//settings/wcm/templates// ├── jcr:content # Status (draft|enabled), allowedPaths, jcr:title ├── structure/ # Cấu trúc cố định, LIVE update đến tất cả page sử dụng template ├── initial/ # Nội dung khởi tạo, chỉ copy 1 lần khi tạo page mới └── policies/ # Mapping từ cấu trúc component đến cq:policy tương ứng /conf//settings/wcm/policies/ # Nơi lưu trữ POLICY DEFINITIONS /conf//settings/wcm/template-types/ # Blueprint mẫu để tạo template mới ``` ### Template Properties & Availability **Properties trên `jcr:content` của template:** - `jcr:title`: Tên template hiển thị khi tạo trang. - `status`: `draft` | `enabled` | `disabled`. Phải là `enabled` thì tác giả mới tạo được trang. - `allowedPaths`: Regex array xác định cây thư mục được phép dùng template (Ví dụ: `[/content/myproject(/.*)?]`). - `ranking`: Thứ tự sắp xếp trong danh sách Create Page. **Thứ tự ưu tiên đánh giá Template Availability:** 1. `cq:allowedTemplates` trên page cha hoặc site root (Độ ưu tiên cao nhất). 2. `allowedPaths` trên template definition. 3. `allowedParents` trên template. 4. `allowedChildren` trên template. ### Policy Properties - `cq:policy`: Đường dẫn trỏ đến node định nghĩa policy trong `/conf/.../policies/`. - `components`: Danh sách component được phép thêm vào container (Ví dụ: `["group:My Project", "myproject/components/content/hero"]`). - `cq:styleGroups`: Định nghĩa Style System class cho component. - `clientlibs`: Khai báo category clientlib tự động load cho page policy. ### Diagnostic Checklists :::tip\[Checklist: Template không xuất hiện khi tạo page] 1. Template đã chuyển sang trạng thái `enabled` chưa? 2. `allowedPaths` regex có khớp với đường dẫn page đang tạo không? 3. Thuộc tính `cq:allowedTemplates` trên content root folder có bao gồm template này không? 4. User hiện tại có quyền JCR read trên thư mục `/conf/` không? ::: :::tip\[Checklist: Không thêm được component vào layout container] 1. Component đã được tích chọn trong `components` list của container policy chưa? 2. `componentGroup` của component có bị rỗng hoặc là `.hidden` không? 3. Layout container con có bị thiếu ánh xạ `cq:policy` không? 4. Author có quyền modify trên node page đang edit không? ::: *** ## 7. Sling Models ### `@Model` Annotation ```java @Model( adaptables = { Resource.class, SlingHttpServletRequest.class }, adapters = { Cta.class, ComponentExporter.class }, resourceType = "myproject/components/cta", defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL, cache = true ) public class CtaImpl implements Cta { // ... } ``` - `adaptables`: `Resource.class`, `SlingHttpServletRequest.class`, hoặc cả hai. - `adapters`: Interface đăng ký để inject hoặc export. - `resourceType`: Liên kết trực tiếp model với component resource type. - `defaultInjectionStrategy`: Mặc định là `REQUIRED`, nên đặt `OPTIONAL` để tránh NPE khi thiếu property. - `cache = true`: Tái sử dụng instance model trong cùng một request. ### Injector Annotations | Annotation | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `@ValueMapValue` | Inject property từ chính node hiện tại | | `@ChildResource` | Inject child node thành `Resource`, một Model con, hoặc `List` | | `@ResourcePath` | Resolve path lưu trong property thành một `Resource` | | `@OSGiService` | Inject một OSGi service vào model | | `@ScriptVariable` | Inject các HTL binding objects (`currentPage`, `currentStyle`, `resourceResolver`) — yêu cầu adaptable là `SlingHttpServletRequest` | | `@RequestAttribute` | Inject attribute được set từ filter hoặc servlet cấp cao hơn | | `@SlingObject` | Inject `ResourceResolver`, `Resource`, `SlingHttpServletRequest`, `SlingHttpServletResponse` | | `@Self` | Inject chính object adaptable (Resource hoặc Request) | ### Modifiers & Lifecycle ```java @ValueMapValue @Named("jcr:title") // Tên property khác với tên field Java private String title; @ValueMapValue @Default(values = "default-theme") // Giá trị mặc định khi property null private String theme; @ValueMapValue @Required // Bắt buộc property này không được null private String requiredId; @Self @Via("resource") // Chuyển đối tượng resolve về resource khi adaptable là request private Resource currentResource; @OSGiService(filter = "(component.name=myproject.SpecialService)") private MyService specificService; // Lọc OSGi service cụ thể theo LDAP filter @PostConstruct protected void init() { // Chạy ngay sau khi hoàn thành injection. Bắt buộc: void, không tham số } ``` ### Usage & Testing ```html ``` ```java // Java adaptation CtaModel model = resource.adaptTo(CtaModel.class); if (model != null) { // Logic xử lý } ``` ```java // Unit Test setup với AemContext (io.wcm.testing.aem-mock) context.load().json("/sample-content.json", "/content/sample"); context.addModelsForClasses(CtaImpl.class); context.registerService(MyService.class, mockService); Cta cta = context.currentResource("/content/sample/jcr:content/cta").adaptTo(Cta.class); assertNotNull(cta); ``` *** ## 8. OSGi & Services ### Component Declaration & Lifecycle ```java @Component( service = MyService.class, immediate = true, configurationPolicy = ConfigurationPolicy.REQUIRE, property = { "service.ranking:Integer=100" }, scope = ServiceScope.SINGLETON ) public class MyServiceImpl implements MyService { @Activate protected void activate(MyConfig config) { // Khởi tạo service khi active } @Modified protected void modified(MyConfig config) { // Cập nhật cấu hình khi configMgr thay đổi } @Deactivate protected void deactivate() { // Giải phóng tài nguyên, đóng thread pool / stream } } ``` ### Dependency Injection (`@Reference`) ```java // Bắt buộc (Mặc định) @Reference private MyService service; // Tùy chọn (Optional & Dynamic) @Reference(cardinality = ReferenceCardinality.OPTIONAL, policy = ReferencePolicy.DYNAMIC) private volatile MyOptionalService optionalService; // Bắt buộc khai báo volatile // Đa tham chiếu (Multiple) @Reference(cardinality = ReferenceCardinality.MULTIPLE, policy = ReferencePolicy.DYNAMIC) private volatile List handlers; // Lọc theo target property @Reference(target = "(component.name=com.myproject.core.CachedService)") private MyService cachedImpl; ``` ### OSGi Configuration (OCD) ```java @ObjectClassDefinition(name = "My Project Service Configuration", description = "Cấu hình API endpoints và timeout") public @interface MyConfig { @AttributeDefinition(name = "Endpoint URL", description = "Base URL của backend API") String endpoint() default "https://api.myproject.com/v1"; @AttributeDefinition(name = "Timeout (ms)") int timeout() default 5000; } ``` Liên kết OCD vào Component: ```java @Component(service = MyService.class) @Designate(ocd = MyConfig.class) public class MyServiceImpl implements MyService { ... } ``` **File `.cfg.json` cấu hình theo run mode:** ```text ui.config/.../apps/myproject/osgiconfig/config.publish.prod/ └── com.myproject.core.services.impl.MyServiceImpl.cfg.json ``` *** ## 9. Servlets & Filters ### Registration **1. Resource-Type Based Servlet (Khuyên dùng):** ```java @Component(service = Servlet.class) @SlingServletResourceTypes( resourceTypes = "myproject/components/product-list", selectors = "filter", extensions = "json", methods = HttpConstants.METHOD_GET ) public class ProductListServlet extends SlingSafeMethodsServlet { @Override protected void doGet(SlingHttpServletRequest req, SlingHttpServletResponse res) throws IOException { res.setContentType("application/json"); res.setCharacterEncoding("UTF-8"); res.getWriter().write("{"status":"ok"}"); } } ``` **2. Path-Based Servlet:** ```java @Component(service = Servlet.class) @SlingServletPaths("/bin/myproject/checkout") public class CheckoutServlet extends SlingAllMethodsServlet { @Override protected void doPost(SlingHttpServletRequest req, SlingHttpServletResponse res) { // Cần bổ sung rule allow trong Dispatcher filter } } ``` ### Request & Response APIs ```java Resource resource = request.getResource(); ResourceResolver resolver = request.getResourceResolver(); // Không tự ý đóng resolver của request! String[] selectors = request.getRequestPathInfo().getSelectors(); String suffix = request.getRequestPathInfo().getSuffix(); String extension = request.getRequestPathInfo().getExtension(); String query = request.getParameter("q"); response.setStatus(SlingHttpServletResponse.SC_OK); response.setContentType("application/json;charset=UTF-8"); ``` ### Sling Filters ```java @Component(service = Filter.class) @SlingServletFilter( scope = SlingServletFilterScope.REQUEST, pattern = "/content/myproject/.*" ) @ServiceRanking(-700) // Thứ tự thực thi (số âm chạy sau, số dương chạy trước) public class SecurityFilter implements Filter { @Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { // Tiền xử lý chain.doFilter(req, res); // Hậu xử lý } } ``` _Scopes:_ `REQUEST` · `INCLUDE` · `COMPONENT` · `FORWARD` · `ERROR` *** ## 10. Schedulers, Sling Jobs & Events ### Scheduler (Runnable) ```java @Component(service = Runnable.class, immediate = true) @Designate(ocd = MySchedulerConfig.class) public class DailySyncTask implements Runnable { @Override public void run() { // Chạy ngầm định kỳ } } ``` **Quartz Cron Syntax (Bắt đầu với GIÂY):** ```text Giây Phút Giờ Ngày-trong-tháng Tháng Ngày-trong-tuần [Năm] 0 0 2 * * ? # 2:00 sáng mỗi ngày 0 */15 * * * ? # Mỗi 15 phút 0 0 */4 * * ? # Mỗi 4 giờ 0 30 6 ? * MON-FRI # 6:30 sáng từ thứ Hai đến thứ Sáu ``` _(Lưu ý: Một trong hai trường ngày phải là `?`, không dùng cả hai `*`)_ ### Sling Jobs (Guaranteed Execution) ```java // Tạo Sling Job (Producer) @Reference private JobManager jobManager; Map props = new HashMap<>(); props.put("productId", "PROD-1234"); jobManager.addJob("myproject/sync/product", props); ``` ```java // Xử lý Sling Job (Consumer) @Component( service = JobConsumer.class, property = { JobConsumer.PROPERTY_TOPICS + "=myproject/sync/product" } ) public class ProductSyncConsumer implements JobConsumer { @Override public JobResult process(Job job) { String id = job.getProperty("productId", String.class); // Trả về: JobResult.OK | JobResult.FAILED (cho phép retry) | JobResult.CANCEL return JobResult.OK; } } ``` ### Resource Change Listener & Event Handling ```java @Component( service = ResourceChangeListener.class, property = { ResourceChangeListener.PATHS + "=/content/myproject/products", ResourceChangeListener.CHANGES + "=ADDED", ResourceChangeListener.CHANGES + "=CHANGED" } ) public class ProductChangeListener implements ResourceChangeListener { @Override public void onChange(List changes) { // Chỉ thực hiện kiểm tra nhẹ, sau đó dispatch một Sling Job để xử lý nặng } } ``` ### Decision Matrix: Khi nào dùng giải pháp nào? | Yêu cầu | Giải pháp phù hợp | Lưu trữ | | ------------------------------------------------------------------ | -------------------------- | ------------------------- | | Chạy theo mốc thời gian cố định | **Scheduler** | In-memory | | Lắng nghe thay đổi node JCR | **ResourceChangeListener** | JCR event system | | Xử lý bất đồng bộ nặng, không được phép mất tác vụ khi restart pod | **Sling Job** | `/var/eventing/jobs` | | Quy trình cần người duyệt, tương tác UI hoặc audit trail | **Workflow** | `/var/workflow/instances` | *** ## 11. Workflows ### Paths & Kiến trúc - `/conf/global/settings/workflow/models/`: Chứa file định nghĩa mô hình workflow (Design time). - `/var/workflow/models/`: Bản sao chạy thực tế (Runtime). **Bắt buộc bấm nút Sync trong Workflow Console sau khi sửa model**. - `/conf/global/settings/workflow/launcher/config/`: Danh sách launcher kích hoạt workflow tự động. - `/var/workflow/instances/`: Trạng thái các instance đang chạy và lịch sử thực thi. ### Custom Workflow Process Step ```java @Component( service = WorkflowProcess.class, property = { "process.label=My Project - Custom Step" } ) public class CustomStepProcess implements WorkflowProcess { @Override public void execute(WorkItem item, WorkflowSession session, MetaDataMap args) throws WorkflowException { String payload = item.getWorkflowData().getPayload().toString(); ResourceResolver resolver = session.adaptTo(ResourceResolver.class); // Lưu data dùng chung cho các step sau item.getWorkflow().getWorkflowData().getMetaDataMap().put("customKey", "customValue"); } } ``` ### Dynamic Participant Chooser ```java @Component( service = ParticipantStepChooser.class, property = { "chooser.label=My Project - Route by Category" } ) public class DynamicRouter implements ParticipantStepChooser { @Override public String getParticipant(WorkItem item, WorkflowSession session, MetaDataMap args) { return "content-approvers-group"; // Trả về user ID hoặc group ID } } ``` *** ## 12. Security, Users & Repoinit ### JCR Locations & Evaluation Rules ```text /home/users// # rep:User /home/groups// # rep:Group /home/users/system/... # Service users (hệ thống) /rep:policy # Danh sách ACL (rep:GrantACE / rep:DenyACE) ``` **Thứ tự ưu tiên đánh giá quyền:** 1. **DENY BY DEFAULT** — Mặc định không có quyền gì. 2. **CLOSEST ACL WINS** — Quyền cấu hình ở node sâu hơn sẽ ghi đè quyền thừa kế từ node cha. 3. **DENY BEATS ALLOW** — Nếu ở cùng một level có cả Allow và Deny thì Deny luôn thắng. _(Không thể ghi đè lệnh Deny bằng cách gán user vào một group khác có quyền Allow)_. ### Repoinit Syntax Định nghĩa service users và phân quyền an toàn qua cấu hình OSGi: ``` create service user myproject-reader with path system/cq:services/myproject create group myproject-editors add myproject-editors to group content-authors set ACL for myproject-editors allow jcr:read,rep:write on /content/myproject allow jcr:read on /content/dam/myproject restriction(rep:glob,"") deny crx:replicate on /content/myproject/drafts end create path (sling:Folder) /var/myproject/data ``` ### Lấy ResourceResolver từ Service User ```java // 1. Cấu hình OSGi Service User Mapping: // bundleSymbolicName:subserviceName=[serviceUserName] // com.myproject.core:content-reader=[myproject-reader] // 2. Lấy resolver trong Java code: Map authInfo = Collections.singletonMap( ResourceResolverFactory.SUBSERVICE, "content-reader" ); try (ResourceResolver resolver = resolverFactory.getServiceResourceResolver(authInfo)) { // Luôn dùng try-with-resources để tự động đóng resolver sau khi dùng xong Resource res = resolver.getResource("/content/myproject"); } ``` *** ## 13. Content Fragments & Experience Fragments ### Content Fragments (CF) - **Model path:** `/conf//settings/dam/cfm/models/` - **Fragment path:** `/content/dam//fragments/` - **Mục đích:** Quản lý nội dung thuần (dữ liệu có cấu trúc, không chứa layout) để phục vụ cho đa kênh (Headless). **Đọc CF trong Sling Model:** ```java Resource fragmentResource = resourceResolver.getResource(fragmentPath); if (fragmentResource != null) { ContentFragment cf = fragmentResource.adaptTo(ContentFragment.class); if (cf != null) { ContentElement element = cf.getElement("title"); String title = element.getContent(); // Đọc variation cụ thể ContentVariation socialVar = element.getVariation("social"); } } ``` ### Experience Fragments (XF) - **Structure path:** `/content/experience-fragments//.../` (Lưu dưới dạng `cq:Page`). - **Mục đích:** Chứa cả nội dung và giao diện (HTML + Clientlib), có thể nhúng trực tiếp vào các trang hoặc xuất ra kênh ngoài. - **HTML Export:** Truy cập URL `/content/experience-fragments/.../master.plain.html` để lấy HTML thuần không có chrome vỏ bọc. ### So sánh CF vs XF | Đặc tính | Content Fragment (CF) | Experience Fragment (XF) | | ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | **JCR Node Type** | `dam:Asset` | `cq:Page` | | **Vị trí lưu trữ** | `/content/dam/...` | `/content/experience-fragments/...` | | **Định nghĩa từ** | Content Fragment Model | Editable Template | | **Bản chất** | Nội dung thuần không có style (Content without presentation) | Trải nghiệm hoàn chỉnh có layout (Presentation with content) | | **Đầu ra chính** | JSON qua GraphQL / REST API | HTML component nhúng trên trang hoặc kênh ngoài | *** ## 14. Sling Model Exporter & SPA ```java @Model( adaptables = SlingHttpServletRequest.class, adapters = { Cta.class, ComponentExporter.class }, resourceType = "myproject/components/cta", defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL ) @Exporter( name = ExporterConstants.SLING_MODEL_EXPORTER_NAME, // "jackson" extensions = ExporterConstants.SLING_MODEL_EXTENSION // "json" ) @JsonInclude(JsonInclude.Include.NON_NULL) public class CtaImpl implements Cta, ComponentExporter { @JsonProperty("linkUrl") public String getUrl() { ... } @JsonIgnore public String getInternalState() { ... } @Override public String getExportedType() { return "myproject/components/cta"; } } ``` - URL truy cập model JSON: `/content/myproject/en/jcr:content/root/cta.model.json` - Vì có selector `model` và extension `.json`, Dispatcher có thể cache URL này như một file tĩnh. *** ## 15. Multi-Site Manager (MSM) & Translation ### Cấu trúc thư mục chuẩn ```tree /content/myproject/ ├── language-masters/ # Nguồn nội dung gốc do author biên soạn │ ├── en # Master source │ ├── fr # Language copy đã dịch từ en │ └── de # Language copy đã dịch từ en ├── us/en # Live copy từ language-masters/en ├── ca/ │ ├── en # Live copy từ language-masters/en │ └── fr # Live copy từ language-masters/fr └── de/de # Live copy từ language-masters/de ``` ### Hủy kế thừa (Cancellation) - **Property Level:** `cq:propertyInheritanceCancelled = ["title", "heroImage"]` _(Khuyên dùng để chỉ ngắt kế thừa field cụ thể)_. - **Page Level:** Suspend (tạm dừng đồng bộ, có thể resume) hoặc Detach (ngắt vĩnh viễn thành page độc lập). ### Quy trình dịch thuật và triển khai (3 bước) 1. **TRANSLATE**: Dịch từ source language vào language master tương ứng. 2. **ROLL OUT**: Đồng bộ từ language master ra các live copy của từng quốc gia/khu vực (chỉ diễn ra trên Author). 3. **ACTIVATE**: Publish trang đã cập nhật lên môi trường Publish. *** ## 16. Replication & Cloud Distribution ### Classic Replication (AEM 6.5) - **Replication Agents:** Nằm tại `/etc/replication/agents.author/publish`. - **Agent User:** Đọc nội dung trên Author để đóng gói (nếu thiếu quyền sẽ bỏ qua âm thầm). - **Transport User:** Gửi request và ghi nội dung vào Publish (nếu sai password/quyền sẽ gây HTTP 401 và nghẽn toàn bộ replication queue). ### AEM as a Cloud Service (Sling Content Distribution) - Sử dụng mô hình **Pub/Sub (Publish/Subscribe)**. - Author đẩy nội dung vào một pipeline trung gian. Các pod Publish tự động subscribe và pull dữ liệu về. - Khi một pod Publish mới được sinh ra do auto-scale, pod đó sẽ tự động đồng bộ dữ liệu mà không cần cấu hình thêm replication agent. ### The 6-Step Replication Troubleshooting Walk :::tip\[Quy trình kiểm tra khi nội dung không xuất hiện trên Publish] 1. **Was it ACTIVATED?** — Kiểm tra replication status trong Page Properties. 2. **Is the QUEUE blocked?** — Kiểm tra xem có item nào bị lỗi làm nghẽn hàng đợi phía sau không. 3. **Node on PUBLISH?** — Mở cửa sổ ẩn danh truy cập trực tiếp port Publish để loại trừ lỗi Dispatcher. 4. **REFERENCES published?** — Các Content Fragment, Experience Fragment, hoặc Asset nhúng đã được kích hoạt chưa? 5. **DISPATCHER cached?** — Kiểm tra xem cache flush request có được gửi thành công đến Dispatcher không. 6. **CDN cached?** — Kiểm tra tầng cache ngoài cùng trên CDN / Cloudflare. ::: *** ## 17. AEM as a Cloud Service (AEMaaCS) ### So sánh kiến trúc chính | Tiêu chí | AEM 6.5 (On-Prem / AMS) | AEM as a Cloud Service | | ----------------------------- | -------------------------------------- | ---------------------------------------------------------------------- | | **Hệ thống** | Server cố định, tự quản lý nâng cấp | Dịch vụ đám mây, tự động cập nhật liên tục | | **Khả năng mở rộng** | Provisioning thủ công cho giờ cao điểm | Tự động auto-scale số lượng pod Publish theo tải | | **Thư mục `/apps` & `/libs`** | Cho phép ghi tại runtime | **Read-only / Bất biến (Immutable)** tại runtime | | **Cấu hình ACL / Users** | Tạo thủ công qua UI hoặc package | Bắt buộc định nghĩa qua **Repoinit** | | **NodeStore** | Thường dùng TarMK hoặc MongoMK | Author: **DocumentNodeStore (MongoDB)**; Publish: **SegmentNodeStore** | | **Hotfix khẩn cấp** | Có thể patch thẳng code / bundle | **Không có đường tắt hotfix**, mọi thay đổi đều phải qua pipeline Git | ### Cloud Deployment Pipelines 1. **Full-stack Pipeline:** Build và deploy toàn bộ backend Java, frontend, và repository package. 2. **Front-end Pipeline:** Build và deploy nhanh các tài nguyên frontend (JS/CSS) mà không cần build lại toàn bộ Java. 3. **Web-tier Pipeline:** Deploy cấu hình Apache và Dispatcher riêng biệt (rất nhanh). 4. **Config Pipeline:** Áp dụng nhanh các cấu hình hệ thống cụ thể. *** ## 18. Cross-Topic Architectural Rules - **"Works on author, blank on publish"**: Nguyên nhân phổ biến nhất là Author đã authenticated còn Publish là anonymous. Code phụ thuộc vào session privilege mà anonymous không có, hoặc reference content (CF, XF, Asset) chưa từng được publish. - **"A dot is cached, a question mark is not"**: Selectors và extensions (`.model.json`, `.filter.html`) thuộc về URL path nên Dispatcher cache được dễ dàng. Query parameters (`?page=2`) mặc định bỏ qua cache. - **Derived content cần invalidation riêng**: Khi một trang nhúng Experience Fragment hoặc Content Fragment, việc activate Fragment nguồn không tự động flush cache của mọi trang đang nhúng nó. - **Deny beats allow, closest ACL wins**: Không thể bypass một quyền Deny bằng cách gán thêm group khác. - **Không có đường tắt trên Cloud**: Mọi thay đổi đều phải đi qua Git và Cloud Manager Pipeline. Hãy tận dụng Feature Flags cho việc rollout tính năng an toàn.