Developing with AEM

Monday 10 November 2014

The idea that once the website is launched that’s it finished, is just plain wrong.

There are many Content Management Solutions (CMS) in the market at the moment, but one that is getting particular attention is Adobe’s Experience Manager (AEM: previously named CQ). At AKQA, we’re using AEM on a number of projects and have noticed a lot of additional interest in this technology – hence this edition of wholly devoted to it.

Personally, I’ve been working with AEM/CQ for the last 3.5 years and have found it to be an incredibly powerful CMS that integrates well with the suite of Adobe products. But the aim of this piece is not to be a sales pitch – there’s enough information on the internet if you’re interested. Instead, I want to share some of the lessons learnt and key approaches we take when working with AEM.

Author first

What exactly do I mean by ‘author first’ – surely the end website is the most important? Well yes, obviously. The website you create needs to meet all of your client’s objectives and also match the design created to promote them.

But a website is not a static thing – it develops over time. The main reason you are building within a CMS is to enable your client to add and update content, delete sections and so on. The idea that once the website is launched that’s it finished, is just plain wrong.

What that means for developing your platform in AEM (platform rather than site – I’ll cover that later) is that the author should be your main consideration. In fact, AEM is written for the author: there to enable them to create content. This really is the primary purpose of AEM.

What does ‘author first’ mean in practice? Well, it means you should think about the authoring experience while making any decisions on your solution. Does this make the author’s life easier? Does this enable them to do what they need to do? I’ll come back to ‘author first’ later as it’s such a key principle.

AEM fundamentals

To understand fully how AEM works, there are a few key principles you’ll need to grasp. AEM is far more complex and has far more functionality than I will cover here, but this piece should give you enough to understand our approach to working with AEM.

If you’d like to know more about AEM, I recommend the Adobe training courses and their supporting documentation. For the purposes of this article, I will deal only with creating a website, not using AEM’s PhoneGap integration feature or considering how to configure servers or integrate it with SiteCatalyst, etc.

As a basic production instance, AEM consists of an Author instance and a Publish instance; the former is used for content creation. When content is ready, it is published – that is, pushed to the public-facing Publish instance that serves the website to consumers.

I’ll go through the process of creating a page for an author, to introduce the main concepts they’ll have to deal with while working with AEM. I’ll then go through our approach and working principles.

Page creation

To create a page, an author will log in to the Author instance, navigate to the correct point within their website and click + to add a new page. At this point they are presented with a dialog showing a list of available templates. The author selects one, adds the page details – name, title, description etc. – and a new page is created.

AEM gives the author the option to edit the page immediately, which opens the new page in a separate tab/window to allow them to add appropriate content. As the page opens, the author will see a set of components (defined by the template) that they can author, some of which have existing settings or inherent values.

There may also be parsys components on the page. These act as drop zones that allow the author to add new components into the area defined (text within the drop zone explains that new components can be added). The author will update the components on the page to add content, dropping in images where needed, adding copy and adding and removing components until they are happy with the page. The author can then save the page to publish when it’s time to go live.

What I’ve described above is the basic author workflow. Editing is very similar – the author simply opens an existing page rather than creating a new one. As part of this workflow, there are a number of items that warrant further attention: how do we create them to ensure the platform is as easy to use and maintain as possible?


Components are the building blocks of web pages in AEM: everything on a page is created by a component. Each component has the option to have an editor dialog, to allow the author to add appropriate content. In AEM 6 this can be also be in-line.

I will now illustrate how this would feel for an author to follow the workflow above. They have created a page and on it they can see that the navigation is already present and populated: they don’t need to change it. Below the navigation is a teaser.

Clicking on the teaser opens a dialog box that allows the author to select where the teaser should link to, and its main text and tagline. They can also select an image from the dialog box or drag one from the AEM sidebar onto the teaser to add as content.

Below are some fundamental aspects of components that inform how they are used and developed:

While building an AEM solution, one of our fundamental principles is to keep the number of components to a minimum. This supports maintainability as the code base is smaller, but it also makes the author’s life simpler. Rather than work out which of the five teaser components they need to use in a specific place, the author can simply use the teaser component.

We achieve this by making the component aware of which part of the website/page it’s been added to and (if required) allowing the author to chose which variant they want within the component dialog box.

Components are the route by which an author can add, update and delete content. AEM offers a ‘what you see is what you get’ interface – click on the appropriate part of the website to author it. The author interface and dialog boxes should get as much UE attention and love as the end website. These are the key website interaction points for your client – the simpler you can make the process, the happier they will be.


Templates are essentially a starting set of content for a page. Once a page has been created from a template the connection is over: any subsequent update to the template will not affect the pages created from it.

Despite their simplicity, AEM templates are very powerful. AEM stores its content in the Java Content Repository (JCR), a node-based way to store data. This means you can store as much (or as little) configuration for the new page as you like within the template, down to component settings and content, if needed.

While creating templates, we return to our focus on the author: we want to make their experience as simple as possible. The way we work with AEM templates defines which parts of a page are editable and which are locked. There are no restrictions to this within AEM. You can have templates that lock everything down on a page and only allow the author to update specified components – or you could have a parsys component that allows the author drag in whatever they want.

The best and most pragmatic solution is the middle ground. We aim to have our templates give a page structure, locking down site furniture (navigation, footer etc.) and key components (e.g. hero teaser), but also offering areas in which the author can add and arrange components to deliver the page they want.

As part of this solution, we’ll often have some example components within these sections. When the page is initially opened, the author can see the example structure, but they can re-order, add and delete these example components as they wish.

Essentially, the trade-off is between flexibility and design consistency. You want your author to have enough flexibility to create the pages they want, but you also want pages to be consistent across the website, to offer a positive end user experience.

The middle ground is the compromise between these two – giving the author enough flexibility while also ensuring design consistency. The advantage of example components is that they show an author the shape of the page as it was originally envisaged. They can modify this, but they don’t have to think up a new design each time. This lowers their cognitive load and also the work of finding and adding the required components.

One final consideration while working with templates: they can be website-wide or restricted to certain areas (based on allowed parents/allowed children). This enables you to enforce the site structure and also makes the author’s life much simpler. When the author comes to create a page, they will only see the templates available in that location.


A page in AEM is a set of information stored in nodes that allows components to create the page. At first a copy of the page template, it is updated as the author edits it via AEM. Content can be inherited in the site tree, allowing the navigation to be authored on the homepage (for example) and inherited by the rest of the site, which exists as child nodes of the homepage.

Design and user experience considerations

As I said in my introduction to this piece, AEM is a very powerful CMS. One of its strengths is the control it gives to front-end developers with regard to the markup of the end pages. This means there are really no platform restrictions on the designs you can create with AEM.

Having said that, there are more general considerations that come from working with a CMS, especially for a responsive website. These all come down to one key consideration: The content is authored. Okay, so that should be obvious – it’s a CMS, right? However, this places certain restrictions on your design, as content will be added by people who are not designers:

It comes down to trying to minimise the risk that the author could break the design, not minimise to remove. At the end of the day, the author is responsible for creating the page. The flexibility that we give them will mean that they can break the page (if they want). However, we should do all we can to minimise this risk through clever design and coding.

It’s worth noting that specifying the number of characters for fields and similar restrictions will make the author’s life more difficult and can lead to frustration with the system. These restrictions also tend to be design-specific, which as I mentioned before, is not what you want to add at component level as they may not apply when you use the component in a different design.

We approach this issue by making the code as accommodating as possible – areas that expand or scroll, ellipses with mouse-over to see all the content etc. There are multiple approaches, depending on the design. The style guide will also recommend copy lengths for the author, but this won’t stop them creating overlong pages.

The approach above is especially important when you’re internationalising your pages, as the length of words varies greatly between languages and fonts. If you’ve hardcoded the restriction into your component, a code change and deployment will be needed to change it. With our approach, the author can still create their pages and the content will be accessible.

User experience

As I emphasise above, we should consider the experience for both end user and author. Within each component dialog, what is the easiest way for the author to achieve their aims? If we can derive values based on location or other content, we should do so – rather than take the easy option of adding fields to the dialog box.


I have already covered the main architectural considerations of working with AEM: mainly to focus on re-use, to minimise the number of components, and to prioritise the author experience.

The other key learning is to work with AEM not against it. AEM is a very capable CMS, and your project will go a lot smoother if you use it the way it’s supposed to be used. AEM will also simplify your project, and has capabilities for file concatenation (JS and LESS), minification, Gzip and less compilation (to name but a few).

AEM has a workflow capability that allows you to set up authorisation flows and to automate various tasks. We advise caution with using these if they require manual intervention (e.g. approval to publish a page). While this seems like a good idea initially, the authorisation step quickly becomes a bottleneck and ends up being removed. In our opinion, it’s better to trust the author and make sure they’re aware of when content should be published. This will make for a more flexible system and allow the site to respond faster.

One last point from an architectural standpoint: AEM is set up to render dynamic content from the server (i.e. user-specific content) and the pages are heavily cached (via the dispatcher and in most cases a CDN too). Wherever possible, do your user-specific dynamic content client-side or include it via server-side or edge-side.


The main lesson is to use foundation components that ship with AEM to learn how to interact with AEM. The code may not be fully production-ready, but the components will show you how to work with dialogs and interact with resources etc. All code is available in any AEM instance under the libs/foundation/components node (JSP-based components) and libs/wcm/foundation/components (Sightly components: AEM 6).

In terms of the front end, if you require specific styles or functionality to make the author experience work (but it’s not required on the end site), create a specific client library (CSS and/or JavaScript) that is only pulled through on the Author instance. This will allow you to provide the professional author interface required without adding any additional weight to the end site.


Internationalisation is worth a quick comment, AEM deals with the localisation of content via a number of mechanisms - but it’s also possible to translate the entire AEM interface. All the text for the interface is stored in i18n libraries (a set of key value pairs). When developing components the same approach should be used with the text for the author dialogs being held in i18n libraries to ensure they can be translated if required.


Finally a quick note on content, in AEM the production author instance should be the source of truth for content. It manages what’s been pushed to the publish instance(s) and needs to be aware of any changes. If you try and author content on a different server (say UAT), package it up and deploy it to your production author instance, it can overwrite directories breaking the link between author an publish and creating orphan pages. To avoid any issues create all you content on the production author instance and back fill to your other environments as required.

This is fine once you’re live but during development you want some content to be shared between the development team and QA team to ensure a common ground in terms of communicating issues, handing over code etc. To manage this we have a separte part of our code repository that doesn’t get deployed to production but can be optionally added to our build so it can be shared between developers. The optimum is to have 3 sets of content:

The last thing to note is that your i18n libraries should also be part of content & not deployed to production (except for the initial push), the reason for this is the interface to update i18n is within AEM so once deployed they are effectively content. If they are deployed with your code you will overwrite any work to translate the values with the next code deployment.

There you have it - a (high level) overview of our approach to AEM development. Hopefully it’s given you some insight into how we work with the Adobe CMS at AKQA.

About The Author

James is a Technical Architect for ideas and innovation agency AKQA in London. He’s been working firmly in the front-end development sphere for the past 14 years.