In this chapter, let’s explore the relationship between a base page component and editable templates. Learn to build out an unstyled Article template based on some mockups from Adobe XD. In the process of building out the template, Core Components and advanced policy configurations of the Editable Templates are covered.
Review the required tooling and instructions for setting up a local development environment.
If you successfully completed the previous chapter, you can reuse the project and skip the steps for checking out the starter project.
Check out the base-line code that the tutorial builds on:
Check out the tutorial/pages-templates-start
branch from GitHub
$ cd ~/code/aem-guides-wknd
$ git checkout tutorial/pages-templates-start
Deploy code base to a local AEM instance using your Maven skills:
$ mvn clean install -PautoInstallSinglePackage
If using AEM 6.5 or 6.4, append the classic
profile to any Maven commands.
$ mvn clean install -PautoInstallSinglePackage -Pclassic
You can always view the finished code on GitHub or check out the code locally by switching to the branch tutorial/pages-templates-solution
.
In this part of the tutorial, you build a new Article Page Template that can be used to create article pages and aligns with a common structure. The Article Page Template is based on designs and a UI Kit produced in Adobe XD. This chapter is only focused on building out the structure or skeleton of the template. No styles are implemented but the template and pages are functional.
Usually, planning for a new website starts with mockups and static designs. Adobe XD is a design tool building user experience. Next let’s inspect a UI Kit and mockups to help plan the structure of the Article Page Template.
Download the WKND Article Design File.
A generic AEM Core Components UI Kit is also available as a starting point for custom projects.
When creating a page you must select a template, which is used as the basis for creating the page. The template defines the structure of the resultant page, initial content, and allowed components.
There are three main areas of Editable Templates:
Next, create a template in AEM that matches the structure of the mockups. This occurs in a local instance of AEM. Follow the steps in the video below:
High-level steps for the video above:
/content/experience-fragments/wknd/us/en/site/header/master
.header
. The header
element is targeted with CSS in the next chapter./content/experience-fragments/wknd/us/en/site/footer/master
.footer
. The footer
element is targeted with CSS in the next chapter.main
. The main
element is targeted with CSS in the next chapter.H4
.H5
.View the template in the Template console by navigating to http://localhost:4502/libs/wcm/core/content/sites/templates.html/conf/wknd
Enable the Article Page template.
Edit the properties of the Article Page template and upload the following thumbnail to quickly identify pages created using the Article Page template:
A common practice when creating global content, such as a header or footer, is to use an Experience Fragment. Experience Fragments, allows users to combine multiple components to create a single, reference-able, component. Experience Fragments have the advantage of supporting multi-site management and localization.
The AEM Project Archetype generated a Header and Footer. Next, update the Experience Fragments to match the mockups. Follow the steps in the video below:
High-level steps for the video above:
/content/wknd/us/en
the Home page./content/wknd/us/en
the Home page.Next, create a page using the Article Page template. Author the content of the page to match the site mockups. Follow the steps in the video below:
High-level steps for the video above:
/content/wknd/us/en/magazine
.At this point, the article page is clearly unstyled. However the basic structure is in place. Next, inspect the node structure of the article page to gain a better understanding of the role of the template, page, and components.
Use the CRXDE-Lite tool on a local AEM instance to view the underlying node structure.
Open CRXDE-Lite and use the tree navigation to navigate to /content/wknd/us/en/magazine/guide-la-skateparks
.
Click on the jcr:content
node beneath the la-skateparks
page and view the properties:
Notice the value for cq:template
, which points to /conf/wknd/settings/wcm/templates/article-page
, the Article Page Template created earlier.
Also notice the value of sling:resourceType
, which points to wknd/components/page
. This is the page component created by the AEM project archetype and is responsible for rendering page based on the template.
Expand the jcr:content
node beneath /content/wknd/us/en/magazine/guide-la-skateparks/jcr:content
and view the node hierarchy:
You should be able to loosely map each of the nodes to components that were authored. See if you can identify the different Layout Containers used by inspecting the nodes prefixed with container
.
Next inspect the page component at /apps/wknd/components/page
. View the component properties in CRXDE Lite:
There are only two HTL scripts, customfooterlibs.html
and customheaderlibs.html
beneath the page component. So how does this component render the page?
The sling:resourceSuperType
property points to core/wcm/components/page/v2/page
. This property allows the WKND’s page component to inherit all the functionality of the Core Component page component. This is the first example of something called the Proxy Component Pattern. More information can be found here.
Inspect another component within the WKND components, the Breadcrumb
component from: /apps/wknd/components/breadcrumb
. Notice that the same sling:resourceSuperType
property can be found, but this time it points to core/wcm/components/breadcrumb/v2/breadcrumb
. This is another example of using the Proxy component pattern to include a Core Component. In fact, all the components in the WKND code base are proxies of AEM Core Components (except for the custom demo HelloWorld component). It is a best practice to reuse as much of the functionality of Core Components as possible before writing custom code.
Next inspect the Core Component Page at /libs/core/wcm/components/page/v2/page
using CRXDE Lite:
In, AEM 6.5/6.4 the Core Components are located under /apps/core/wcm/components
. In, AEM as a Cloud Service, the Core Components are located under /libs
and are updated automatically.
Notice that many script files are included beneath this page. The Core Component Page contains numerous functionalities. This functionality is broken into multiple scripts for easier maintenance and readability. You can trace the inclusion of the HTL scripts by opening the page.html
and looking for data-sly-include
:
<!--/* /libs/core/wcm/components/page/v2/page/page.html */-->
<!DOCTYPE HTML>
<html data-sly-use.page="com.adobe.cq.wcm.core.components.models.Page" lang="${page.language}"
data-sly-use.head="head.html"
data-sly-use.footer="footer.html"
data-sly-use.redirect="redirect.html">
<head data-sly-call="${head.head @ page = page}"></head>
<body class="${page.cssClassNames}"
id="${page.id}"
data-cmp-data-layer-enabled="${page.data ? true : false}">
<script data-sly-test.dataLayerEnabled="${page.data}">
window.adobeDataLayer = window.adobeDataLayer || [];
adobeDataLayer.push({
page: JSON.parse("${page.data.json @ context='scriptString'}"),
event:'cmp:show',
eventInfo: {
path: 'page.${page.id @ context="scriptString"}'
}
});
</script>
<sly data-sly-test.isRedirectPage="${page.redirectTarget && (wcmmode.edit || wcmmode.preview)}"
data-sly-call="${redirect.redirect @ redirectTarget = page.redirectTarget}"></sly>
<sly data-sly-test="${!isRedirectPage}">
<sly data-sly-include="body.skiptomaincontent.html"></sly>
<sly data-sly-include="body.socialmedia_begin.html"></sly>
<sly data-sly-include="body.html"></sly>
<sly data-sly-call="${footer.footer @ page = page}"></sly>
<sly data-sly-include="body.socialmedia_end.html"></sly>
</sly>
</body>
</html>
The other reason for breaking out the HTL into multiple scripts is to allow the proxy components to override individual scripts to implement custom business logic. The HTL scripts customfooterlibs.html
, and customheaderlibs.html
, are created for the explicit purpose to be overridden by implementing projects.
You can learn more about how the Editable Template factors into the rendering of the content page by reading this article.
Inspect another Core Component, like the Breadcrumb at /libs/core/wcm/components/breadcrumb/v2/breadcrumb
. View the breadcrumb.html
script to understand how the markup for the Breadcrumb component is ultimately generated.
Often, especially at the beginning of an AEM project it is valuable to persist configurations, like templates and related content policies, to source control. This ensures that all developers are working against the same set of content and configurations and can ensure additional consistency between environments. Once a project reaches a certain level of maturity, the practice of managing templates can be turned over to a special group of power users.
For now, templates are treated like other pieces of code and sync the Article Page Template down as part of the project.
Until now code is pushed from the AEM project to a local instance of AEM. The Article Page Template was created directly on a local instance of AEM, so it needs to import the template into the AEM project. The ui.content module is included in the AEM project for this specific purpose.
The next few steps are done in the VSCode IDE using the VSCode AEM Sync plugin. But they could be doing using any IDE that you have configured to import or import content from a local instance of AEM.
In, the VSCode open the aem-guides-wknd
project.
Expand the ui.content module in the Project explorer. Expand the src
folder and navigate to /conf/wknd/settings/wcm/templates
.
Right+Click the templates
folder and select Import from AEM Server:
The article-page
should be imported, and the page-content
, xf-web-variation
templates should also be updated.
Repeat the steps to import content but select the policies folder from /conf/wknd/settings/wcm/policies
.
Inspect the filter.xml
file from ui.content/src/main/content/META-INF/vault/filter.xml
.
<!--ui.content filter.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<workspaceFilter version="1.0">
<filter root="/conf/wknd" mode="merge"/>
<filter root="/content/wknd" mode="merge"/>
<filter root="/content/dam/wknd" mode="merge"/>
<filter root="/content/experience-fragments/wknd" mode="merge"/>
</workspaceFilter>
The filter.xml
file is responsible for identifying the paths of nodes that are installed with the package. Notice the mode="merge"
on each of the filters which indicates that existing content not to be modified, only new content is added. Since content authors may be updating these paths, it is important that a code deployment does not overwrite content. See the FileVault documentation for more details on working with filter elements.
Compare ui.content/src/main/content/META-INF/vault/filter.xml
and ui.apps/src/main/content/META-INF/vault/filter.xml
to understand the different nodes managed by each module.
In order to ensure consistent deployments for the WKND Reference site some branches of the project are set up such that ui.content
overwrites any changes in the JCR. This is by design, i.e for Solution Branches, since code/styles are written for specific policies.
Congratulations, you have created a template and page with Adobe Experience Manager Sites.
At this point, the article page is clearly unstyled. Follow the Client-Side Libraries and Front-end Workflow tutorial to learn the best practices for including CSS and JavaScript to apply global styles to the site and integrate a dedicated front-end build.
View the finished code on GitHub or review and deploy the code locally at on the Git branch tutorial/pages-templates-solution
.
tutorial/pages-templates-solution
branch.