In this chapter we will explore the relationship between a base page component and editable templates. We will build out an un-styled Article template based on some mockups from AdobeXD. 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 re-use the project and skip the steps for checking out the starter project.
Check out the base-line code 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 the code out locally by switching to the branch tutorial/pages-templates-solution
.
In this part of the tutorial, you will build a new Article Page Template that can be used to create new article pages and aligns with a common structure. The Article Page Template will be based on designs and a UI Kit produced in AdobeXD. This chapter is only focused on building out the structure or skeleton of the template. No styles will be implemented but the template and pages will be functional.
In most cases, planning for a new website starts with mockups and static designs. Adobe XD is a design tool building user experiences. Next we will inspect a UI Kit and mockups to help plan the structure of the Article Page Template.
Download the WKND Article Design File.
When creating a page you must select a template, which will be used as the basis for creating the new page. The template defines the structure of the resultant page, initial content, and allowed components.
There are 3 main areas of Editable Templates:
Next, create a new template in AEM that matches the structure of the mockups. This will occur in a local instance of AEM. Follow the steps in the video below:
High level steps for the video below:
/content/experience-fragments/wknd/us/en/site/header/master
.header
. The header
element will be targeted with CSS in the next chapter./content/experience-fragments/wknd/us/en/site/footer/master
.footer
. The footer
element will be targeted with CSS in the next chapter.main
. The main
element will be 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 below:
/content/wknd/us/en
the Home page./content/wknd/us/en
the Home page.Next, create a new 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 below:
/content/wknd/us/en/magazine
.At this point the article page is clearly un-styled. 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 we 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:
Note that there are only 2 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 of 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 located at: /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 of the components in the WKND code base are proxies of AEM Core Components (except for our famous HelloWorld component). It is a best practice to try and re-use 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 more scripts are included beneath this page. The Core Component Page contains a lot of functionality. 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 the 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.
In many cases, 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 we will treat the templates like other pieces of code and sync the Article Page Template down as part of the project. Up until now we have pushed code from our AEM project to a local instance of AEM. The Article Page Template was created directly on a local instance of AEM, so we need to import the template into our AEM project. The ui.content module is included in the AEM project for this specific purpose.
The next few steps will take place using the VSCode IDE using the VSCode AEM Sync plugin but 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 located at /conf/wknd/settings/wcm/policies
.
Inspect the filter.xml
file located at 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 will be installed with the package. Notice the mode="merge"
on each of the filters which indicates that existing content will not 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 setup such that ui.content
will overwrite any changes in the JCR. This is by design, i.e for Solution Branches, since code/styles will be written for specific policies.
Congratulations, you have just created a new template and page with Adobe Experience Manager Sites.
At this point the article page is clearly un-styled. 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 brach tutorial/pages-templates-solution
.
tutorial/pages-templates-solution
branch.