The Essential Elements of Architecting for AEM Sites Pt 3

In Part 2 of our series, we discussed 3 fundamental steps that should be taken to group or organize the needed components for the website. In Part 3 we will discuss a series of questions that are meant to guide the architecting of the actual components.

Here are a set of questions and considerations that you need to ask about each of the components. Go back through all the components you have specified in the previous steps and give the necessary details. Droppable components are the area where you spend the majority of time asking yourself and defining these questions or considerations. They certainly do NOT apply to only the droppable components. These items are critical to all 3 types of components: droppable, page, and embedded. We have broken them up into two sections: Authorability of the component and Developer focused tasks.

Authorability of the components

  • What data can be authored? – We can’t stress how important this is. Defining what the author can do is the entire point of a CMS. A lot of what is content is easily brushed aside and is almost thought of as secondary in development. Also, knowing what is the output of the content, or what will be consumed by front end users is part of this. This is in its purest sense, the words that are read, the image that you see, the file that you download, etc. Defining the title, or the text field, or the image field is what is meant here. In these components from Booz Allen Hamilton (see screenshots below) the title, images, text, and links are content that a person authors. This should not be seen as the only thing related to “authoring”.
  • More controls or less controls? – There is a trade off from flexible components vs. components that are rigid. If you are flexible then you are likely to be complex, because it will likely have a ton of features and controls to allow the author to do a wide variety of things. The more rigid the component then the easier it is to build, because it will likely only do one or two very specific things. This becomes a type of spectrum, and your decision will likely fit somewhere in between. The key aspect of that decision is “do I want to have very few components that can do everything for me or do I want to have a ton of very specific comps?” There is no right or wrong answer.
  • Should there be one component or multiple components? – It might seem like the same question as the previous bullet, but it is not. This is where you begin to think about the configuration of the component, and what other controls need to be created in order to complete the “authoring” of the component. Not specifically content in its truest form, but still a part of the controls that an author will make to give the content its specific flavor or look. One of the biggest discussion points for you will likely be the List component (because it has been for almost every project I have been on). Do you make one list component with several style options or do you give them 5 different list components that do the same thing but differ only by style? This is a prime opportunity to involve the authors. Get their opinion, because there is no hard and fast rule. Frankly, this bullet point should be an entire blog post all to itself (and likely will be one day). And with the release of the new Style System for AEM 6.3 (Feature Pack 20593), it would be wise to discuss the options.
  • What does the dialog or interface look like? – This is where you really control the author experience. The impact will be felt greatly by the author. Your goal here is to define the interface for them. Notice that we did not say “design” the interface. Don’t worry about trying to take the time to mock it up with a fancy design, just write down the field types, field labels, validation, and formats, using the type of field that is appropriate (ex: radio button vs. checkbox). Be smart about how you delineate tabs. Keep elements that belong together on the same tab. (ex: Text and Image component – don’t separate its attendant metadata fields from the image portion of the component).
  • What is the Title of the component? – One of the simple yet underrated steps is to actually state the title of the component. This title should appear within the sidebar/sidekick, as well as within the edit dialogue. Too many times I have have seen a component not have its title written out on the component dialogue. Titles need to be distinct and signify what they are. Especially if you haven’t properly identified the allowed parents and children.
  • Do you have multiple component groups? – Assign a component group for the droppable components. If your implementation has multiple component groups then you need to make sure to label them in a comprehensible way. Define the name of the group and also decide which components belong together in a group. This can be arbitrary or based on usage, or based on the supertype it inherits from. If it is not supposed to be a droppable comp then make sure to mark them as “hidden”. Also, avoid putting your components in the “General” category. It’s all about making something that is logical to the people who are going to use it.
  • Page Properties. While not specifically part of the embedded or droppable components in the strictest sense, you need to make sure you decide what should belong in the Page Properties. Page Properties are mostly something you need to do for the Page Components, but it may have an impact on droppable and embedded components on other pages of the site. There may be some items that need to be controlled at the properties level, such as page elements, metadata, tags, etc.
  • What is the best thing for the author? – I told you I was a broken record. There is no real action step here beyond just thinking about how this component will be best used by the author. This again seems like a no-brainer, but I have seen many times when developers make choices for their convenience rather than what’s best for the author. In one case, a developer made a system that forced the Author to go into CRXDE Lite to change content. I know that it is not fair for the developer sometimes because they are under a time crunch to make the thing as quick as possible. You should take the time to help the author understand the tradeoffs and then get their buy-off. Don’t prioritize other things over the author.

Developer heavy focused tasks

  • Where does the component live in the repository? – /apps/[project name]/components/[component name]. Defining this will help the developer know where everything should belong and you won’t end up with things in the wrong place.
  • What are the allowed parents and children? – This is when you want to control or prevent components from being used on certain pages. Ex: a slideshow system – the main slideshow component holds the slideshow slide components. One of my previous customers had a slideshow system. The components that we made for it were only useful for the slideshow. As a solution, we limited the ability of the component, allowing the author to exclusively place on slideshow pages to avoid confusion. The last thing you want is a frustrated author calling you up asking why a component won’t work and then realizing that you didn’t tighten down the controls on their site better. Before you say it, yes having a properly titled component could prevent this, but I have seen too many people try to shove the square peg down the round hole when everything was completely labeled.
  • What is the supertype of the component? – This is a key decision to maximize the reusability and maintainability of the code. Sometimes the supertype is an OOTB component.
  • Can the content be cached by the Dispatcher? – If the answer is no then this is a red flag. One of your highest priorities in AEM development is to ensure that the content of a site is cachable. Due to the environment structure of AEM, allowing requests for content to get filtered down to the Publish server is a poor design. While it can be argued that some content is not cachable, this should be viewed and treated as an aberration or fringe case. If your first goal is to create a usable tool for the author, then your second goal should be the cachability of the content.
  • Screenshots from the design that points out what area of the page/site that the component will render in. – It’s important to provide some further detail visually. You don’t need to be overly detailed. A simple outline of the component in question should be sufficient to help narrow in on the important part of the page in question.
  • Is everything about the component clearly detailed in writing? – Take a few minutes and add a description to help prevent confusion about what the component will do or where it should belong. This is something specific for the developer and not the author. A good description can help a developer make sense of the flow of the component and prevent bad development decisions from being made. You don’t need a lot of wording, just enough to get the main point across.

Process Suggestion
One other thing to keep in mind is that this document should not contain information about end-user functionality. That belongs to a requirements doc, provided by the business owner or a Business Analyst. Just worry about the “what” of development, not specifically the how (ex: bootstrap). It doesn’t need to be a monolith. Stay focused on authoring and component breakdown.

And now that you have the architecture documents completed, you can begin building the structure of the components within AEM, while the front end developers begin working on the markup. Here are a set of steps you could take if you wanted to:

  1. Stub out all the components without anything in it.
  2. Assign out to people the individual components and have them build the dialogs.
  3. Process the data in the dialog, properly render the output of the data.
  4. Put in the markup.

You don’t have to wait for the markup to actually begin development in AEM.

Here is a document that shows additional examples of the Page, Embedded, and Droppable components, again from the preliminary Booz Allen Hamilton design. Part 4 will conclude by discussing how to architect the Page Templates as well as some other helpful advice.

Special thanks to Kem Elbrader for assisting in writing this series.