A lot of our customers still rely on the Classic UI for authoring updates. This means the sites implementation doesn't use many of the latest features of the AEM product. Other customers may be operating in the Touch-Enabled UI, but they are still developing new content using static templates. Updating to Editable Templates requires review, planning, and a properly executed project. This lab is intended to help jump start that process, providing guidance and tools to reduce the effort to modernize your AEM Sites implementations.
In this lab, we will learn about the process of migrating Experience Manager Sites pages. First, we will review a site implemented using legacy static templates and plan a migration to modern editable template-based pages. Using this information, we will analyze the existing content for changes necessary to migrate to a new template. Then we will update the pages, to leverage the responsive grid, policies, and Touch-enabled UI capabilities in AEM. From there we will explore how to update code and configurations, making them compatible with modern AEM Sites development paradigms. Finally, we will adjust existing content to work with the updated code.
We will see how the new aem-modernize-tools can help us achieve all this so easily.
Identify & review considerations for converting static template to editable templates
Analyze existing content for changes necessary to migrate to new template structure
Update a template to use new AEM patterns & components (hands-on)
Convert components to AEM Core Components (hands-on)
Update Classic dialog to Coral 3 Dialog (hands-on)
AEM 6.5 GA
All other files/code are provided in the resources directory.
To set up an AEM instance using Maven.
This lesson sets up the AEM and software necessary for the remaining lessons.
You can download all packages (resources.zip) using:
https://expleague.azureedge.net/labs/L761/resources.zip
The following steps use Maven to install the provided software to your local AEM instance. You can instead upload these files to the Package Manager, if you would prefer to use the GUI.
Open the Terminal application
Change the working directory to the resources folder:
This command assumes that you have checked out the GitHub repository to a folder named Meetup-2019 on your desktop. Replace this path with the correct one based on where you may have checked-out the Git repository.
$ cd ~/Desktop/Meetup-2019/resources
Install the legacy default designs.
$ mvn com.day.jcr.vault:content-package-maven-plugin:install -Dvault.file=./default-design.zip
Install the provided Geometrixx Shapes content package on both Author and Publish instance.
$ mvn com.day.jcr.vault:content-package-maven-plugin:install -Dvault.file=./cq-geometrixx-pkg-5.11.11-SNAPSHOT.zip
Install the AEM Modernization Tool kit.
$ mvn com.day.jcr.vault:content-package-maven-plugin:install -Dvault.file=./aem-modernize-tools-content-0.0.1-SNAPSHOT.zip
Install the Lab Demo code.
$ mvn com.day.jcr.vault:content-package-maven-plugin:install -Dvault.file=./summit-l761-geodemo.ui.apps-0.0.1-SNAPSHOT.zip
Create an Editable Template matching the existing page structure.
Use the Tool to migrate existing Page to the new Editable Template.
This lesson reviews an existing site which was implemented using Static Templates and identifies the appropriate steps to migrate them to Editable Templates. Subsequently, we'll use the Page Template/Structure Conversion Tool to convert a page.
The Geometrixx Shapes team has decided to upgrade their Static Templates to the new AEM Editable Templates. They want to start with converting the Home Page template over to a new structure. They've already set up an initial code using the Adobe Maven AEM Archetype. The next steps are to:
Create a template for the Home Page derived from a base template.
Configure the Home Page template for containers, policies, and components.
Covert the existing home page to use the new editable template.
Verify the updated page.
Let's get started!
We've already reviewed the existing Geometrixx Home page and broken down the structure, identifying what is needed for the template. Let's look at a complete Home Page:
This is a home page filled with content. Sometimes, it is easier to visualize the base components by looking at an empty page:
From here, you should now be able to see the break out of the components.
Here's an annotated view; the components listed here are identified using the new types - not the existing components currently employed by the template. Each of these components marked on this image are structure components. This means they are managed at the template and must be added to editable template, by the template author.
In addition, within the layout container highlighted in blue, there are additional nested structure components:
In this exercise, we will create an Editable Template which supports the same structure as the legacy Static Template.
Let's create what will be the new Home Page editable template. First log into AEM using the default account:
Username: admin
Password: admin
Open the AEM Start Page in Chrome.
Navigate to the Templates folder.
Open the Geometrixx Demo template folder.
Start the Template Creation Wizard.
Select the base template that is used to derive the new Editable Template.
Specify the new template's name.
Note: Ensure that you use the name GeoDemo Home Page. We will use it in a configuration later.
Open the newly created template.
We need to update the template's policy, so that the CSS rules are correctly applied. The first step is to open the Page Policy dialog.
Then we create a new policy and add the homepage style definition.
Now we need to configure the root layout container to set the default/locked components, and restrict components that can be used. For this exercise, make sure you only select the components you see here in the screenshots.
First, select the layout container and open its policy dialog.
Then create a new policy definition.
Once we have a new definition, we will give it a name and add a few components from the General group.
We also want to add a couple of Geometrixx Demo components, as these will be structural components.
Finally, set the number of columns in the responsive grid, and save the policy.
Now that the policy is created, we can create the remaining structure for the template. This will lock specific components on the page, while enabling authors to use other components in the layout container. To achieve this, we need to be in the Structure mode. This is the default mode for the Template Editor. If you are not in structure mode, see the troubleshooting steps to switch modes.
In order to add components to the template, open the side panel.
Now, drag the Header component over, adding it to the root layout container. This component should only be editable by template authors.
Once the header is placed it appears to take up the full 16 columns. However, this is not the case - something about the non-standard column count may create issues. Refresh the page and you should see it in the default 12 column layout.
Now that we can see the correct layout, we can fix its width. Select the component and enter its layout mode.
While in layout mode, expand the header to take up the full 16 column width. Once done, exit the layout mode.
Next, we will add the Carousel to the root layout container.
Like the header component, once the carousel is in the container it needs to be resized. So select the carousel and enter the layout mode again.
Resize the carousel to take up the full 16 columns. Once complete, exit the layout mode.
Finally, unlock the Carousel so each page created from this template can have custom content.
Next, we will add the Main Layout container, drag it over below the Carousel.
This container will span 12 columns, which is the default column size in the responsive grid. It is still a good idea to force it to a specific size. So let's select the container and enter the layout mode.
To make the adjustment, we are just going to set the size to 12 columns. We do not want to adjust the width, but we do need to trigger the layout container set the width value. To do this, we move the right handle just enough to trigger the layout display, then release it locking it back into 12 columns. This will force the responsive size of the text container to be set.
Next, we'll add the main layout container's content. This is will be a the fixed Lead component and a Layout Container, which will allow authors to add arbitrary content.
Drag the Lead Component over to the main layout container.
This will have custom content per page, so let us unlock it.
Now we can add the layout container that will allow authors to add content and components.
We want to allow authors to add only specific components, and more than this template currently allows. So we'll add a custom policy to this container - open the container's policy.
Give the policy a descriptive name.
Add all the entire GeoDemo component group, and then save the policy.
Finally, we want authors to be able to add the allowed components and add content to them, so unlock the container.
Next, we'll add the Right Rail Layout container, and configure its policy of allowed components.
First, drag over the layout container - make sure to place it in the root layout container, this is the 12 column wide instance.
To resize it, we need to enter the layout mode.
Resize it to be four columns wide, this will make it automatically float to sit next to the other container.
Like the main container, we want to allow authors to add a restricted set of components to this container. So open its policy editor.
Give the new policy a name.
Add the allowed components for this container and save the policy.
And finally, unlock the container to allow authors to add content.
The final step is to add the Footer to the root layout container. This component should only be editable by template authors.
Drag the Footer component to the root layout container.
Now that we can see the correct layout, we can fix its width. Select the component and enter its layout mode.
While in layout mode, expand the header to take up the full 16 column width. Once done, exit the layout mode.
Now that we have a working template, we can convert the Geometrixx home page. To do this, we will use the Page Template/Structure Conversion Tool. This is a tool created specifically to convert from a legacy static template to an editable template, and works in three steps:
Convert Page Structure
Convert all parsys components to responsive grids
Convert all column controls to a new responsive grid structure, each column is its own responsive grid.
The Page & Column control rewrite rules are configurable. For this lab we have provided the default ones necessary to convert Geometrixx column control. However, we do need to customize the configuration for the Page Rewrite Rule. Let's do that now:
Open CRX/DE and list the component names on the new Editable template.
Open the CRX/DE Lite in Chrome.
Navigate from the tree root to:
/conf
geodemo
settings
wcm
templates
geodemo-home-page
structure
jcr:content
root
Click on the root node to expand it and display the node names on the Editable Template. In this example, the responsivegrid node represents the main parsys. The responsivegrid_942409522 node represents the rightrail parsys.
Note: the node responsivegrid_942409522 is unique to this example, you will have a different value in your AEM instance
To configure the Rewrite Rule, we need to update the OSGi Configuration. To do this, open the Web Console:
Open the OSGi Web Console in Chrome.
Search for the Page Rewrite Rule Configuration. Click on the configuration entry labeled com.adobe.aem.modernize.structure.impl.rules.PageRewriteRule~homepage, and open the form.
This is the pre-edited configuration form; we are going to update the <<responsive_grid_name>> references highlighted here:
Replace <<responsive_grid_name>>, with the name of the right-rail parsys shown in your AEM instance. This is an example complete form, the numbers will be different for your updates. Once the updates are done, save the form.
This will actually convert the page to use the new Editable Template. The only pages that are listed, are those which match configured PageRewriteRule Service definitions. At this time, this is just the Geometrixx Home Page template.
Open the AEM Start Page in Chrome.
Navigate to the Page Conversion Tool.
Enter the Geometrixx Homepage path and run the search.
Select the Gemoetrixx English home page and run the conversion process.
Once the process is complete, you will see the success message.
After this step, the Home page has been converted. Let us take a look at it:
Open the Geometrixx Home Page in Chrome.
For the most part, the page looks the same, which is precisely the outcome we wanted.
Note: There are still some stylistic differences in the page. This is attributed to a difference in the components no longer aligning with the new page structure. Let us address this in the next lesson.
Find/Create Core/HTL components matching existing components.
Review/Update Rewrite Rules.
Use the Tool to migrate Component Definitions.
In this lesson, we will look at legacy components and update them to either proxy AEM Core Components or updated (HTL) custom/customer components. To accomplish this, we'll use the new Component Conversion Tool for migrating component definitions.
The Geometrixx Shapes team realized they have a good number of custom components on their projects, which they need to review every time AEM gets updated.
They conducted an evaluation of their components and the Core Components and figured out they could use the latter as replacement for custom code in many situations and guarantee reduced upgrade work in the future.
In this exercise, we will review the list of custom Geometrixx components, and identify those who could be replaced with Core Components equivalent.
Open the CRX/DE Lite in Chrome.
Navigate from the tree root to:
/content
geometrixx
en
jcr:content
root
Most of Geometrixx's components are from the legacy foundation component suite. Here is the list:
Geometrixx Header: geometrixx/components/header
Foundation Carousel: foundation/components/carousel
Geometrixx Lead: geometrixx/components/lead
Foundation Image: foundation/components/image
Geometrixx Title: geometrixx/components/title
Foundation Text: foundation/components/text
Looking over this list, we want to update the following components to the specified references. Each of these are either new custom components or Core Component proxies. We provided the target source code in this lab, so there's no code to create/update.
Geometrixx Header: geometrixx/components/header
Convert to GeoDemo Header: geodemo/components/content/header
Foundation Image: foundation/components/image
Convert to GeoDemo Image: geodemo/components/content/image
Geometrixx Lead: geometrixx/components/lead
Convert to GeoDemo Lead: geodemo/components/content/lead
Geometrixx Title: geometrixx/components/title
Convert to GeoDemo Title: geodemo/components/content/title
Foundation Text: foundation/components/text
Convert to GeoDemo Header: geodemo/components/content/text
Since many organizations can have a large number of components, the Component Conversion Tool only displays components as long as they match a rule. This will help the conversion process by limiting options and allowing you to convert components in batches, as desired.
This cuts down on the size of the list, so as not to display components which will never be modified.
We have already provided the rules that will make the changes for updating these components. Let us review them:
You can view them in CRX/DE:
Open the CRX/DE Lite in Chrome.
Navigate from the tree root to:
/apps
cq
modernize
component
rules
geodemo
Let us take a close look at one of the rules. Each of the rules consists of two parts, a list of patterns and a replacement.
Each node under patterns is essentially a structure that must match for this rule to be applied. A rule may have multiple patterns, if any of the patterns match, then the rule will be applied.
In order to match, each of the properties, child nodes, and properties must match. In this case, the following must be true:
Node is of primary type nt:unstructured
Node has the property sling:resourceType set to foundation/components/image
No matter how many patterns exist, there is only one replacement. This is used as the basis for writing the replacement node. There are a number of replacement rules, we would not need all of them for this lab. For more information, see the HelpX page for the Conversion Tool.
Let us go through the configuration of this replacement:
Set the node's primary type to the static value nt:unstructured.
Set the sling:resourceType property to the static value geodemo/components/content/image.
Set the fileReference property to the original node's fileReference property.
Set the width property to the original node's width property.
Copy any children nodes from the original to the updated node. In the case of this Image component, there may be a binary file stored on the component. This last configuration will copy any files to the updated node.
Now that we have reviewed the conversion rules, we are confident that we can use the Component Conversion tool. Let us open it up:
Open the AEM Start Page in Chrome.
Navigate to the Component Converter Tool.
We need to search for the components to convert. We only want to convert the components on the Geometrixx Home page, so specify its jcr:content node - otherwise it will list all of the children pages' components as well.
This list looks correct for our rules and the components we want to update. Let us run it!
Once the conversion is done, you will get the success message.
Let's take a look at the full page final output now:
Open the Geometrixx Home Page in Chrome.
There's no obvious visual distinction using the new components, which is exactly the outcome we were looking for. If we take a closer look at the nodes in the repository, we can see they are now using the updated references:
Open the CRX/DE Lite in Chrome.
Navigate from the tree root to:
/content
geometrixx
en
jcr:content
root
Example:
Review the Dialog Rewrite Rules.
Use the Tool to convert Classic Dialogs to Touch-enabled UI Dialogs.
This lesson covers how to use the Dialog Conversion Tool for updating Classic Dialogs for a component. There is thorough documentation available (see References) on how to use this tool. However, we will go through the process in a controlled environment.
Now that the templates and components have been updated, we need to optimize the dialog for the Lead component for the Touch-enabled UI.
Before we begin, let us take a look at the current dialog and how a Classic dialog appears on the Touch-enabled UI.
Open the Geometrixx Home Page in Chrome.
Make sure we're in edit mode.
Open the lead component's dialog on the Geometrixx home page.
Review the rendering. You can see that it is an embedding of the classic dialog in a Touch UI wrapper.
We're going to identify the first dialog we want to migrate. In this case, it is the Geometrixx Lead component. We copied the original over to the new code base as an example.
Open the AEM Start Page in Chrome.
Navigate to the Dialog Conversion tool.
Search for the components with legacy dialogs. In this project's case, there is only one: our Lead component.
Select the lead component for conversion and kick the process off.
After it's done, you will get the standard success message.
With the dialog conversion complete, we can take a look at the new dialog.
Open the Geometrixx Home Page in Chrome.
Select the Lead component and open its dialog again.
As you can see, it now renders using the much cleaner Coral 3 widgets.
There are a few places where something may go wrong during the lab, and you may need to backtrack to fix it. This information should help with the most likely issues that may be encountered.
The first possible, albeit highly unlikely, issue that may be experienced is the inability to add components to the newly created Editable Template. This can occur if you are not in the Structure mode.
Instead, you may find yourself in Layout Mode:
Or possibly Initial Content mode:
Or finally, Preview mode:
To resolve this, simply change modes back to Structure by selecting it from the mode menu.
After the conversion, the right rail is not displayed:
This occurs when the name of the right rail parsys was not set correctly in the OSGi configuration. It is not essential for the lab that it should be correct, so we are not providing a resolution.
Another issue which you may encounter is an error during the Page Conversion process. This produces an error which appears as:
This occurs when the one of the updates to the Page Rewrite Rule configuration was missed, ensure both values are updated here:
In this lab, we provided an overview of the tools created to assist in migrating AEM pages, templates, and components to modern capabilities. From here, customers can begin planning projects to apply these tools to their current implementations. You can:
Evaluate current static templates with a view for Editable Template structure.
Review current component suite for compatibility with Core Components.
Inventory classic component dialogs for upgrade to Coral 3 versions.
With this information in hand, you can create custom conversion rules. Use them on a proof-of-concept application to begin your AEM Modernization effort!