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:
template-authors
group.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:
This document assumes that you are already familiar with creating and editing templates. See the authoring document Creating Page Templates, which details the capabilities of editable templates as exposed to the template author.
The WKND tutorial goes into depth into how to use Page Templates by implementing an example and is quite useful for understanding how to set up a template in a new project
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 a new editable template you:
Create a folder for the templates. This is not mandatory, but is recommended best practice.
Select a template type. This is copied to create the template definition.
A selection of template types are provided out-of-the-box. You can also create your own site-specific template types if required.
Configure the structure, content policies, initial content, and layout of the new template.
Structure
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.
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
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
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.
Enable the template, then allow it for specific content trees.
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
Use it to create content pages.
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.
Never enter any information that needs to be internationalized into a template. For internalization purposes, the localization features of the Core Components are recommended.
Templates are powerful tools to streamline your page creation workflow. However too many templates can overwhelm the authors and make page creation confusing. A good rule of thumb is to keep the number of templates under 100.
Adobe does not recommend having more than 1000 templates due to potential performance impacts.
The editor client library assumes the presence of the cq.shared
namespace in content pages, and if it is absent the JavaScript error Uncaught TypeError: Cannot read property 'shared' of undefined
will result.
All sample content pages contain cq.shared
, so any content based on them automatically includes cq.shared
. However, if you decide to create your own content pages from scratch without basing them on sample content, you must make sure to include the cq.shared
namespace.
See Using Client-Side Libraries for further information.
For organizing your templates you can use the following folders:
global
Even though you can nest your folders, when the user views them in the Templates console they are presented as a flat structure.
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 new folder (recommended).
It is best practice to create a new folder to hold your customized templates and not to use the global
folder.
Folders must be created by a user with admin
rights.
Template types and policies are inherited across all folders according to the following order of precedence:
/conf/global
/apps
/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 new folder, you can either do this:
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]
You can then define the following properties on the folder root node:
<your-folder-name> [sling:Folder]
jcr:title
String
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 needs to be assigned. See the section ACLs and Groups for details.
Go to Global Navigation -> Tools > Configuration Browser.
The existing folders are listed to the left including the global
folder.
Click Create.
In the Create Configuration dialog the following fields need to be configured:
Click Create
In the Configuration Browser, you can edit the global folder and activate the Editable Templates option if you wish to create templates within this folder, however this is not recommended best practice.
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 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 template-authors
group is only for users that must be able to create new templates.
Editing templates is very powerful and if not done properly existing templates can be broken. Therefore this role should be focused and only include qualified users.
The following table details the necessary permissions for template editing.
Path | Role / Group | Permissions |
Description |
---|---|---|---|
/conf/<your-folder>/settings/wcm/templates |
Template Authors |
read, write, replicate | Template authors that create, read, update, delete, and replicate templates in site specific /conf space |
Anonymous Web User | read | Anonymous Web User must read templates while rendering a page | |
Content Authors | replicate | replicateContent authors need to activate the templates of a page when activating a page | |
/conf/<your-folder>/settings/wcm/policies |
Template Author |
read, write, replicate | Template authors that create, read, update, delete, and replicate templates in site specific /conf space |
Anonymous Web User | read | Anonymous Web User must read policies while rendering a page | |
Content Authors | replicate | Content authors need to activate the policies of a template of a page when activating a page | |
/conf/<site>/settings/template-types |
Template Author | read | Template author creates a new template based on one of the predefined template types. |
Anonymous Web User | none | Anonymous Web User must not access the template types |
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.
When creating a new template you need to specify a template type:
Template types effectively provide templates for a template. When creating a new template the structure and initial content of the selected template type is used to create to the new template.
Template types allow you to define:
AEM provides a small selection of out-of-the-box template types such as HTML5 Page and Adaptive Form Page.
Template types are typically defined by developers.
The out-of-the box template types are stored under:
/libs/settings/wcm/template-types
You must not change anything in the /libs
path. This is because the content of /libs
can be overwritten at any time by an update to AEM.
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
The template types have to respect the correct folder structure (i.e. /settings/wcm/...
), otherwise the template types will not be found.
If you have created a template that can serve as the basis of other templates, you can copy this template as a template type.
templates
node to the template-types
node under the template folder.templates
node under the template folder.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
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
This node holds properties for the template:
jcr:title
status
String
draft
, enabled
or disabled
Defines the structure of the resultant page:
Is merged with the initial content ( /initial
) when creating a new page.
Changes made to the structure will be reflected in any pages created with the template.
The root
( structure/jcr:content/root
) node defines the list of components that will be available in the resulting page.
editable
property is set to true
.initial
branch.The cq:responsive
node holds definitions for the responsive layout.
Defines the initial content that a new page will have upon creation:
jcr:content
node that is copied to any new pages./structure
) when creating a new page.root
node holds a list of components to define what will be available in the resulting page.When editing a template you can define the layout, this uses standard responsive layout.
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
The paths of policy definitions depend on the path of the component. cq:policy
holds a relative reference to the configuration itself.
Page policies allow you to define the content policy for the page (main parsys), in either the template or resultant pages.
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:
enabled
Allowed Templates
cq:allowedTemplates
jcr:content
node of the required branch.For example, with a value of:
/conf/<your-folder>/settings/wcm/templates/.*
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:
/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./conf/<my-folder>/settings/wcm/templates/<my-template>
- The template and related content policies define the page configuration./apps/<my-site>/components
- On both the author and publish environments the content is rendered by components.When rendering a page:
Templates:
cq:template
property of its jcr:content
node will be referenced to access the template that corresponds to that page.Components:
structure/jcr:content
tree of the template with the jcr:content
tree of the page.
jcr:content
node; the same path under the policies/jcr:content
node of the template will then be searched.
cq:policy
property of this node points to the actual content policy (i.e. it holds the design configuration for that component).
When creating a new 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:
AEM offers multiple properties to control the templates allowed under Sites. However, combining them can lead to very complex rules that are difficult to track and manage.
Therefore, Adobe recommends that you start simple, by defining:
only the cq:allowedTemplates
property
only on the site root
For an example, see the WKND tutorial content: /content/wknd/jcr:content
The properties allowedPaths
, allowedParents
, and allowedChildren
can also be placed on the templates to define more sophisticated rules. However, when possible, it is much simpler to define further cq:allowedTemplates
properties on sub-sections of the site if there is a need to further restrict the allowed templates.
An additional advantage is that the cq:allowedTemplates
properties can be updated by an author in the Advanced tab of the Page Properties. The other template properties cannot be updated using the (standard) UI, so would need a developer to maintain the rules and a code deployment for every change.
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 newly 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.