Little Bits of Polish in AEM

TL;DR

AEM implementors can see a large benefit with only a little effort if they take advantage of some of the more neglected out of the box features in AEM. Features such as component groups, thumbnails, descriptive text, and permissions can make authors more effective and happy while reducing the need for training on new features.

There are a number of small things that you can do to really elevate the quality of your AEM customizations. In this article I will discuss component groups, configurable iconography, descriptive text, permissions, and page properties.

These improvements are mostly small, and they mostly get ignored when an AEM implementation is tied to a tight deadline or budget. They aren’t mission critical but they can make the difference in user perception between an ok system and a great one.

These small things require very little development work, but do need to be well thought out to have maximum impact. Attention to detail here can help an author more quickly find a feature they need, or remind an author how something works. This will reduce requests for retraining, time for page authoring, and even potentially reduce feature requests and bugs filed.

Component Groups

Component Groups provide named divisions between components in AEM. Many projects use a single group to distinguish project components from native components. If we take the time to divide components into more granular groups by purpose, type, or other project specific criteria authors get multiple benefits.

First authors can find components more easily. If our implementation has multiple image galleries and the author knows they need one of them, they can filter by the image gallery group and pick one from the available list.

Authors can also more easily understand the purposes of newly introduced components without formal training. “This portfolio component is in the image gallery section. So it must be intended for displaying images.”

More granular component groups can also give administrators and template editors more control over which components are allowed in which locations, without forcing them to configure individual component allowances.

Coding Component Groups

The component group for your component is configured on the jcr:content node. Below is an example of how a custom component group can be applied to a component.

Sample .content.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:title="My Component Title"
    componentGroup="<Group Name Here>"
    cq:isContainer="{Boolean}false"
    cq:noDecoration="{Boolean}false"
    jcr:primaryType="cq:Component" />

Pretty Pictures

There are several locations where AEM offers the option to configure a custom image for use instead of the normal placeholder image. If the correct images are used, each of these locations can provide great benefits to the system’s authors and administrators.

The following is a list of the key configurable images in AEM that will assist in authoring the most.

Template Thumbnails

If you only have one template for your project, or you don’t create new pages very often, this might not be as useful, but many projects have a great many templates for specific purposes and create dozens of new pages every week. With the right images, picking the correct template for a page can be much more intuitive. The thumbnail can provide the author with a visual of what they’re going to get upon creation. This can be especially useful for distinguishing between flavors of the same page type (i.e. General Right Rail, and General Left Rail).

Basic template thumbnails can be configured by placing an appropriate image with the name thumbnail.png below the template node. Alternatively, if you are using Template Editor templates you can author a thumbnail for your custom template using the “Upload Image” button in the template’s properties.

Component Icons

I’ve found that component icons are the most useful configurable images of this type in the entire system. On one project they were so necessary that we introduced them via a customization before they were even an official part of the system!

When proper care is taken to choose correct icons and custom icons for each component, authors can drastically decrease their page creation time. It is much easier and quicker to find a component in a long list by its icon than by its name. Sometimes icons can be descriptive enough that authors can learn what a new component does just by looking at it in the side panel!

Component Icons use the cq:icon property. You can see a complete list of available icon options in the Coral UI documentation.

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    cq:icon="shoppingCart"
    jcr:description="We.Retail Shopping Cart"
    jcr:primaryType="cq:Component"
    jcr:title="Shopping Cart"
    componentGroup="We.Retail Commerce"/>

Alternatively you can use a custom image by adding it as a file below the component with the name cq:icon.png.

Asset Folder Thumbnails

Folder thumbnails facilitate fast navigation through the system by making identification of folders quicker with distinct visuals. Just like component icons, it is much easier to identify folders by image than by test. In addition, images can help clarify folder name meanings and thus decrease training time.

Luckily Assets folders get automatically generated thumbnails. So there is less work to do there, but sometimes the automatic thumbnails can be too ambiguous or can change without warning. So I recommend setting a specific thumbnail for important folders.

One nice thing about Asset folder thumbnails is that they are authorable. So you do not need a developer to make this change. For green field development, I still recommend that the developers set some initial thumbnails on important folders.

To configure asset folder thumbnails as an author, select the folder in the assets UI. Click properties. Then click “Change Thumbnail” and upload a new image from your file system. Note that you can’t use a reference to an asset in the DAM for this process.

To configure asset folder thumbnails as part of your code or part of a Package Manager package place a jpg file under folder’s jcr:content node (in this case a folder named _jcr_content) and name it manualThumbnail.jpg. You can also set a few properties on a node next to that named manualThumnbail.jpg.dir. To get more details make a sample folder with a thumnbnail using the UI, package it up and extract the package locally.

User Avatars

All of the optional user fields, and user avatars in particular, can be a great asset for administration, testing, and even developing.

Just like with the images and icons above, these images can help user admins sort through users in the User Management console in the Touch UI. Group avatars show up when assigning users to groups as well, which can help administrators more quickly determine that they’ve given a user the correct group memberships.

User’s avatars also show up on many of the navigation pages like Sites and Assets which can be be very useful. If you have a screenshot of one of these pages, use of unique avatars can add an additional piece of information when debugging issues. If a user has multiple accounts, then that user can more easily determine which account they are using. Since the avatars are visible by default, unlike user names, a multi account user may notice they are on the wrong account when they wouldn’t otherwise think to check.

In particular, I recommend setting specific avatars for the admin user and any test accounts that you have, even on local development instances. The admin avatar should be something that stands out – a red or orange background with an exclamation point will highlight that you’ve logged in as admin well. You can use the same color for the admin group. Other accounts and groups should use distinct color schemes for their avatars as well to decrease the amount of time it takes to determine which is which.

Regular users can set their own avatars by clicking on their existing avatar in the upper right on any management page (sites.html, assets.html, etc) and then click Profile, followed by “New Photo”.

Admins can set avatars for other users from /libs/granite/security/content/useradmin.html by selecting the user from the list and clicking “New Photo” on the edit screen.

Favicons for Custom Internal Pages

Favicons are specifically designed to allow users to more easily distinguish between open tabs at a glance. If your AEM customization set includes any custom internal facing pages, giving those pages unique favicons can help authors with multiple tabs open switch between them more easily.

For authorable pages, I recommend adding an inherited page property that lets the authors configure each page’s favicon. For specific pages developers should set a static icon.

<head>
    ...
    <link rel="shortcut icon" href="<path to favicon>/favicon.ico">
    ...
</head>

Getting Images Made

The easiest way to get proper images for these features is to have a developer on your team with basic Photoshop skills put them together. If you have a creative group at your company you may be able to get them to make a few for you. For some of these features, such as component icons, you even have the opportunity to use Adobe’s icon set from CoralUI.

When creating images for this purpose focus on simple colors and iconography. Take extra care to ensure that each image is easily distinguishable from the others in the set. You may want to define some project-wide mappings of colors to meaning such as the red or orange recommended for admins above.

Finally, if you only have the time to implement one of these items, I recommend focusing on the component icons. In-page authoring is the most complex task that most users will perform when interacting with AEM and component icons will help the most with that process.

Descriptions

Just like with images and thumbnails, filling in the customizable text throughout the project can help authors create content more quickly and accurately. Writing these bits of descriptive text requires some thought and iteration, but it does not take much development time and the benefits can be well worth it.

Dialog Field Descriptions

Dialog field descriptions provide a little snippet of text that shows up on hover of an element next to the field in a Component’s Touch UI dialog. There are a few useful things that we can add here: For complex components a longer form description of what behavior will result from different values can be useful. I also like to include information about the default value of each field.

Most fields use the fieldDescription property for this purpose as detailed in the Granite documentation.

<text jcr:primaryType="nt:unstructured"
    sling:resourceType="granite/ui/components/foundation/form/textfield"
    fieldLabel="Text"
    fieldDescription="Description goes here"
    name="./text" />

Custom Dialog Text

Note that the red text in the above image is part of the dialog’s html!

In some cases, dialog field descriptions are too hidden to be of much use. In those cases where an explicit message is needed, I recommend using a text widget to print out your message. Granite offers this widget out of the box but it isn’t usually called out in the dialog documentation because it isn’t technically a form field.

If you need your text to really stand out, you can even add custom classes to the surrounding span with the built in granite:class property and then add a custom css clientlib to the cq.authoring.editor category. With this combination you can put big red warnings in your dialogs if you need to.

<text jcr:primaryType="nt:unstructured"
    sling:resourceType="granite/ui/components/coral/foundation/text"
    granite:class="myCustomWarning"
    text="Do not change this unless you really know what you are doing!" />

.myCustomWarning {
    color: red;
    font-size: 3rem;
    line-height: 1.1;
}

Component and Template Descriptions

Components and templates both have dedicated fields for descriptions. Unfortunately, as of this writing they aren’t used for much. If your component and template names are at all ambiguous I would still recommend putting longer form descriptions in here. At the very least, other developers and administrators can see these descriptions in the code and in the repository. Hopefully these values will be given more visibility in a later version of AEM!

Both component and template descriptions are set by configuring a jcr:description property on item’s top level node. For template descriptions of editable templates, the description may also be set from the template’s properties by a template author.

___

If you don’t have time for all of these, focus on the dialog field descriptions for the most complex components. These are the places where it is most difficult to understand what to do as an author. Proper descriptions can save an author a lot of trial and error.

Hiding Stuff

If you have display options to users that never need those options then it causes confusion and slows down training and authoring. There are several places in AEM where you can hide unused options and make your author’s lives easier.

Unused Page Properties

There are a lot of default page properties. Most projects only use a subset of those properties to fulfill their feature sets. Properties that don’t do anything for your particular page component can be easily removed. In some cases you can drop out entire tabs. With fewer tabs and fields in the page properties, authors can find the properties they actually need much more quickly. I’ve even seen trained authors fill in fields that they’ve been told don’t do anything, because they weren’t sure and didn’t want to make a mistake.

To hide page properties use the merge properties provided by Sling’s Resource Merger.

Unused Nav Items

There are a lot of navigation items in the authoring UI. Many items like Screens, Personalization, and Commerce remain unused by many AEM customers. These items can be hidden or removed completely to streamline options for authors that don’t need them. It is much easier to remember where to go if you are presented with 2 options instead of 10.

If you want to remove one of these items for a single user or group, find the specific nav item node under /libs/cq/core/content/nav and remove that user or group’s view permission. If you want to hide the item from all users, including the admin, you can add a node under /apps that overlays it and set the sling:hideResource property to true.

<screens jcr:primaryType="nt:unstructured"
    sling:hideResource="{Boolean}true" />

Hiding Unused Folders and Content in Sites and Assets

Just like with navigation items, a complex instance can end up having a lot of content in Sites and Assets. You may have many users who only work with specific sections of that content. To make it easier for those users to focus on content intended for them, I recommend using permissions to conditionally show them only the items they really need.

If you don’t have time to work through all of these things, hiding unused folders and content in Sites and Assets is the most important in most cases. Many users will move through these navigation panels just often enough to slow them down but not often enough to remember which options are relevant for them. However in some instances where a large number of pages are created on a regular basis, you may find that hiding page properties is more important, especially if authors are regularly confused about which fields to use.

Package Properties

If you’ve ever worked with an AEM instance that has been active for a couple of years you will know that the package manager’s package list can become extremely cluttered. Filling in all of the package metadata makes managing packages in a long-lived AEM instance much easier. With these properties in place you can filter and search for packages and get a good idea of what each one does without having to rip it open.

Package Group

The package’s group is the simplest and most important package property that people leave out on a regular basis. With groups in place you can easily filter down to a specific category or type of package from the left hand side of the screen. I recommend using a special group name for your main code package, and a separate name for any main content packages. You may also want to separate Assets and Sites packages and create a special group for one time ad-hoc packages beyond the normal “My Packages” group.

Package Version

For the vast majority of packages you’ll create and build the package once and never come back to it, but for some packages you’ll modify them multiple times and rebuild regularly to get the most up to date content. To more easily distinguish between these I recommend adding a version number on your second build of the package and incrementing it with every subsequent build.

Package Description

A sentence about why you created the package can go a long way when you’re looking at the package a year later and trying to figure out what it was for. This can help you sort out important packages and help give you a way to audit your package list.

Package Dependencies

In some cases your packages will have dependencies. If you’ve ever installed a package of tagged assets before installing the package with the tags in it, you’ll know the pain of finding all your tags are gone. You can prevent this by making the tag package a dependency on the assets package. This can also be useful if your main source package depends on a certain service pack or cumulative feature pack.

Package Image

As with everything in the Pretty Pictures section of this article, images can make it easier to quickly find the appropriate package in the package list. I recommend giving your core code package a unique image so that you can find it quickly. Any other important packages should be treated the same way.

Package Screenshots

For complex feature packages, it can be helpful to include a few screenshots of the feature in action so you’ll know what you’re getting when you install it.

If you only have time for one of these, you should absolutely be setting the Package Group, but I really recommend also filling in the description whenever you can.

Conclusion

All of these small configurations and changes can really make your AEM customization pop! I hope that this gave you some new ideas of ways that you can make your AEM customizations easier to use. Remember, paying attention to the little details can make a huge difference!