Project Setup project-setup
This tutorial covers the creation of a Maven Multi Module Project to manage the code and configurations for an Adobe Experience Manager Site.
Prerequisites prerequisites
Review the required tooling and instructions for setting up a local development environment. Ensure that you have a fresh instance of Adobe Experience Manager available locally and that no additional sample/demo packages have been installed (other than required Service Packs).
Objective objective
- Learn how to generate a new AEM project using a Maven archetype.
- Understand the different modules generated by the AEM Project Archetype and how they work together.
- Understand how AEM Core Components are included in an AEM Project.
What you are going to build what-build
In this chapter, you generate a new Adobe Experience Manager project using the AEM Project Archetype. Your AEM project contains complete code, content, and configurations used for a Sites implementation. The project generated in this chapter serves as the basis for an implementation of the WKND Site and are built upon in future chapters.
What is a Maven project? - Apache Maven is a software management tool to build projects. All Adobe Experience Manager implementations use Maven projects to build, manage, and deploy custom code on top of AEM.
What is a Maven archetype? - A Maven archetype is a template or pattern for generating new projects. The AEM Project archetype helps to generate a new project with a custom namespace and include a project structure that follows best practices, greatly accelerating the project development.
Create the project create
There are a couple options for creating a Maven Multi-module project for AEM. This tutorial uses the Maven AEM Project Archetype 35. Cloud Manager also provides a UI wizard to initiate the creation of an AEM application project. The underlying project generated by the Cloud Manager UI results in the same structure as using the archetype directly.
The next series of steps will take place using a UNIX® based command-line terminal, but should be similar if using a Windows terminal.
-
Open up a command-line terminal. Verify that Maven is installed:
code language-shell $ mvn --version Apache Maven 3.6.2 Maven home: /Library/apache-maven-3.6.2 Java version: 11.0.4, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-11.0.4.jdk/Contents/Home
-
Navigate to a directory in which you want to generate the AEM project. This can be any directory in which you want to maintain your project’s source code. For example, a directory named
code
beneath the user’s home directory:code language-shell $ cd ~/code
-
Paste the following into the command line to generate the project in batch mode:
code language-shell mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \ -D archetypeGroupId=com.adobe.aem \ -D archetypeArtifactId=aem-project-archetype \ -D archetypeVersion=39 \ -D appTitle="WKND Sites Project" \ -D appId="wknd" \ -D groupId="com.adobe.aem.guides" \ -D artifactId="aem-guides-wknd" \ -D package="com.adobe.aem.guides.wknd" \ -D version="0.0.1-SNAPSHOT" \ -D aemVersion="cloud"
note note NOTE To target AEM 6.5.14+ replace aemVersion="cloud"
withaemVersion="6.5.14"
.Also, always use the latest archetypeVersion
by referring to the AEM Project Archetype > UsageA full list of available properties for configuring a project can be found here.
-
The following folder and file structure is generated by the Maven archetype on your local file system:
code language-plain ~/code/ |--- aem-guides-wknd/ |--- all/ |--- core/ |--- ui.apps/ |--- ui.apps.structure/ |--- ui.config/ |--- ui.content/ |--- ui.frontend/ |--- ui.tests / |--- it.tests/ |--- dispatcher/ |--- pom.xml |--- README.md |--- .gitignore
Deploy and build the project build
Build and deploy the project code to a local instance of AEM.
-
Ensure you have an author instance of AEM running locally on port 4502.
-
From the command line, navigate into the
aem-guides-wknd
project directory.code language-shell $ cd aem-guides-wknd
-
Run the following command to build and deploy the entire project to AEM:
code language-shell $ mvn clean install -PautoInstallSinglePackage
The build takes around a minute and should end with the following message:
code language-none ... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary for WKND Sites Project 0.0.1-SNAPSHOT: [INFO] [INFO] WKND Sites Project ................................. SUCCESS [ 0.113 s] [INFO] WKND Sites Project - Core .......................... SUCCESS [ 3.136 s] [INFO] WKND Sites Project - UI Frontend ................... SUCCESS [ 4.461 s] [INFO] WKND Sites Project - Repository Structure Package .. SUCCESS [ 0.359 s] [INFO] WKND Sites Project - UI apps ....................... SUCCESS [ 1.732 s] [INFO] WKND Sites Project - UI content .................... SUCCESS [ 0.956 s] [INFO] WKND Sites Project - UI config ..................... SUCCESS [ 0.064 s] [INFO] WKND Sites Project - All ........................... SUCCESS [ 8.229 s] [INFO] WKND Sites Project - Integration Tests ............. SUCCESS [ 3.329 s] [INFO] WKND Sites Project - Dispatcher .................... SUCCESS [ 0.027 s] [INFO] WKND Sites Project - UI Tests ...................... SUCCESS [ 0.032 s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 23.189 s [INFO] Finished at: 2023-01-10T11:12:23-05:00 [INFO] ------------------------------------------------------------------------
The Maven profile
autoInstallSinglePackage
compiles the individual modules of the project and deploys a single package to the AEM instance. By default this package is deployed to an AEM instance running locally on port 4502 and with the credentials ofadmin:admin
. -
Navigate to Package Manager on your local AEM instance: http://localhost:4502/crx/packmgr/index.jsp. You should see packages for
aem-guides-wknd.ui.apps
,aem-guides-wknd.ui.config
,aem-guides-wknd.ui.content
, andaem-guides-wknd.all
. -
Navigate to the Sites console: http://localhost:4502/sites.html/content. The WKND Site is one of the sites. It includes a site structure with a US and Language Masters hierarchy. This site hierarchy is based on the values for
language_country
andisSingleCountryWebsite
when generating the project using the archetype. -
Open the US
>
English page by selecting the page and clicking the Edit button in the menu bar: -
Starter content has already been created and several components are available to be added to a page. Experiment with these components to get an idea of the functionality. You will learn the basics of a component in the next chapter.
Sample content generated by the Archetype
Inspect the project project-structure
The generated AEM project is made up of individual Maven modules, each with a different role. This tutorial and most development focus on these modules:
-
core - Java Code, primarily back-end developers.
-
ui.frontend - Contains source code for CSS, JavaScript, Sass, TypeScript, primarily for front-end developers.
-
ui.apps - Contains component and dialog definitions, embeds compiled CSS and JavaScript as client libraries.
-
ui.content - contains structural content and configurations like editable templates, metadata schemas (https://experienceleague.adobe.com/content,%20/conf?lang=en).
-
all - this is an empty Maven module that combines the above modules into a single package that can be deployed to an AEM environment.
See the AEM Project Archetype documentation to learn more details of all the Maven modules.
Inclusion of Core Components core-components
AEM Core Components are a set of standardized Web Content Management (WCM) components for AEM. These components provide a baseline set of a functionality and are styled, customized, and extended for individual projects.
AEM as a Cloud Service environment include the latest version of AEM Core Components. Therefore projects generated for AEM as a Cloud Service do not include an embed of AEM Core Components.
For AEM 6.5/6.4 generated projects, the archetype automatically embeds AEM Core Components in the project. It is a best practice for AEM 6.5/6.4 to embed AEM Core Components to ensure that the latest version gets deployed with your project. More information about how Core Components are included in the project can be found here.
Source Control Management source-control
It is always a good idea to use some form of source control to manage the code in your application. This tutorial uses git and GitHub. There are several files that get generated by Maven and/or the IDE of choice that should be ignored by the SCM.
Maven creates a target folder whenever you build and install the code package. The target folder and contents should be excluded from SCM.
Under, the ui.apps
module observe that many .content.xml
files are created. These XML files map the node types and properties of content installed in the JCR. These files are critical and cannot be ignored.
The AEM project archetype generates a sample .gitignore
file that can be used as a starting point for which files can be safely ignored. The file is generated at <src>/aem-guides-wknd/.gitignore
.
Congratulations! congratulations
Congratulations, you have created your first AEM Project!
Next Steps next-steps
Understand the underlying technology of an Adobe Experience Manager (AEM) Sites Component through a simple HelloWorld
example with the Component Basics tutorial.
Advanced Maven commands (Bonus) advanced-maven-commands
During development, you may be working with just one of the modules and want to avoid building the entire project in order to save time. You may also want to deploy directly to an AEM Publish instance or perhaps to an instance of AEM not running on port 4502.
Next let’s review some additional Maven profiles and commands you can use for greater flexibility during development.
Core module core-module
The core module contains all Java™ code associated with the project. The build of core module deploys an OSGi bundle to AEM. To build just this module:
-
Navigate into the
core
folder (beneathaem-guides-wknd
):code language-shell $ cd core/
-
Run the following command:
code language-shell $ mvn clean install -PautoInstallBundle ... [INFO] --- sling-maven-plugin:2.4.0:install (install-bundle) @ aem-guides-wknd.core --- [INFO] Installing Bundle aem-guides-wknd.core(~/code/aem-guides-wknd/core/target/aem-guides-wknd.core-0.0.1-SNAPSHOT.jar) to http://localhost:4502/system/console via WebConsole [INFO] Bundle installed [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 8.558 s
-
Navigate to http://localhost:4502/system/console/bundles. This is the OSGi Web console and contains information about all the bundles installed on the AEM instance.
-
Toggle the Id sort column and you should see the WKND bundle installed and active.
-
You can see the ‘physical’ location of the jar in CRXDE-Lite:
Ui.apps and Ui.content modules apps-content-module
The ui.apps maven module contains all the rendering code needed for the site beneath /apps
. This includes CSS/JS that is stored in an AEM format called clientlibs. This also includes HTL scripts for rendering dynamic HTML. You can think of the ui.apps module as a map to the structure in the JCR but in a format that can be stored on a file system and committed to source control. The ui.apps module only contains code.
To build just this module:
-
From the command line. Navigate into the
ui.apps
folder (beneathaem-guides-wknd
):code language-shell $ cd ../ui.apps
-
Run the following command:
code language-shell $ mvn clean install -PautoInstallPackage ... Package installed in 70ms. [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.987 s [INFO] Finished at: 2023-01-10T11:35:28-05:00 [INFO] ------------------------------------------------------------------------
-
Navigate to http://localhost:4502/crx/packmgr/index.jsp. You should see the
ui.apps
package as the first installed package and it should have a more recent timestamp than any of the other packages. -
Return to the command line and run the following command (within the
ui.apps
folder):code language-shell $ mvn -PautoInstallPackagePublish clean install ... [INFO] --- content-package-maven-plugin:1.0.2:install (install-package-publish) @ aem-guides-wknd.ui.apps --- [INFO] Installing aem-guides-wknd.ui.apps (/Users/sachinmali/Desktop/code/wknd-tutorial/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4503/crx/packmgr/service.jsp [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.812 s [INFO] Finished at: 2023-01-10T11:37:28-05:00 [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal com.day.jcr.vault:content-package-maven-plugin:1.0.2:install (install-package-publish) on project aem-guides-wknd.ui.apps: Connection refused (Connection refused) -> [Help 1]
The profile
autoInstallPackagePublish
is intended to deploy the package to a Publish environment running on port 4503. The above error is expected if an AEM instance running on http://localhost:4503 cannot be found. -
Finally run the following command to deploy the
ui.apps
package on port 4504:code language-shell $ mvn -PautoInstallPackage clean install -Daem.port=4504 ... [INFO] --- content-package-maven-plugin:1.0.2:install (install-package) @ aem-guides-wknd.ui.apps --- [INFO] Installing aem-guides-wknd.ui.apps (/Users/dgordon/code/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4504/crx/packmgr/service.jsp [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] --------------------------------------------------------------------
Again a build failure is expected to occur if no AEM instance running on port 4504 is available. The parameter
aem.port
is defined in the POM file ataem-guides-wknd/pom.xml
.
The ui.content module is structured the same way as the ui.apps module. The only difference is that the ui.content module contains what is known as mutable content. Mutable content essentially refers to non-code configurations like Templates, Policies, or folder structures that is stored in source-control but could be modified on an AEM instance directly. This is explored in more detail in the chapter on Pages and Templates.
The same Maven commands used to build the ui.apps module can be used to build the ui.content module. Feel free to repeat the above steps from within the ui.content folder.
Troubleshooting
If there is issue generating the project using the AEM Project Archetype see the list of known issues and list of open issues.
Congratulations again! congratulations-bonus
Congratulations, on going through the bonus material.
Next Steps next-steps-bonus
Understand the underlying technology of an Adobe Experience Manager (AEM) Sites Component through a simple HelloWorld
example with the Component Basics tutorial.