Usability Tip: Use Contextual Help in your Adobe AEM Component Dialog

The world’s worst developer, Joe Gunchy (read more about Joe here) created a component Dialog with a regular text field to enter a date.  There is no indication on the Dialog how the user should format that date, but he made it a required field.   Should they type 8-Jan-14 or 1/8/2014?   Joe Gunchy is actually expecting day/month/year when he parses the date in his code.  It’s cool, he added a validation method on the field that repeatedly says “The format is wrong. Try again.”   – forcing the content author to start drinking before noon.  Joe Gunchy is not only a horrible developer, he’s an enabler.


What is “Contextual Help”?

Contextual help, or ’embedded help’, is simply instructions added to the component Dialog to assist the content author as they enter values into their input fields.   Adding instruction and a short example to the Dialog increases the usability of the component for the author.    Contextual help in an Adobe AEM component should be placed under each field to assist the Author during content entry. An example should also be included with the contextual help, such as:

“Please enter the Link’s Text. Example: Review the Story” or

“Please enter the destination link’s path or URL. Example:”.


How do you add contextual help?

On the Dialog properties, add a property named fieldDescription representing the help text.

Figure 1 – fieldDescription is used to add Contextual Help



How does it look on the Dialog?

The contextual help appears directly beneath the field as shown in the figure below.

Figure 2 – Contextual Help beneath the field with example text



Do you have a great usability tip? Please share in the comments!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s