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!


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!


What to look for when hiring a potential Adobe AEM developer

Adobe AEM is a hot product right now. Finding available, skilled talent is difficult, to say the least.  I get two to three messages on LinkedIn every week about project that is looking for someone with AEM experience. When assembling a team, you have a few options: use professional services consulting, partner with an experienced agency, or build a team of your own in-house.

Assuming you’re building a team in-house and you can’t find someone with AEM experience on their resume, what skills should you look for when hiring a developer to train as an AEM developer?  Developing in AEM is not difficult; however, there is definitely a learning curve around all of the underlying technologies (SLING, OSGi/Felix, JCR, etc), understanding best practices, comprehending all of the new terminology you’ll be bombarded with (DAM, CRX, MSM), and understanding CMS concepts in general.

Here’s a list of skills I look for when I’m building a team of developers who do NOT have AEM experience.  These skills truly lend themselves to molding a solid AEM candidate:

  • Servlet and JSP development  –  All of the templates and components in an AEM project are built using Java Server Pages (JSP), so 2-3 years experience with this is a must.  No JSP experience on the resume? Move on.

“No JSPs? Survey says? Bzzzzzzzz.”

  • CSS, Javascript, HTML – This is more for our front-end/HTML mark-up developers, but having your AEM developer with some CSS/Javascript experience is key, especially when we do AJAX calls or have to create custom Widgets using EXTJS. Also, having the ability to apply a quick style to the component instead of waiting for the Web Developer to do it only saves time for everyone.
  • AJAX/JQuery/EXTJS –  Adobe AEM pre-compiles published pages into static HTML, so dynamic content is pulled-in via AJAX – usually with a library like JQuery.  Additionally, EXTJS is used to create custom widgets for your editor dialogs. Experience with these is in my top 3 must-haves.
  • OSGi/FELIX – Scheduled jobs and services run as ‘bundles’ in the built-in Felix console.  While OSGi-specific experience is not a requirement, experience developing some type of service is required.  See below.
  • Web Services creation and consumption – Any dynamic content ingested from an external  service is usually accomplished by interacting with an service-layer running on an application server like Tomcat or JBOSS. A web services developer will be a key player on the team to assist with this interaction. You need at least one on the team with this skill.
  • CMS development experience – This isn’t a must-have, but understanding the concepts surrounding using a CMS versus traditional MVC (Model, View, Controller) development is helpful.  It helps with the learning curve of using a CMS.
  • Java Content Repository (JCR)/CRX – Getting away from the relational database mindset, where everything is tied together with some sort of key is a hard concept to grasp.  Not a must-have, but having someone on the team understand the underlying data repository who can evangelize it is a nice-to-have.
  • Other nice-to-haves – Eclipse IDE, Maven, SVN, Jenkins, Artifactory, Apache Sling, Lucene, Tomcat/JBoss, Apache web server, analytics tagging


Have you found a characteristic in your hiring practice that lends itself to become a great AEM developer? Share in the comments below.

From zero to coding your Adobe AEM project in less than 10 minutes

The world’s worst developer, Joe Gunchy (read more about Joe here) is leading a development team. He has 8 developers on the team, all running different operating systems and versions on their  laptops.  The guys wearing the skinny jeans and the hoodies are on OS X, the khaki pants/polo shirt guys use Windows, and “Charlie” uses Linux because he refuses to use an OS developed by “The Man”.   Joe has instructed everyone on the team to download and install the following things: Eclipse, Maven,  Maven plugin, an SVN plugin, Apache, an AEM Author instance, one Publish instance, Tomcat, and a Dispatcher to running in Apache.  No worries, he has 2 days for environment set-up scoped into the project – for each developer!  That’s 128 hours!  Each OS requires a different configuration, environment variables set in different places, and Charlie just can’t seem to get it running at all. It’s been a week for Charlie.

“Works on my machine” – Joe Gunchy


Zero to coding an AEM project in less than 10 minutes

Developer environment configuration and ramp-up time consumes many hours at the beginning of a project.  Differences in the developer’s hardware, development IDE set-up time and configuration, establishing connectivity to the source code repository all contribute to precious hours or even days wasted to get the team developing and building in a consistent, repeatable way.


What if you could go from zero to coding an AEM project in less than 10 minutes?  Without sounding too much like an ‘infomercial’, you can…

We exclusively use Vagrant images (link) for developing AEM projects.

“Vagrant provides easy to configure, reproducible, and portable work environments built on top of industry-standard technology and controlled by a single consistent workflow to help maximize the productivity and flexibility of you and your team.”   Put more simply, Vagrant allows you to “create and configure lightweight, reproducible, and portable development environments.

We have one pre-configured Vagrant image with AEM Author and Publish instances, a local HTTP server with a Dispatcher, all connectivity to SVN established, and MAVEN configurations for building – all installed and ready for a new developer to check-out and start coding.  Vagrant runs on top of a variety of Virtual Machine providers, such as VirtualBox and is supported on Windows, OSX, Linux. Best of all, it’s free.

Typing two commands will get a developer ready to code within minutes.

$ vagrant init name/of/image
$ vagrant up

With Vagrant, vagrant up is all you need to work on any project, to install every dependency that project needs, and to set up any networking and synced folders so you can continue working from the comfort of your own machine.

Spent the time up front with your architect to get a single, configured development environment ready and you’ll save numerous hours throughout the rest of the project.

 Vagrant up!


Share your results in the comments below.

Develop your Adobe AEM project in this order!

Did you know there is a certain order that most successful Adobe® AEM project are developed?  While this might sound elementary to some,  deviating from this order will certainly increase your development time and you will ultimately lose efficiencies gained by using this order.

From start to finish, your AEM project should be developed in this order:

  1. Static mark-up development
  2. Content page template creation
  3. Site structure creation
  4. Content-managed components (no dynamic content)
  5. Navigation components
  6. Scaffolding creation
  7. User configuration
  8. Services integration (dynamic content)
  9. Content entry
  10. Site search
  11. Workflow configuration and development

Why does this order matter?  Let’s take a look…


1. Static mark-up is complete

“Get the mark-up ready or don’t start coding at all.”

Never, ever, ever begin an AEM project without approved creative and a majority of the static mark-up that represents the page content completed. Templates, scaffolding, and components all depend on this structure (or snippets of the mark-up) for their creation.   At a minimum, the mark-up for general content pages containing the navigation, hero-space components, header/footer, right-rail should be ready.  From these, you can create a majority of the components.  I’m less concerned about that one-off Investor Relations page you have hidden in your footer. Get the mark-up ready representing a majority of your site, or don’t start coding at all. There is too much re-work to be done if the structure changes, which greatly outweighs the delay of  simply waiting.


2. Content page templates

Which template will get the most usage?  Forget those hidden pages in your footer links for now. Let’s get to the meat of the site where most of the content will be created and develop those templates first.  Once these are created, we can start assembling your basic site structure.  You will use the mark-up created in step 1 to develop these templates.

Do you have too many templates available to your content authors? Be sure to read my upcoming article on Limiting the Number of Templates and Components.


3. Site structure configuration

Once you have the basic content page created, you can begin assembling the structure of your site to include language branches and individual section landing pages, like “Products” or “Partners”. There won’t be anything on the pages at this point, but the bones of the site begin to take shape.  We will cover the right way to structure your site to support multiple regions and languages in a future lesson.


4. Content-managed components

Always work on the most basic, straight-content managed components before anything that requires services integration or other dynamic content.  These are the easiest components to complete and can be divided up between the development team without much dependency on each other.  Completing these first also allows you to start content entry and functional testing of the content page template and basic components.


5. Navigation components

Navigation components are anything that allows the user to, well, navigate around the site. Duh.  These include the main navigation, utility links in the header, footer links, breadcrumbs, language branch switching components, and any ‘calls-to-action’ like buttons, links, lists of links, etc.  Primary navigation and breadcrumb trails should be driven off of the site structure itself, so having this structure in place (as shown in step 3) is key.


6. Scaffolding creation

The Scaffolding feature in AEM is under-used and should be used when you create multiple pages of a certain type over and over again.  News and press releases, product detail pages, partner profiles, are great examples of pages that should use Scaffolding. A press release always has a headline, sub-head, author, date, body copy, and likely some boilerplate information about the company at the bottom of the press release.  Forcing a content author to manually assemble a page by dragging and dropping individual components like Title, Rich Text, Image then editing those individual components is way too time consuming.  Scaffolding essentially gives them a single form to fill in, and the values of the form are distributed to the individual components (created in step 4) through code when the page is saved. The effort to create a Scaffolding page and dialog is minimal but the time saved by using it repeatedly is immense.


7. User configuration

“Create a Group for each major section of the site.”

Now that you have the basic structure of the site created (including indivual landing pages for major sections of the site), you can configure the Users and Groups that will interact with those sections.   Start by creating a Group for each major section of the site (Products, Resources, Press Releases) and assign the appropriate permissions for the group to allow adding, editing, and deleting pages within that branch of the site.  Create Users and assign them to the Group. So, if “Joe” is a content author who is in charge of creating Press Releases, add him to the “Press Release” group and you’re done.  This way, you do not have to assign permissions to each individual.  These groups will come into play when we configure the approval workflow in step 11.


8. Services integration

You now have a decent representation of the site built, and now it’s time to breathe some life into it.   Services integration refers to any content such as stock ticker, Twitter feeds, login and registration services, CRM integration, e-Commerce, Google Maps, etc that gets added to a page that doesn’t involve a content author.   Due to the static nature of an AEM site, where the pages are pre-compiled into static mark-up, the dynamic content shown on the page should be retrieved and displayed using AJAX after page load.  This involves creating intermediate services layer that can retrieve content either from the JCR, or pass through to external service providers to retrieve the content.


9. Content entry

We have pages, we have components, we have Scaffolding, and we have services. Now we can enter some real content into the pages.  You’ll need this content for step 10.   This is also a good time to Tag the pages to associate similar content across parts of the site.


10. Site search

I recommend doing this near the end of development cycle for two reasons: 1) your services layer is now complete and ready to integrate with either your external search provider or internal search service and 2) we now have actual content to crawl and display in our search results.  Creating search functionality earlier in the project forces you mock up fake results which is really a waste of developer time.  Use real content.


11. Workflow configuration and development

I’m lazy, so I love the integrated workflow feature in AEM and use it extensively to automate processes to approve, publish, replicate, ingest content, etc.  Content authors create pages and submit them to the approval workflow for review. Once the content is reviewed and approved, the approving group can  publish the content to the live site automatically by clicking the APPROVE button.  I will explain in detail how to create an approval workflow model in a future article. But think about all the manual steps you do repeatedly during content creation and publishing and 9 times out of 10, these tasks can be automated using workflow.