Keep Your Adobe AEM Project Out of Deep Sh*t

My grandpa once told me a story about the County troublemakers who lived in his boyhood town in rural Illinois. One unusually humid midwest summer, for five nights in a row, the troublemakers ran down the hill near the family outhouse,  rammed their bodies into the outhouse at full speed, and knocked it to the ground.  The next morning, my grandpa and his dad would have to reposition it back over its putrid sewage hole.

hi52f53e80We have to move it,” his dad said.

And they did. But, they didn’t move it far. He and my grandpa repositioned the outhouse only 3 feet in front of the existing sewage hole and covered the exposed area with sticks and straw. That evening, they hid in the shadows and waited for the troublemakers to arrive.

Just as expected, the troublemakers assembled in the darkness at the top of the hill and quietly giggled, “Charge!”    They rapidly descended towards the bottom of the hill,  ready to tackle the outhouse again. But, before they reached their goal, they fell feet-first into the exposed hole and were covered in sewage.

Why am I telling you this story on an Adobe AEM blog? Because it’s funny.  But there is a moral: If you don’t expect change, you’ll end up in deep sh*t.   

Customers are great at changing their minds.


I was recently asked how to convert an existing Adobe AEM site to be responsive to accommodate mobile devices.  The business leads initiating the project had not considered mobile during the initial discovery and development, but they changed their minds and now they want it. Surprise!

Unfortunately, converting an existing desktop-only site to be a responsive, mobile-optimized site is much more difficult to retrofit after it has been developed than anticipating change and planning for it in the beginning.   If your mark-up is well structured, it could just be an exercise of adding additional CSS and Javascript to support the new additional breakpoints. But that’s highly unlikely.  It’s much more realistic that you will have to modify mark-up in your components and templates to properly render in the new devices.

A generous estimate to make a site responsive by planning for it upfront is about 20% more in development time over a pure desktop experience.  This includes creating the mark-up, CSS, Javascript, and various image sizes to support two additional breakpoints: tablet and mobile phone.

Now compare this 20% to approximately 40% -100% additional development time to retrofit a site to be responsive. This includes auditing each component and template to ensure the mark-up is well-formed and ready to be styled for tablet and mobile phone, as well as the additional regression testing you’d have to do to re-verify the original desktop experience when mark-up and scripts change.  You could almost argue that this time could be increased even more by having to modify images in the Digital Asset Manager to support the new image sizes optimized for the various screen sizes.

What can you to today to keep out of the deep stuff?

As you plan your development for your desktop experience, assume the client will change their mind and prepare your site to be responsive, even if you don’t create the additional CSS and other coding necessary for the other platforms now (because you will). Structure your mark-up and CSS as if you’re coding a site to be responsive, but only fulfill the desktop requirement now.   Spend the time today and lay the groundwork so completing the tablet and mobile phone use-case costs only 10-15% to complete the remainder of the work, as opposed to the 40% retrofitting costs to implement.


If you find my articles useful, please share on your social networks!


Hiding Links from the Adobe AEM Welcome Screen

Unlike the world’s worst programmer Joe Gunchy (read more about Joe here) , you were smart and followed my guidance on developing your Adobe AEM project in the right order.  So we can assume you have Groups of users in your system with various permissions to access different sections of the site. Some Groups can manage workflow, some cannot.  Some can manage Tags, others cannot.

Did you know you can hide the links on the Welcome Screen to a Group of users so they never see them at all?


“Out of sight, out of mind.”



 Here’s how:

  • Navigate to the Users section of your site and click on the Group you want to hide a link from.
  • Double-click the Group name and select the Permissions tab


  • Navigate to one of the paths below and remove the VIEW option in the permissions.
Websites /libs/wcm/core/content/siteadmin
Digital Assets /libs/wcm/core/content/damadmin
Campaigns /libs/mcm/content/admin
Community /libs/collab/core/content/admin
CQ Inbox /libs/cq/workflow/content/inbox
Users /libs/cq/security/content/admin
Tools /libs/wcm/core/content/misc
Tagging /libs/cq/tagging/content/tagadmin
CloudServices /libs/cq/core/content/welcome/resources/cloudservices
Workflows /libs/cq/core/content/welcome/resources/workflows
Replication /libs/cq/core/content/welcome/resources/replication
Reports /libs/cq/core/content/welcome/resources/reports
Documentation /libs/cq/core/content/welcome/docs/docs
Developer Resources /libs/cq/core/content/welcome/docs/dev
CRXDE Lite /libs/cq/core/content/welcome/features/crxde
Packages /libs/cq/core/content/welcome/features/packages
Package Share /libs/cq/core/content/welcome/features/share
Clustering /libs/cq/core/content/welcome/features/cluster
Backup /libs/cq/core/content/welcome/features/backup
OSGI Console /libs/cq/core/content/welcome/features/config
  • Finito!

How to Reduce the Number of Templates in your Adobe AEM Project

The world’s worst developer, Joe Gunchy (read more about Joe here) is examining the website wireframes for his new Adobe AEM project to determine how many templates he needs to create. So far, he thinks he needs 17 – maybe more because of all the combinations of how the main content area is divided. 

“I make more templates because Content Authors are clueless.” – Joe Gunchy

One page has a single column for the main content that spans the entire width of the screen. He calls this the “single column template. On another, the main content area is divided into two equal parts, partitioned at 50%-50%, respectively.  He calls this the two column template.  Then there’s a three-column page where each column is divided evenly at 33%-33%-33%.    He found another two-column page is divided 66% on the left, 33% on the right.  He calls this the “two column – 2” template.  Wait, there’s one that’s divided 33% on the left, 66% on the right – “two column – 3”!   Oops, what about that page where the 66% part of the page is sub-divided into another two columns at 50% each – “two column – 4”? Then there are those product pages, press releases, employee profile pages, whitepaper downloads… Those should probably be another template, right? Joe Gunchy thinks so.   Joe Gunchy is an idiot.

“Two column – 76” – Joe Gunchy

When you’re examining website wireframes, do you make a new template to account for every combination of page layout you see like Joe Gunchy did? No way.  I would make one template and a Column Control component. That’s all you need.  

Despite what Joe Gunchy thinks, content authors are not dumb. With a simple Approval Workflow in place, a content author can and should be given the power to create flexible pages with any combination of page division, components, and content. Let the approving authority decide if it’s assembled to meet brand and style guidelines before publishing the page.


Enough is Enough

Check out the layout below.  Notice the main content area of the page is divided into two columns at 66%-33%.  Body copy spans the entire length of the left column. Then, the left side is split into two more columns where we put some promotional pods; then three columns below that.  How do you accommodate all of these combinations?  Let me show you how easy it is to create a page as ‘complex’ as the one below.  This site does it the right way.




Introduction to the Column Control

Adobe AEM comes with an out-of-the-box component called “Column Control”. Using ideas from this component in conjunction with the Paragraph System (the drag-and-drop feature of Adobe AEM) gives content authors the ability to divide and assemble a page in countless combinations.   Additionally, by adding and configuring a Paragraph System into each column, you can nest other Column Control components to further divide a content area into smaller columns to achieve, say, a 66% column on the left that is sub-divided into a 50%-50% split, etc. Configuring it is easy, and only a little work is necessary to style the columns to allow for the correct padding and margins as they are nested.

Here is the custom Column Control in action. Notice the nesting allowed by first dividing the page into 66%-33%, then we added another Column Control to the left column and selected 50%-50%. We then dragged in whatever content component we wanted into the Paragraph System to represent our content and our page is complete.



Here are the steps to create a custom Column Control component:

  • Create a new component named, “Page Division – Column Control”
  • Add a drop-down to your dialog with the various combinations of page divisions


  • Add a DIV for each column represented by each selection in your component JSP
  • Add a Paragraph System to each DIV in the component code to allow nesting.
<div class=”col-33″>
        <cq:include path=”right-par” resourceType=”foundation/components/parsys” />


That’s it.  With this one component, you can allow your content authors to create any page no matter how complex the layout may seem.  Let the content approver determine if the page meets their guidelines before publishing the page to the world.  Give your content author the power and ability to create any page by implementing this powerful component.



The Best Way to Test Targeting and Personalization in Adobe AEM

I recently implemented Targeting and Segmentation for a client using third-party targeting and personalization provider, Demandbase.  Demandbase stores vast amounts of information about companies, such as revenue range, major industry vertical (manufacturing, asset management, entertainment, etc), number of employees, region, and more.  When a visitor requests a page in Adobe AEM, the Demandbase API performs a look-up based on the visitor’s IP address and populates the ClientContext object with the various attributes in AEM for use in your Targeting segments. Then, targeted content is shown to the visitor when it matches the segment.

Our client has a huge library of whitepapers stored in the DAM and wanted to show “Recommended” whitepapers specific to the visitor’s industry.  That is, if a visitor from Wells Fargo visits the page, then we would show an Asset Management-specific whitepaper to them, since that is their primary industry.

I configured the various segments for each targeted industry, created content specific to those industries, and am now ready to test.  Wait? How do you actually test the content switching capabilities for each major industry based an IP address?

Client Context

1. You can use the Client Context to change a value manually – which is NOT actually a valid test. This only forces a value from the Client Context to assume a new value. Below I forced the value of my Industry to be “Non-profit” and content was changed on the page – but, it wasn’t changed by actually interrogating my IP address and switching dynamically. And it did not test it from the Dispatcher side as the visitor would see, only the Author instance.



Phone a Friend

You can call all of your friends in various Industries to visit the page and report back what they see. This probably works, but I don’t have that many friends.

The Best Way

You can spoof your IP addressing using a Firefox Add-On.


  • Visit the page with the teased content. You should now see the targeted content based on values gathered from the users IP address.  Use the IP address from a company in a known industry to see that they would see if visiting the page.

You can convert a company’s host name to their IP address with online tools such as Host to IP Address found here.

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!