AEM Project Archetype

Hello in this video, we will be looking at how to use the AEM Project Archetype to generate an AEM project.

So what is an AEM Project? Well, in its simplest terms, it’s a collection of folders and files that make up a customer’s code base. This includes CSS, JavaScript, HTML templates, Java code, as well as a series of XML and configuration files.

These files are collected and organized into a Maven project. Maven, part of Apache, is a software management tool that’s used to build and deploy Java based code. And Maven is used to manage the dependencies for the project, as well as any other third-party APIs. Now one of the most important functions of Maven is that it compiles the code base and produces artifacts that AEM can recognize and install. There are two main artifacts, AEM packages and OSGi bundles. Packages contain HTML, CSS, JavaScript, as well as a series of XML configuration files. The OSGi bundles are actual JAR files that contain the compiled Java code. Now once these AEM artifacts are generated during a Maven build, they can then be deployed to an AEM environment. Locally, these artifacts can be uploaded directly by using AEM’s Package Manager or by using a Maven command. When using AEM as a cloud service, this deployment is done using Adobe’s Cloud Manager. So what about the AEM Project Archetype? Well, an Archetype is a Maven tool and it’s essentially a template for generating projects. So the AEM Project Archetype will general a clean AEM project for us and it’ll ensure that this AEM project includes the latest standards and best practices. So features like AEM core components, editable templates, testing, as well as the latest front-end tools and technologies are all included in the project and configured correctly. The AEM Project Archetype takes a series of parameters like the version of AEM being used, application title, application ID and as well as some other inputs. And this is going to generate a project that’s customized based on those parameters. So it’s definitely the fastest and recommended way to starting a new project. So let’s look at how an AEM project is broken down. Typically, it’s organized into multiple sub-folders or sub-projects, otherwise known as Maven modules. Now together these modules make up a standard AEM project that gets generated by the Archetype. And the motivation behind this organization is to break down a project into sort of these discrete separation of concerns, which makes it a lot easier for large dev teams to manage code and dependencies. The ui.frontend module is a dedicated front-end module that contains all the source code used on the application’s front-end. So this would be typically CSS and JavaScript but it’s also configured to support modern front-end languages like SASS and Typescript. Now the ui.frontend module will generate static CSS and JavaScript that is integrated with the ui.apps module in the form of client libraries. And the ui.apps module gets its name because it loosely maps to the apps folder in AEM. And this is the module that’s going to contain important things like our component definitions, as well as OSGi configs, client libraries and optionally OSGi bundles. The core module contains all of the Java code for the project and this includes things like Sling Models, OSGi services, unit testing. And during the build process, the Java code gets compiled into an OSGi bundle and that’s actually merged into the ui.apps project.

Now we also have a ui.content module and this gets its name because it’s loosely mapped to the content and configurations in AEM. Now the intention of the ui.content module is to contain all the structural content that our application is going to rely on. So this can be things like high-level page structure, DAM folder structures. It’ll also contain things like some initial template definitions and other pieces of mutable content.

Now there’s some additional modules that get generated by the Archetype. One is a dispatcher module that contains all of the dispatcher configurations for the project, as well as some integrated testing modules. Lastly, there is the all module. Now the all module, as the name implies, contains all of the code that needs to be packaged and deployed to AEM. During the Maven build process, the ui.apps and ui.content modules generate packages that are embedded in the all module. And finally, the last step of the Maven build is to generate an all package, which is finally deployed to AEM. Now, everything in the AEM project is going to be managed in source control. And the only thing that is going to be deployed to AEM is that all package. So this is a bit complex but that’s why we’ve got the AEM Project Archetype to help us generate this structure for us automatically.

So let’s look at this in action.

The AEM Project Archetype is opensource and it can be found on GitHub. Like other projects at Adobe, the Archetype is continuously updated. So whenever starting a new project, you should look to use the latest version. The GitHub README has some high-level information about the Archetype and it’s got some useful links to much more detailed documentation, as well as several tutorials, which you can follow along with, and go through all the steps of implementing your own AEM Sites project. Now if we scroll down, you can see the different parameters that the Archetype uses to generate a project. So if you’re starting out your own project, it’s a good idea to become familiar with these and understand the effects and how it can impact the generated project.

All right, so let’s go ahead and generate a sample project using the Archetype. And if we scroll down the README, we can see some basic commands. And we’re just going to generate this project using command line terminal. Now, as a best practice, you want to have a dedicated directory to hold all of your source code. So I’ve got this folder for all my code.

And we want to make sure that you have a Java installed. You can’t generate the project without it. You also of course need Apache Maven installed. And now the AEM project itself relies on npm and Node.js, so you’ll want those two tools to be installed as well.

All right, so we’re just going to copy this command here to generate our project. And again if you’re doing this on your own, you’d want to change the app title, app ID, group ID to match the different parameters based on your application and organization.

So I’m just going to paste this command into my terminal. And that’s going to start the generation of our AEM project.

And once that’s finished, we can see that we’ve got a new folder called mysite. That’s our generated project. And if we navigate into that folder, you can see the different Maven modules. Let’s take a closer look at those using the Finder. And so here you can see all of the Maven modules we discussed earlier. We’ve got the all module, which is going to contain all our code, core, dispatcher, integrated testing, as well as ui.apps, ui.content and ui.frontend.

All right, so the next thing we want to do is let’s go ahead and actually build our project. And to do that we’ll use the command mvn clean install and the profile we’re going to use is autoInstallSinglePackage. And this profile will build and deploy our code base to a local instance of AEM.

So what we’re seeing now is Maven compiling all of our different Maven modules, core, ui.apps, ui.frontend. And eventually we should see a message like this, which indicates that we’ve built and compiled everything and that our build was successful. Now for the sake of the video, I’ve sped up the Maven build process but in general it takes about a minute or so. Before we log into AEM, let’s check out the build artifacts that Maven generated. So under core, you can see we’ve got our JAR file, this is the OSGi bundle for all the Java code as part of the project. Under ui.apps, we’ve got our ui.apps package, that ZIP. And you can also see under ui.content, we’ve got the ui.content ZIP. And of course beneath our all module, we can see the all package, which is packaging up all of the sub-modules, and that’s going to be installed on AEM. So now let’s quickly switch over to my local instance of AEM. We’ll just go ahead and log in and let’s see the result of that deployment. If we go to Tools, Deployments, Packages, this is going to open up AEM Package Manager. And here we can see our mysite.all package, which included our ui.apps package, as well as our ui.content package.

So those have been successfully uploaded and installed. All right, so let’s go ahead and see what sample content was bundled as part of the project. We can navigate into AEM Sites. We can see a new site called mysite. And we can go ahead and open up the homepage.

And if we switch into Edit mode, we can see that we’ve got a pretty basic site, some basic styles. But, yeah, we’ve got a title component, several teaser components, and all of these are part of AEM core components which have been bundled in as part of our AEM project. And while not everything is really styled, everything is fully functional. So we can update and author content, add images to these teasers. So it’s a great starting point.

Now, the AEM Project Archetype also includes a sample editable template. And this allows us to create new pages. So we can create a new page based on this content page template. And for the title we’ll just call it First Page. And then we can go ahead and open it.

And again nothing too exciting but we do have a title component, as well as a main layout container. And here we can insert new components. We can use the core text component. And everything is fully functional. So we can add, you know, a little Hello World message here and see it populate on our page.

And if we want to check out the editable template that this page is based on, from the Page Properties menu we can click Edit Template. And so here we’ve got our editable template which was generated by the Project Archetype. Again, it’s pretty simple. We’ve got a layout container, a footer, header and title but at least everything is all wired up and it’s all configured to work together.

So that’s it for this short video on the AEM Project Archetype. Thanks for watching. -