Exadel Toolbox Lists: A Brand-New Way to Create a Generic List in AEM

Being an AEM developer is sometimes more about seeking than finding. Not every problem has an out-of-the-box solution. You can spend a lot of time looking for a comfortable way to implement a routine task, especially when it comes to data storage and retrieval.

A Day in the Life of an AEM Developer

Let’s imagine a day in the life of AEM developer Bob. Bob’s task is to create a new AEM component for the acme.com website: a country selector dropdown. It looks like this:

First of all, Bob needs to think about the data used in this dropdown. Each entry must contain the country’s official name and ISO code. From an authoring point of view, content administrators should have the ability to alter this list anytime and preferably make the same change on all localized versions of the site at the same time. So it looks like we need some kind of a list that would contain the name/code pairs list for this data.
Perhaps you’ve already guessed what well-known solution Bob used — ACS AEM Commons Generic Lists. This tool allows users to create and manage simple sets of key/value pairs. The country list will look like this:

Looking for the Perfect Solution

ACS Commons Generic Lists seemed to be a good choice for this task… until Bob learned that he also needs to store a localized name for each country. Bob has already used both the “Title” and “Value” properties, so where can he store the third value?
His first idea is to put the localized name in the same field as the English name and separate them by a comma. Sounds kinda… hacky, doesn’t it? First, if we look at ACS Commons Generic List as a tiny two-column table in AEM, this solution will violate the first normal form. Second, there may be countries that already contain a comma in the name! And lastly, if Bob needs to store another property in the future (for example, the country’s flag icon), managing this list will become a nightmare. In short, Generic Lists might not be the right solution after all.
After a little bit of research, Bob found another approach. In this insightful article, Matthew Sullivan explains how to extend Generic Lists by using arbitrary fields. This seems like it should be an optimal solution, but there is another catch. As of ACS Commons 4.3.4, Generic Lists have migrated to Touch UI, and these “extended lists” can no longer be opened or edited. The Touch UI interface of Generic Lists also has several other issues (1,2,3) that affect the authoring experience, including publishing lists and creating new lists under a specific folder. So we can see that while he’s gotten a bit closer, Bob still doesn’t have a perfect solution to his problem.
You can probably relate to Bob at this point, and we certainly have in the past. After reviewing all the possible solutions and assessing their pros and cons, the Exadel MarTech team decided that it was time to create our own tool for Lists in AEM that would leverage our experience to overcome some of the drawbacks of previous solutions.

Introducing Exadel Toolbox Lists

Exadel ToolboxLists is a brand new tool that provides a flexible way to manage collections of structured items in the TouchUI interface. It’s available in Exadel Authoring Kit for AEM — Part of Exadel Toolbox (EToolbox). You can check it out in our GitHub repository. Here, we’ll walk you through some examples and create our first EToolboxList:

• Open Sites Console (alternatively, you can open EToolboxLists Console: Tools -> EToolbox-> EToolbox Lists) and navigate to the folder where you’d like to have your list. Click “Create” -> List
  
• Specify the list’s title and select the item component (we’ll come back to item components later). For now, “Simple List Item” is a good choice.
  
• Open the created page. Now you can start adding your list entries!
  

EToolboxLists are based on regular AEM pages, so there is an OOTB ability to roll out, translate, and publish lists.
But what about our country selector example? How can we create a list item with our own arbitrary fields? The answer is simple: you just need to create an AEM Component that represents your item and add an @ListItem annotation. The sample item below features other AAT annotations like @DialogField or @TextField. You can learn more about them here.

That’s it! There’s no need to create new templates, policies, or XML configurations. Now “Country Item” will appear on the list of available item components. You can go to the ”Page Properties” dialog and change the item component for this list.


So now that the list is configured, how can we retrieve its entries in our service or model? There is a ListHelper utility that can read a list for you by its path. You can also adapt all the items to an arbitrary model and collect them into a list or map:

The compact and reusable data structures we’ve described have many applications across your AEM codebase. We hope that EToolboxLists and other fancy Exadel Toolboxfeatures will help you to manage your data and create simple yet flexible and extendable configurations for your AEM components and projects. We’re always working on new features and improvements and are always happy to get feedback or new ideas for the Exadel Authoring Kit for AEM.

Authors: Liubou Masiuk, Stepan Miakchilo