AEM Techies Take Note: We Built AEM Authoring Toolkit for You

What’s the Problem?

Creating components makes up more than half the dev time in AEM. Generally speaking, a component is going to be an authorable data presentation — a Sling model of a POJO class shipped with some content-generating logic.

Modern AEM websites are highly modular, therefore there are loads of components. They tend to be rather simplistic by themselves, assembling to make larger structures — both interactive and versionable. At Exadel, we’ve accumulated quite a bit of experience developing flexible component architecture that performs smoothly for users.

But making components is not all fun and games. Making complex XML configurations for components involves a certain amount of headache.

With the onset of AEM 6.x, Adobe introduced a new modern-looking authoring framework known as touch-oriented interface or Touch UI. Its underlying Granite framework delivers excellent options for authoring on any type of device. You can arrange complex editing dialogs however you like, enjoy the same experience on any device and/or breakpoint, and implement most of the logic in the inline editing mode. AEM 6.x has got all the power and dashing good looks of the Coral 3.0 interface.

But there is a tradeoff between the modern interface and usability on the one hand and dev complexity on the other. Dialogs and widgets are defined via JCR node sets, and their structure is not in the least bit simple. Many dialogs, however similar they may be, need just as many defining node sets. Data for dialogs and inline editors serving the same component are sometimes plainly duplicated.

This means that the good old “changed once, missed to change elsewhere” problem is in full force here.

If you choose to migrate your components from Classic UI to Touch UI you’re bound to incur expenses while transpiling the previously prepared node sets (or XML files) to new ones — they’re mostly the same in essence, but not without a range of annoying disparities and deficits. While Classic UI is mature and of age, the Touch UI is experiencing some severe growing pains, and still has a long way to go.

But never fear, there are solutions to these problems. The worldwide AEM community has done quite a bit to automate the building of author-mode interfaces. Some take the approach of creating a Granite dialog definition descriptively from an existing Java class, or otherwise creating both a Java class and its authoring counterpart from a common meta.

However, the general consensus is that the component is king, and when it comes to feature implementation requests, the change should be in the Java-coded model, and the authoring interface should only reflect that change. We dream of the day when AEM devs can modify or extend their Java code without being bitten in the behind by the ever-present need to fiddle with XML.

What Did We Do About It?

For the last couple of months, the folks at the Exadel Digital Marketing Technology Practice have been developing a solution aligned with this approach. We have a lot of legacy code to handle and are moving the codebase en masse from POJO to the Sling model world. We either develop or majorly refactor a handful of components each sprint, and there are hundreds of standardized labels, descriptions, selections, alert notices, etc. to deal with.

To help make this process easier and more manageable, we envisioned an instrument that would:

• be a close reproduction of Java code for your components in the frame of UI/UX
• repeat the creation and development of lines of Sling models without the need to switch to a cryptic meta language (actually, we love coding in Java and are thoroughly content with it)
• reproduce or mimic the most natural and common programming patterns (abstraction, inheritance, code reuse) when it comes to the Granite interface definitions
• make these definitions controllable “from the Java world” (including Ide syntax support and code completion, linting, etc.) — as much as possible
• implement advanced user interaction (from showing/hiding UI elements to complex data validation/reporting) in a way that does not travel far from Java as well, though this appears to be utterly frontend bound
• make all of the above in a configurable and flexible manner

We’ve made considerable progress toward this vision and we call it the AEM Authoring Toolkit. You can find it on GitHub and in the Maven repository.

The AEM Authoring Toolkit is an ever-evolving project aimed at delivering a comprehensive set of AEM authoring tools for generating UI/UX in an automatic and versatile manner.

Simply put, the Toolkit is the set of routines that plug into the workflow of AEM project compilation and deployment, automatically supplement one or more deployed packages with necessary XML definitions, and supply a value-pack of additional frontend assets.

Granite UI definitions are built based on annotations added to Java classes and their fields. Upon changing your Sling models or POJOs, adding or removing meaningful properties and moving them across the project, you automatically receive ever more developed interfaces.

Toolkit contains a Maven plugin that triggers before deploying a zipped payload to an AEM instance. Its raison d’etre is to analyze bundled Java code and assemble node sets. Annotations themselves are the property of an API module — a lightweight and dependency-free Java library. In addition to this, there is also the asset module, its main element being the DependsOn microframework.

Under the hood, there are annotations and annotation handlers. The former maintain Granite-bound settings, the latter process and verify them, and transform them to XML entities. For a typical component, a .content.xml, a _cq_dialog.xml, and a _cq_editConfig.xml are generated and injected into a component’s folder within the package. Then the XMLs unroll in the AEM instance.

A Look at the Details

Let’s check it out on the code level!

Suppose you have developed an AEM component that rests upon an authorable value named text.

This is what you would add to your repository to define the component itself:

Not that much so far! But now you need to facilitate the authoring dialog for that single field. Create the _cq_dialog.xml

That’s a much bigger deal! Don’t forget the XML namespaces! Take care to include items thrice: content > items > tabs > items > [tab_name] > items… Well, we actually opted for a tabbed dialog, but this is quite usual anyway.
And what about the inline editing facility? There’s another file to build, and that’s _cq_editConfig.xml

So you’ll write this down. Then deploy. Then debug. Then deploy again… then finally realize there must be a nobler way — a pure developer’s approach.
Here it is.

With this, we are totally done! The Toolkit’s plugin will analyze the class, look for the component folder at the specified path, and put all three XML entities there.
Of course you can feed names and labels from a collection of constants, and add whatever fields you wish. And if you’re looking to add a dropdown, for example, rather than a textbox, you just replace @TextField with @Select.
Currently, there are 20+ widget annotations supported, and this number will grow with every new release.

Do I Need AEM Toolkit?

When all is said and done, do AEM developers and project managers really need to consider adding the Toolkit to their working environment?

We can answer that concern with a few specific cases.

Suppose you have a bunch of older (pre-AEM 6.x) components. Probably you are planning a massive Touch UI migration for them, as many businesses end up doing. Using Toolkit annotations would make backend changes not only more simple, but also easier to review.

If you’d like to sketch out and implement new components and component architectures, the Toolkit also makes a big difference. When it comes to Sling buildup, model structure and polymorphism, it is very tricky to populate your resources with authored data. With the Toolkit, changes in the backend are naturally reflected in authoring tools.

Want to add interaction and implement a non-linear authoring approach? There’s no need to strike out custom clientlibs (or rather you may need some but far less often). The Toolkit offers its frontend part (the DependsOn microframework) to maintain complex relationships between widgets, and validate and report input limitations.

It’s quite possible you will need more than what the Toolkit offers just out of the box, or you’d like to manage assets developed by your own team. In this case, the Toolkit would offer you a brief but functional extension API to create custom annotations as well as custom handlers.

Another obvious consideration is that you, like all of us, care very much about the consistency of your codebase. Will using Toolkit lead to tons of refactoring, and will it take ages to revert if you decide to drop it? Nope!

With annotations added, you can turn the plugin on or off any time you wish. You may leave your previously written XML code in place, or combine the “manual XML” / “auto generated XML” approaches across components or within a single component. You can even try to “merge” the Toolkit with some foreign solution.

That’s basically it for the overview. We’re planning to provide you with more detail and code snippets in the near future. We are also going to show you how the Toolkit helps organize and maintain the whole of your AEM ecosystem. You are welcome to visit the Toolkit homepage any time, take a look at the manual, and play around with a sample project.

Until next time!

Authors: Stepan Miakchilo, Liubou Masiuk

Originally published at https://exadel.com on June 22, 2020.