Page Templates

When creating a page you need to select a template. The page template is used as the base for the new page. The template defines the structure of the resultant page, any initial content and the components that can be used (design properties). This has several advantages:

• Page Templates allow specialized authors to create and edit templates.
  • Such specialized authors are called template authors
  • Template authors must be members of the template-authors group.
• Page Templates retain a dynamic connection to any pages created from them. This ensures that any changes to the template are reflected in the pages themselves.
• Page Templates make the page component more generic so the core page component can be used without customization.

With Page Templates, the pieces that make a page are isolated within components. You can configure the necessary combinations of components in a UI, thereby eliminating the need for a new page component to be developed for each page variation.

This document:

• Gives an overview of creating a Page Template
• Describes the admin/developer tasks required to create editable templates
• Describes the technical underpinnings of editable templates
• Describes how AEM evaluates a template’s availability

Creating a New Template

Creating Page Templates is primarily done with the template console and template editor by a template author. This section gives an overview of this process and follows with a description of what occurs at a technical level.

When creating an editable template you:

1. Create a folder for the templates. This is not mandatory, but is recommended best practice.

2. Select a template type. This is copied to create the template definition.

   NOTE

   A selection of template types are provided out-of-the-box. You can also create your own site-specific template types if necessary.

3. Configure the structure, content policies, initial content, and layout of the new template.

   Structure

   • The structure allows you define components and content for your template.
   • Components defined in the template structure cannot be moved on a resulting page nor deleted from any resulting pages.
   • If you want page authors to be able to add and remove components, add a paragraph system to the template.
   • Components can be unlocked and locked again to allow you to define initial content.

   For details on how a template author defines the structure, see Creating Page Templates.

   For technical details of the structure, see Structure in this document.

   Policies

   • The content policies define the design properties of a component.

     • For example, the components available or minimum/maximum dimensions.

   • These are applicable to the template (and pages created with the template).

   For details on how a template author defines policies, see Creating Page Templates.

   For technical details of policies, see Content Policies in this document.

   Initial Content

   • Initial Content defines content that will appear when a page is first created based on the template.
   • Initial content can then be edited by page authors.

   For details on how a template author defines the structure, see Creating Page Templates.

   For technical details on initial content, see Initial Content in this document.

   Layout

   • You can define the template layout for a range of devices.
   • Responsive layout for templates operates as it does for page authoring.

   For details on how a template author defines the template layout, see Creating Page Templates.

   For technical details on template layout, see Layout in this document.

4. Enable the template, then allow it for specific content trees.

   • A template can be enabled or disabled to make it available or unavailable to page authors.
   • A template can be made available or unavailable for certain page branches.

   For details on how a template author enables a template, see Creating Page Templates.

   For technical details on enabling a template, see Enabling and Allowing a Template for Use in this document

5. Use it to create content pages.

   • When using a template to create a page there is no visible difference and no indication between static and editable templates.
   • For the page author, the process is transparent.

   For details on how a page author uses templates to create a page, see Creating and Organizing Pages.

   For technical details on creating pages with editable templates, see Resultant Content Pages in this document.

Template Folders

For organizing your templates you can use the following folders:

• global
• Site-specific

In a standard AEM instance the global folder already exists in the template console. This holds default templates and acts as a fallback if no policies and/or template-types are found in the current folder. You can add your default templates to this folder or create a folder (recommended).

Template types and policies are inherited across all folders according to the following order of precedence:

1. The current folder
2. Parent(s) of the current folder
3. /conf/global
4. /apps
5. /libs

A list of all allowed entries is created. If any configurations overlap ( path/ label), only the instance closest to the current folder is presented to the user.

To create a folder, you can either do this:

• Programmatically or with CRXDE Lite
• Using the Configuration Browser

Using CRXDE Lite

1. A new folder (under /conf) can be created for your instance either programmatically or with CRXDE Lite.

   The following structure must be used:

   /conf
       <your-folder-name> [sling:Folder]
           settings [sling:Folder]
               wcm [cq:Page]
                   templates [cq:Page]
                   policies [cq:Page]
   

2. You can then define the following properties on the folder root node:

   <your-folder-name> [sling:Folder]

   • Name: jcr:title
   • Type: String
   • Value: The title (for the folder) you want to appear in the Templates console.

3. In addition to the standard authoring permissions and privileges (for example, content-authors) you now need to assign group(s) and define the required access rights (ACLs) for your authors to be able to create templates in the new folder.

   The template-authors group is the default group that must be assigned. See the section ACLs and Groups for details.

Using the Configuration Browser

1. Go to Global Navigation > Tools > Configuration Browser.

   The existing folders are listed to the left including the global folder.

2. Click Create.

3. In the Create Configuration dialog the following fields need to be configured:

   • Title: Provide a title for the configuration folder
   • Editable Templates: Tick to allow for editable templates within this folder

4. Click Create

ACLs and Groups

Once your template folders are created (either via CRXDE or with the Configuration Browser), ACLs must defined for the appropriate groups for the template folders to ensure proper security.

The template folders for the WKND tutorial can be used as an example.

The template-authors Group

The template-authors group is the group used to manage access to templates and comes standard with AEM, but is empty. Users must be added to the group for the project/site.

The following table details the necessary permissions for template editing.

This default template-authors group only covers the project setups, where all template-authors members are allowed to access and author all templates. For more complex setups, where multiple template authors groups are needed to separate access to templates, more custom template authors groups must be created. However the permissions for the template authors groups would still be the same.

Template Type

When creating a template you need to specify a template type:

• Template types effectively provide templates for a template. When creating a template the structure and initial content of the selected template type is used to create to the new template.

  • The template type is copied to create the template.
  • Once the copy has occurred, the only connection between the template and the template type is a static reference for information purposes.

• Template types allow you to define:

  • The resource type of the page component.
  • The policy of the root node, which defines the components allowed in the template editor.
  • It is recommended to define the breakpoints for the responsive grid and setup of the mobile emulator at on the template type.

• AEM provides a small selection of out-of-the-box template types such as HTML5 Page and Adaptive Form Page.

  • Additional examples are provided as a part of the WKND tutorial.

• Template types are typically defined by developers.

The out-of-the box template types are stored under:

• /libs/settings/wcm/template-types

Your site-specific template types should be stored in the comparable location of:

• /apps/settings/wcm/template-types

Definitions for your customized templates types should be stored in user-defined folders (recommended) or alternatively in global. For example:

• /conf/<my-folder-01>/<my-folder-02>/settings/wcm/template-types
• /conf/<my-folder>/settings/wcm/template-types
• /conf/global/settings/wcm/template-types

Creating Template Types

If you have created a template that can serve as the basis of other templates, you can copy this template as a template type.

1. Create a template as you would any Page Template as documented here, which will serve as the basis of your template type.
2. Using CRXDE Lite, copy the created template from the templates node to the template-types node under the template folder.
3. Delete the template from the templates node under the template folder.
4. In the copy of the template that is under the template-types node, delete all cq:template and cq:templateType properties from all jcr:content nodes.

You can also develop your own template type using an example editable template as a basis, available on GitHub.

CODE ON GITHUB

You can find the code of this page on GitHub

• Open aem-sites-example-custom-template-type project on GitHub
• Download the project as a ZIP file

Template Definitions

Definitions for editable templates are stored user-defined folders (recommended) or alternatively in global. For example:

• /conf/<my-folder>/settings/wcm/templates
• /conf/<my-folder-01>/<my-folder-02>/settings/wcm/templates
• /conf/global/settings/wcm/templates

The root node of the template is of type cq:Template with a skeleton structure of:

<template-name>
  initial
    jcr:content
      root
        <component>
        ...
        <component>
  jcr:content
    @property status
  policies
    jcr:content
      root
        @property cq:policy
        <component>
          @property cq:policy
        ...
        <component>
          @property cq:policy
  structure
    jcr:content
      root
        <component>
        ...
        <component>
      cq:responsive
        breakpoints
  thumbnail.png

The main elements are:

• <template-name>

  • [initial](#initial-content)
  • jcr:content
  • [structure](#structure)
  • [policies](#policies)
  • thumbnail.png

jcr:content

This node holds properties for the template:

• Name: jcr:title
• Name: status
  • ``Type: String
  • Value: draft, enabled or disabled

Structure

Defines the structure of the resultant page:

• Is merged with the initial content ( /initial) when creating a page.

• Changes made to the structure are reflected in any pages created with the template.

• The root ( structure/jcr:content/root) node defines the list of components that are available in the resulting page.

  • Components defined in the template structure cannot be moved on or deleted from any resultant pages.
  • After a component is unlocked the editable property is set to true.
  • After a component that already contains content is unlocked, this content is moved to the initial branch.

• The cq:responsive node holds definitions for the responsive layout.

Initial Content

Defines the initial content that a new page will have upon creation:

• Contains a jcr:content node that is copied to any new pages.
• Is merged with the structure ( /structure) when creating a page.
• Any existing pages will not be updated if the initial content is changed after creation.
• The root node holds a list of components to define what is available in the resulting page.
• If content is added to a component in structure mode and that component is subsequently unlocked (or conversely), then this content is used as initial content.

Layout

When editing a template you can define the layout, this uses standard responsive layout.

Content Policies

The content policies define the design properties of a component. For example, the components available or minimum/maximum dimensions. These are applicable to the template (and pages created with the template). Content policies can be created and selected in the template editor.

• The property cq:policy, on the root node
  /conf/<your-folder>/settings/wcm/templates/<your-template>/policies/jcr:content/root
  Provides a relative reference to the content policy for the page’s paragraph system.

• The property cq:policy, on the component-explicit nodes under root, provide links to the policies for the individual components.

• The actual policy definitions are stored under:
  /conf/<your-folder>/settings/wcm/policies/wcm/foundation/components

Page Policies

Page policies allow you to define the content policy for the page (main parsys), in either the template or resultant pages.

Enabling and Allowing a Template for Use

1. Enable the Template

   Before a template can be used it must be enabled by either:

   • Enabling the template from the Templates console.

   • Setting the status property on the jcr:content node.

     • For example, on:
       /conf/<your-folder>/settings/wcm/templates/<your-template>/jcr:content

     • Define the property:

       • Name: status
       • Type: String
       • Value: enabled

2. Allowed Templates

   • Define the Allowed Template path(s) on the Page Properties of the appropriate page or root page of a sub-branch.
   • Set the property:
     cq:allowedTemplates
     On the jcr:content node of the required branch.

   For example, with a value of:

   /conf/<your-folder>/settings/wcm/templates/.*

Resultant Content Pages

Pages created from editable templates:

• Are created with a subtree that is merged from structure and initial in the template

• Have references to information held in the template and template type. This is achieved with a jcr:content node with the properties:

  • cq:template - Provides the dynamic reference to the actual template; enables changes to the template to be reflected on the actual pages.

  • cq:templateType - Provides a reference to the template type.

The above diagram shows how templates, content, and components interrelate:

• Controller - /content/<my-site>/<my-page> - The resultant page that references the template. The content controls the entire process. According to the definitions it accesses the appropriate template and components.
• Configuration - /conf/<my-folder>/settings/wcm/templates/<my-template> - The template and related content policies define the page configuration.
• Model - OSGi bundles - The OSGI bundles implement the functionality.
• View - /apps/<my-site>/components - On both the author and publish environments the content is rendered by components.

When rendering a page:

• Templates:

  • The cq:template property of its jcr:content node is referenced to access the template that corresponds to that page.

• Components:

  • The page component will merge the structure/jcr:content tree of the template with the jcr:content tree of the page.
    • The page component will only allow the author to edit the nodes of the template structure that have been flagged as editable (and any children).
    • When rendering a component on a page, the relative path of that component is taken from the jcr:content node; the same path under the policies/jcr:content node of the template will then be searched.
      • The cq:policy property of this node points to the actual content policy (that is, it holds the design configuration for that component).
        • This lets you have multiple templates that re-use the same content policy configurations.

Template Availability

When creating a page in the site admin interface, the list of available templates depends on the location of the new page and the restrictions on placement specified in each template.

The following properties determine whether a template T is allowed to be used for a new page to be placed as a child of page P. Each of these properties is a multi-value string holding zero or more Regular Expressions that are used for matching with paths:

• The cq:allowedTemplates property of the jcr:content subnode of P or an ancestor of P.

• The allowedPaths property of T.

• The allowedParents property of T.

• The allowedChildren property of the template of P.

The evaluation works as follows:

• The first non-empty cq:allowedTemplates property found while ascending the page hierarchy starting with P is matched against the path of T. If none of the values match, T is rejected.

• If T has a non-empty allowedPaths property, but none of the values match the path of P, T is rejected.

• If both of the above properties are either empty or non-existent, T is rejected unless it belongs to the same application as P. T belongs to the same application as P if and only if the name of the second level of the path of T is the same as the name of the second level of the path of P. For example, the template /apps/wknd/templates/foo belongs to the same application as the page /content/wknd.

• If T has an non-empty allowedParents property, but none of the values match the path of P, T is rejected.

• If the template of P has a non-empty allowedChildren property, but none of the values match the path of T, T is rejected.

• In all other cases, T is allowed.

The following diagram depicts the template evaluation process:

Limiting templates used in child pages

To limit what templates can be used to create child pages under a given page, use the cq:allowedTemplates property of jcr:content node of the page to specify the list of templates to be allowed as child pages. Each value in the list must be an absolute path to a template for an allowed child page, for example, /apps/wknd/templates/page-content.

You can use the cq:allowedTemplates property on the template’s jcr:content node to have this configuration applied to all created pages that use this template.

If you want to add more constraints, for example, regarding the template hierarchy, you can use the allowedParents/allowedChildren properties on the template. You can then explicitly specify that pages created from a template T have to be parents/children of pages created from a template T.