5.1 Editable Templates, Structure, Initial Content & Content Policies

5.1 Editable Templates, Structure, Initial Content & Content Policies

Exam Focus: AEM Editable Templates are a cornerstone of modern AEM Sites architecture and are heavily emphasized on the AD0-E128 exam. Candidates must master the architectural divergence between legacy static templates (/apps) and modern editable templates (/conf), the internal repository anatomy of an editable template (structure, initial, policies), the exact behavior of locked vs. unlocked structure components, layout container configuration (responsivegrid and breakpoints), the template lifecycle (Draft, Enabled, Disabled), and how Content Policies configured via Design Dialogs (cq:design_dialog) govern component availability and design options.

---

Editable Templates vs. Legacy Static Templates

In legacy AEM development (pre-AEM 6.2 and early 6.x systems), pages were generated using Static Templates. Understanding the limitations of static templates illuminates why Adobe introduced editable templates and why static templates are considered an anti-pattern in modern cloud architectures.

The Core Limitations of Static Templates

Under the legacy static template model, whenever business teams needed a new page layout, a developer was required to create a new cq:Template node under /apps, author a corresponding page rendering component, define its layout structure in JSP or HTL scripts, commit the code to version control, and trigger a CI/CD build. Furthermore, styling options and allowed components were managed using Design Mode, which wrote configurations to /etc/designs. Because /etc/designs resided in mutable JCR space without granular tenant isolation, multi-site deployments frequently suffered from policy collisions and unmanageable code merges.

Editable Templates completely eliminate developer dependency for layout and governance. Developers build atomic Core Components and template types; template authors then assemble, style, and govern templates dynamically through the browser UI.

---

Repository Anatomy of an Editable Template

Editable templates reside inside tenant configuration folders under /conf/<my-app>/settings/wcm/templates/<template-name>. A complete editable template consists of a standardized node hierarchy:

+ /conf/my-app/settings/wcm/templates/article-page
    - jcr:primaryType = "cq:Template"
    + jcr:content
        - jcr:primaryType = "cq:PageContent"
        - jcr:title = "Article Page"
        - status = "enabled"
        - cq:templateType = "/conf/my-app/settings/wcm/template-types/page-type"
    + structure
        - jcr:primaryType = "cq:Page"
        + jcr:content
            - jcr:primaryType = "cq:PageContent"
            - sling:resourceType = "my-app/components/page"
            + root
                - jcr:primaryType = "nt:unstructured"
                - sling:resourceType = "wcm/foundation/components/responsivegrid"
                - editable = "true"
                + header
                    - sling:resourceType = "my-app/components/header"
                + footer
                    - sling:resourceType = "my-app/components/footer"
    + initial
        - jcr:primaryType = "cq:Page"
        + jcr:content
            - jcr:primaryType = "cq:PageContent"
            - sling:resourceType = "my-app/components/page"
            + root
                + title
                    - sling:resourceType = "my-app/components/title"
                + teaser
                    - sling:resourceType = "my-app/components/teaser"
    + policies
        - jcr:primaryType = "nt:unstructured"
        + jcr:content
            + root
                - cq:policy = "my-app/components/container/policy_article_root"
    + thumbnail.png (nt:file)

1. The Structure Node (/structure)

The /structure subtree defines the permanent, non-negotiable skeleton of pages created from the template. It contains two types of structural elements:

• Locked Components: Any component placed in /structure that remains locked (the default state) cannot be deleted, moved, or reconfigured by content authors on individual pages. Typical examples include global navigation headers, brand breadcrumbs, and site footers. A change to a locked component in /structure is inherited by pages that use the template. For Publish delivery, the changed template or /conf content must be published through the supported process and affected caches must be invalidated; editing Author does not bypass publication.
• Unlocked Layout Containers / Components: When a template author unlocks a component or layout container (by clicking the padlock icon in the Template Editor to set editable="true"), that container becomes an authorable region on created pages. Authors can add, reorder, resize, and delete components inside that unlocked container on individual pages.

2. The Initial Content Node (/initial)

The /initial subtree defines the default starting content and boilerplate components that appear on a page when an author creates it via the Create Page wizard.

• When a new page is created under /content, AEM's page creation service copies the child nodes of /initial/jcr:content into the new page's jcr:content node.
• Once created, the content on the child page is completely severed from /initial. Authors can edit text, replace images, or delete initial components altogether.
• Crucial Exam Rule: If a template author alters or adds components to /initial on an existing template, those changes only affect newly created pages. Existing pages created prior to the change will not receive the updated initial content. This behavior stands in stark contrast to /structure, where changes propagate instantaneously to all existing pages.

3. The Policies Node (/policies)

The /policies subtree acts as a routing lookup table. It maps specific component resource types or container paths within the template to concrete Content Policy definitions stored under /conf/<my-app>/settings/wcm/policies. For example, /policies/jcr:content/root specifies the cq:policy property pointing to the container policy that dictates which component groups authors are permitted to insert into the root responsive grid.

4. Template Thumbnail (thumbnail.png)

The thumbnail.png file (recommended size: 300x200 pixels) provides the visual preview card rendered in the AEM Sites console when an author selects a template during the page creation process.

---

Template Types (template-types)

Template authors cannot create an editable template from a complete blank slate; they must initialize it from a Template Type. Template types act as the foundational prototype or "template for a template."

• Located under /conf/<my-app>/settings/wcm/template-types (or inherited from core libraries under /libs/settings/wcm/template-types).
• Created and maintained by developers in source control (ui.content package).
• Contains baseline /initial, /structure, and /policies definitions, along with a thumbnail.png and cq:dialog.
• When a template author navigates to Tools > General > Templates and clicks Create, the wizard displays available Template Types. Selecting a type instantiates a new editable template under /conf, cloning the prototype structure into the new template node.

---

Layout Container Configuration & Responsive Grid

Modern AEM page layouts are powered by the Layout Container Core Component (wcm/foundation/components/responsivegrid). The layout container provides a dynamic, browser-based grid mechanism that eliminates fixed CSS table layouts.

The 12-Column Grid Architecture

By default, AEM's responsive grid uses a 12-column system. In the Page Editor or Template Editor, authors can toggle Layout Mode to manipulate components interactively:

1. Resizing (Spans): Authors drag the edge handles of a component to dictate how many columns it spans (e.g., spanning 6 columns creates a 50% split in a 12-column grid).
2. Offsetting: Authors drag components horizontally to introduce column offsets (empty leading columns).
3. Viewport Breakpoints: AEM defines standard responsive breakpoints (typically Phone, Tablet, and Desktop). In Layout Mode, authors switch viewport views in the editor toolbar and customize spans, offsets, or component visibility independently for each screen size.

JCR Representation of Responsive Grid

When an author customizes component widths or visibility across breakpoints, AEM writes child metadata nodes under cq:responsive directly on the component's content node:

+ teaser
    - sling:resourceType = "my-app/components/teaser"
    + cq:responsive
        - jcr:primaryType = "nt:unstructured"
        + default
            - jcr:primaryType = "nt:unstructured"
            - width = "12"
        + tablet
            - jcr:primaryType = "nt:unstructured"
            - width = "6"
            - offset = "0"
        + phone
            - jcr:primaryType = "nt:unstructured"
            - width = "12"
            - behavior = "hide"

If behavior = "hide" is set for a specific breakpoint, AEM's responsive grid client library automatically applies the corresponding CSS utility class (such as aem-Grid--phone--hide) to conceal the DOM element on mobile devices.

---

Template Lifecycle and Status Workflow

Editable templates operate within a three-state lifecycle that governs author access:

  [ Draft ]  ======== Enable ========>  [ Enabled ]
     ^                                       |
     |                                    Disable
     |                                       |
     +============ (Edit) ================== v
                                       [ Disabled ]

1. Draft: When a template is first created or being heavily modified, its status is draft. In this state, template authors can freely configure structure, initial content, and policies. It is hidden from the Sites Page Creation console; regular content authors cannot view or select it.
2. Enabled: Once the template author finalizes the design, they select Enable from the console. The template's status property becomes enabled. It immediately appears as an available template option in the Create Page wizard for all site branches whose governance rules permit it.
3. Disabled: If a template becomes deprecated or must be temporarily retired, administrators choose Disable. A disabled template is hidden from the Create Page wizard, preventing the creation of new pages. However, existing pages built with this template continue to function and render normally.

---

Content Policies (wcm/core/components/policy)

Content Policies replace legacy Design Mode and define the behavioral rules, styling capabilities, and component whitelists for components across templates. Policies are stored centrally under /conf/<my-app>/settings/wcm/policies.

Edit Dialog (cq:dialog) vs. Design Dialog (cq:design_dialog)

Understanding the exact mechanical distinction between edit dialogs and design dialogs is an absolute necessity for the AD0-E128 exam:

• Edit Dialog (cq:dialog):
  • Rendered when a content author clicks the wrench icon on a component instance in the Page Editor.
  • Manages component content (e.g., text copy, image asset path, CTA link).
  • Saves properties directly to the component instance node under /content/.../jcr:content/....
• Design Dialog (cq:design_dialog):
  • Rendered when a template author clicks the policy icon (shield with slider) on a component or layout container in the Template Editor.
  • Manages component capabilities, allowed features, and style options (e.g., allowed heading levels for Title, image cropping presets, allowed component groups for a container).
  • Saves configuration properties to a policy node under /conf/<my-app>/settings/wcm/policies/....

Layout Container Policies: Restricting Allowed Components

When a template author opens the policy for an unlocked Layout Container, they configure the Allowed Components tab. Here, they select which component groups (e.g., MyProject - Content, MyProject - Teasers) or individual components are permitted inside that container.

When an author opens a page in the Page Editor and clicks the "+" (Insert Component) button inside that container, AEM filters the displayed component list strictly according to the container's policy. If a component group is not whitelisted in the policy, authors cannot insert it.

Component-Specific Policies

Individual components utilize policies to enforce design governance and brand consistency:

• Title Component Policy: Restricts allowed HTML heading tags. A template author can enforce that authors may only choose <h2>, <h3>, and <h4>, disallowing <h1> to protect the page's primary SEO heading.
• Image Component Policy: Defines allowed MIME types, enables/disables WebP delivery, defines maximum file upload sizes, and sets mandatory responsive crop aspect ratios (e.g., 16:9, 4:3, 1:1).
• Text Component Policy: Restricts Rich Text Editor (RTE) plugins. An administrator can enable basic bold/italic formatting and disable raw HTML editing or table creation.
• Style System: The policy defines available CSS classes grouped by category (e.g., "Theme: Dark", "Theme: Light", "Card: Elevated"). Content authors can select these styles from a dropdown paintbrush menu in the Page Editor without touching custom CSS.

---

Template Governance: cq:allowedTemplates

Even when an editable template is set to Enabled, it does not automatically appear on every site across an AEM enterprise instance. Template availability is strictly governed by the cq:allowedTemplates property.

The cq:allowedTemplates Multi-String Property

Administrators configure cq:allowedTemplates on the jcr:content node of a site root (e.g., /content/my-app/us/en/jcr:content):

<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0"
    jcr:primaryType="cq:PageContent"
    jcr:title="English"
    cq:allowedTemplates="[/conf/my-app/settings/wcm/templates/.*]">
</jcr:root>

• The value is an array of regular expressions matching allowed template paths.
• [/conf/my-app/settings/wcm/templates/.*] permits all enabled templates residing inside the my-app configuration folder.
• To exclude specific templates (such as experience fragment templates), administrators use negative lookahead regex patterns (e.g., /conf/my-app/settings/wcm/templates/(?!xf-).*).
• AEM evaluates cq:allowedTemplates hierarchically: if a child page branch does not define the property, Sling traverses up the content tree to the closest ancestor page that specifies it.

---

Migration Considerations: Static to Editable Templates

When enterprise customers migrate legacy codebases to AEM as a Cloud Service, converting appropriate legacy static templates to editable templates is the recommended modernization path. The migration lifecycle involves:

1. Auditing Legacy /etc/designs: Extract design mode configurations from /etc/designs/<my-app> and translate them into Content Policy definitions under /conf/<my-app>/settings/wcm/policies.
2. Synthesizing Template Types: Create foundational template types in source control containing standard page layouts (header, responsive root, footer).
3. Creating Editable Templates: Reconstruct page templates in /conf, locking structural components and establishing responsive containers.
4. Refactoring Page Content: Existing page nodes in /content must have their cq:template property updated to point to the new /conf template path, and their page components updated to use modern responsive container nodes.
5. AEM Modernize Tools Suite: Adobe provides the open-source AEM Modernize Tools suite, which automates the conversion of static templates, design dialogs, and component nodes to editable templates and Core Component proxies.