AEM Component Development#

Those come from the decoration tag. AEM wraps each component in a div so the page editor has something to attach its toolbar and click handlers to.

Usually fine. But sometimes it breaks your CSS — particularly with flexbox and grid, where an unexpected wrapper changes the layout entirely.

Three ways to control it:

Per include, in HTL:

Copy Copy Always, on the component: cq:noDecoration="{Boolean}true" in .content.xml.

Change the tag rather than remove it:

Copy Copy That last one matters when the wrapper must be a valid child — inside a

, a
is invalid HTML but an

is correct.

A caution worth mentioning: removing decoration entirely makes a component harder to select in the editor, because the editor loses the element it attaches to. Usually the better answer is changing the tag name, not removing the wrapper.

4. Important Interview Questions 4.1 Basic Q1. What is a component in AEM?

A component is a folder under /apps that contains everything needed to render one type of content and to let authors edit it: an HTL script, a dialog, and usually a Sling Model behind it. The component node has the type cq:Component. Content is linked to it through the sling:resourceType property, so every node that names the component is rendered by it.

Cross: Where do they live? · What node type? (cq:Component) · What links content to a component?

Q2. What files make up a component?

A component folder usually contains .content.xml, which defines the component and its properties; an HTL file named after the folder, which renders it; and _cq_dialog, the form authors use to configure it. Optional parts include _cq_editConfig for editor behaviour, _cq_template for default values when the component is added, and a clientlib for its CSS and JavaScript. Strictly speaking, only .content.xml is mandatory.

Cross: Why _cq_dialog on disk but cq:dialog in CRXDE? · Which are mandatory? (strictly, only .content.xml) · What if there is no dialog? (authors can't configure it)

Q3. Why must the HTL file be named after the folder?

Because of Sling's script resolution rules. One rule looks for a script named after the last segment of the resource type. For energy/components/cta, the last segment is cta, so Sling looks for cta.html in that folder. If the file has any other name, Sling will not find it unless another rule matches, such as a selector-specific script like print.html.

Cross: What if you name it something else? (not found, unless another rule matches) · Can a component have several HTL files? (yes — selector-based, like print.html)

Q4. What is componentGroup?

componentGroup sets the group under which a component appears in the page editor's component browser, such as "Energy – Content". If the value is .hidden, the component never appears there, which is useful for helper components such as accordion items that should only be created by their parent. Note that a component can also be missing because the template's policy does not allow it.

Cross: Why hide one deliberately? (helper components like accordion items) · Is that the only reason it might not appear? (no — template policy is the other)

Q5. What is sling:resourceSuperType?

sling:resourceSuperType is the inheritance pointer between components. When Sling cannot find a script, dialog or other file in a component, it looks in the component named by this property, and continues up the chain through as many levels as exist. This is what makes the proxy pattern possible: a proxy inherits everything from a Core Component and overrides only what it needs.

Cross: Difference from sling:resourceType? · Can you inherit through several levels? (yes) · What does it enable? (the proxy pattern)

Q6. What is cq:dialog?

cq:dialog is the Touch UI dialog — the form authors fill in to configure a component. It is built from Granite UI field types arranged in containers, tabs and items, and each field writes its value to a property on the component's content node. It replaced the old Classic UI dialog, and in editable templates the old design dialog has been replaced by policies.

Cross: What was the old one? (dialog, Classic UI — deprecated) · What is cq:design_dialog? (design dialog for static templates; replaced by policies in editable templates)

Q7. What does ./ mean in name="./linkText"?

It tells the Sling POST Servlet to store the value relative to the component's own content node, so ./linkText becomes the property linkText on that node. Without ./, the value is written somewhere else and the component silently reads nothing. The same servlet also understands suffixes such as @TypeHint to set a property's type and @Delete to remove a property.

Cross: What processes that POST? (Sling Post Servlet) · What is @TypeHint? · How do you delete a property? (@Delete)

Q8. What is a Core Component?

Core Components are Adobe's library of ready-made, production-quality components, such as Title, Text, Image, Teaser and Container. They are accessible, well tested, versioned and released independently of AEM itself. Projects should not use them directly in content; instead, each one is wrapped in a project-specific proxy component that inherits from it.

Cross: Where do they live? · Why version folders like v1, v2? · Should you use them directly? (no — proxy them)

Q9. What is cq:editConfig for?

cq:editConfig controls how a component behaves inside the page editor. It configures toolbar actions, listeners such as REFRESH_PAGE after an edit, drop targets for dragging assets onto the component, and in-place editing. It has no effect on the published page, and it is optional — most simple components do not need one.

Cross: Mandatory? (no) · What does REFRESH_PAGE do and when do you need it? · What is cq:dropTargets?

Q10. What is cq:template inside a component?

cq:template inside a component holds default property values that are copied onto the new content node when an author first adds the component to a page. For example, it can pre-fill a heading level or a placeholder title. It is stored as _cq_template in the component folder and is completely unrelated to page templates.

Cross: How is that different from a page template? (completely different thing) · Where does it live? (_cq_template in the component folder)

4.2 Intermediate Q11. What is a proxy component and why do we use it?

A proxy component is a small component in your project that inherits from a Core Component through sling:resourceSuperType, and content refers to the proxy instead of Adobe's path. There are three reasons to use one. You can selectively override parts, such as the HTL or the dialog. You control which version of the Core Component is used, because upgrading means changing one pointer. And your content is decoupled from Adobe's internal paths, so an upgrade never requires rewriting content.

Cross: What's actually in the file? · How do you upgrade v1 to v2? · What if you skip the proxy?

Q12. How do you add one field to an inherited dialog without copying it?

Use the Sling Resource Merger. Create a dialog in your component that contains only the new field, and position it with sling:orderBefore; everything else is inherited from the parent dialog. You can remove an inherited field with sling:hideResource. This is better than copying the dialog, because a copy stops receiving Adobe's improvements and has to be maintained by hand.

Cross: Which mount path? (/mnt/overlay) · How do you reorder? · Why not just copy the dialog? (you stop receiving Adobe's improvements)

Q13. What is the difference between a simple and a composite multifield?

A simple multifield repeats a single field, and its values are stored as one multi-value property on the component node — for example, a list of tags. A composite multifield repeats a group of fields, such as a question and an answer, and stores each entry as a child node named item0, item1 and so on. It needs composite="{Boolean}true"; without it, only the first field of each entry is saved. In a Sling Model you read the first with @ValueMapValue as an array or list, and the second with @ChildResource.

Cross: How do you read each in a model? · What are the child nodes called? (item0, item1, …) · What breaks without composite=true? (only the first field saves)

Q14. What is the difference between extending and overlaying a component?

Extending means creating a new component that inherits from another through sling:resourceSuperType; the change affects only your new component. Overlaying means placing a file under /apps at the same relative path as one in /libs, which replaces the product version everywhere. Extend by default, and overlay only when you must customise AEM's own authoring interface, because every overlay has to be checked on each upgrade.

Cross: When would you ever overlay? (adding a tab to page properties) · Which is safer on upgrade? · How does the Resource Merger relate to each?

Q15. Where does component logic go?

Component logic belongs in a Sling Model in the core bundle, not in the HTL. HTL is deliberately restricted — it cannot run arbitrary Java — which keeps templates simple and secure. The HTL calls the model with data-sly-use, and the model contains the logic in a plain Java class that can be unit tested with AEM Mocks.

Cross: Why can't you write logic in HTL? (by design, for security and testability) · What came before Sling Models? (WCMUsePojo, then JSP) · How do you unit test it?

Q16. Why do extra div elements appear around my component?

They are decoration tags, which AEM adds around each component so the editor can select it and so the Style System has an element to apply classes to. You can change the element with cq:htmlTag or decorationTagName — for example to li inside a list — or remove it with cq:noDecoration or decoration=false. Removing it entirely makes the component harder to select in the editor, so it is rarely the right choice.

Cross: Why not always disable it? (harder to select in the editor) · When would you change the tag? (inside a

)

Q17. How do you make a component available on a page?

Two layers must both allow it. First, the component needs a visible componentGroup, so it is not hidden. Second, the template's policy on the container where the author wants to place it must list the component, or its group, as allowed. The policy is the deciding layer: if it does not allow the component, authors never see it, regardless of anything in the component itself.

Cross: Where are policies stored? (under /conf//settings/wcm/policies) · Can two templates allow different components? (yes — each has its own policies) · What controls which templates can be used under a page? (cq:allowedTemplates)

Q18. What is cq:isContainer?

cq:isContainer marks a component as one that can hold other components, so the editor treats it as a drop zone. Examples are the Layout Container, Tabs and Accordion. What authors can place inside it is controlled by a policy on the container, and the container renders its children with data-sly-resource over its child resources.

Cross: Example? (Layout Container, tabs, accordion) · How do you restrict what goes inside? (a policy on the container) · How do children render? (data-sly-resource over child resources)

Q19. How does in-place editing work?

In-place editing lets authors edit text directly on the page instead of in a dialog. It is configured in cq:editConfig under cq:inplaceEditing, with an editor type such as text for rich text, or title or plaintext for simple text. The value is saved through the same Sling POST Servlet as a dialog. You might disable it for rich text that must follow strict formatting rules.

Cross: How does the value save? (same Sling Post Servlet) · Why might you disable it? (rich text with strict formatting rules)

Q20. How do you version a component?

Follow the Core Components convention: each version lives in its own folder, such as v1 and v2, and the proxy component points at the version you want. Existing content refers to the proxy, so it keeps working. You never change a released version in place, because existing content depends on its markup and properties; a breaking change becomes a new version, with a content migration if pages should move to it.

Cross: Why not edit in place? (you'd break existing content) · How do you migrate content between versions?

4.3 Advanced Q21. How would you build a listing component whose items come from the page tree rather than being hand-authored?

Work through four decisions.

Traverse or query. If the items live under one known parent page, traverse its children: it needs no index and is predictable. If they can be anywhere and are selected by tag, you must query, which means confirming an Oak index exists and always setting a limit. Where the work happens. Build the list once in @PostConstruct, not in a getter that HTL might call repeatedly inside a loop. How much renders on the server. For a long list, render the first batch on the server so the page is fast and crawlable, and load the rest through a servlet. Keep that servlet cacheable by registering it by resource type with a selector and passing the batch number as a suffix, not a query parameter. Invalidation. A derived listing goes stale when a child page is published, so add a flush rule that invalidates the listing page when its children are activated. Cross: Query or traverse — how do you decide? · Is your query indexed and how do you know? · Why a suffix and not a query parameter? · What happens when an author adds a new product?

Q22. A component works on author but is blank on publish. How do you debug it?

Work through these checks in order:

Read error.log on publish first. A model using the optional injection strategy renders nothing instead of throwing, so the real error may only appear in the log. Confirm that everything the component references was activated — assets, fragments and, for listings, the child pages themselves. Check that the anonymous user can read every path the component reads. Check that the component's clientlib is loading, including allowProxy on the clientlib folder. Check whether the model depends on something that only exists on author. Cross: Why does OPTIONAL hide the problem? · How do you test as anonymous? (private window, direct publish URL) · What does the dispatcher have to do with it?

Q23. How do you make a component accessible?

Use semantic HTML rather than generic div elements, correct heading levels, and alt text supplied through a dialog field. Add ARIA attributes only where native semantics are not enough, make every interactive element usable with the keyboard, and ensure sufficient colour contrast. Extending Core Components also helps, because they are built to WCAG standards, so you inherit that work. Test with tools such as axe and Lighthouse, and by navigating with the keyboard alone.

Cross: How do you test? (axe, Lighthouse, keyboard-only) · Whose job is alt text? (developer provides the field, author fills it, component handles it being empty) · What is a decorative image?

Q24. How do you handle a component that must render differently on mobile?

Prefer CSS and responsive design. If the markup genuinely has to differ, use the Style System or an author-controlled option — never server-side user-agent detection. Device detection on the server breaks dispatcher caching: either every device variant needs its own cache entry, or one variant is cached and served to everyone.

Cross: Why is server-side device detection dangerous with a cache? · What is the Style System? · How do responsive images work in AEM?

Q25. How do you unit test a component?

Test the Sling Model, because that is where the logic lives; HTL itself is not practical to unit test. Use JUnit 5 with AEM Mocks: load test content from a JSON file into AemContext, register the model and any services it needs, adapt a resource to the model, and assert on its output. Services the model depends on can be replaced with mocks using context.registerService.

Cross: What is AemContext? · How do you mock an injected OSGi service? (context.registerService) · What does Cloud Manager's quality gate check?

Q26. How would you let authors change a component's appearance without new components?

Use the Style System. Style options are defined in the component's policy, the author picks one from the component's toolbar, and AEM adds the corresponding CSS class to the component's wrapper element. No code change or new component is needed, and the available styles are controlled centrally per template rather than per component instance.

Cross: Where are styles defined? (in the policy) · How is the class applied? (on the decoration wrapper) · Why better than a dialog dropdown? (controlled centrally per template, no code)

Q27. What is the Sling Model Exporter and why does it matter here?

The Sling Model Exporter serialises a Sling Model to JSON, available at .model.json, by adding @Exporter(name = "jackson", extensions = "json") to the model. It is how a component's authored content reaches a single-page application or a mobile app. Unlike Content Fragments delivered through GraphQL, it follows the structure of the page and its components.

Cross: Which selector and extension does it use? (model and json) · How does it relate to the SPA Editor? (the SPA Editor renders pages from this JSON) · How does it differ from Content Fragments with GraphQL? (page-shaped output versus structured content)

Q28. How do you handle validation in a dialog?

Granite UI provides basic validation on fields, such as required="{Boolean}true". For anything more, register a custom validator in JavaScript with the Granite UI validation registry, targeting a field by a validation attribute or a selector. The script is placed in a clientlib with the category cq.authoring.dialog so it loads only in the editor. A custom validator can also compare two fields.

Cross: Where does the JavaScript live? (a clientlib with the category cq.authoring.dialog) · How do you show the error message? (return it from the validator function) · Can you validate across two fields? (yes, with a custom validator)

4.4 Scenario based Q29. An author saves the dialog, but nothing appears on the page. What do you check?

Check, in order: a field name missing its ./ prefix; the model reading a property with a different name; an optional injection hiding a failure; and the page being served from the dispatcher cache. Then open the node in CRXDE Lite. That single check splits the problem cleanly: if the property is missing, the dialog did not save it; if it is there, the component is not reading it.

Q30. A component works on one template but not on another. Why?

Almost certainly because of the template's policy. Each template has its own policies, and on the second template the container's policy does not list this component, or its group, as allowed. Check the policy for that container in the template editor rather than changing the component.

Q31. After upgrading Core Components, some pages broke. What went wrong?

The content referred to Adobe's resource type directly instead of a proxy component, so it was tied to a specific version, and the upgrade changed the markup or property names. The immediate fix is to roll back the version or migrate the affected content. The long-term fix is to introduce proxy components and point the content at them, so future upgrades are a deliberate change to one pointer.

Q32. Authors say a component is confusing to use. How do you improve it?

Improve the dialog rather than dismiss the feedback. Add help text with fieldDescription, group related fields into clear tabs, show examples with emptyText placeholders, provide sensible defaults through cq:template, and mark genuinely required fields as required, so authors get immediate feedback instead of a blank component on the page.

Q33. The same component must look different for three product lines. How do you build it?

Use the Style System with different style definitions in each template's policy: one component, three policies. Do not build three separate components, which triples the maintenance, and do not add a "brand" dropdown to the dialog, which spreads a styling decision into every content instance.

Q34. A component has made the page very slow. How do you fix it?

Measure first, then fix the cause. The usual culprits are a synchronous external API call during rendering, a query without an index, or an expensive getter called repeatedly from an HTL loop. The fixes are, respectively, to cache the external data or load it client-side, to add an index, and to do the work once in @PostConstruct.

4.5 Production support Q35. A component appears in the component browser, but authors cannot drop it onto the page. Why?

Either the policy of the container they are dropping into does not allow that component, or the target area is not actually a container. Check the container's policy in the template editor; the component browser shows every component allowed anywhere on the page, not only in a specific container.

Q36. A component renders, but without any styling. What do you check?

Check that the component's clientlib is actually loaded on the page. The usual causes are that the clientlib's category is not included by the page or template, that allowProxy is not set to true on the clientlib folder (so the browser cannot fetch it from /etc.clientlibs on publish), or a typo in the category name.

Q37. A component still shows old content after an author edits it. Why?

On publish, the page is probably being served from the dispatcher cache and has not been invalidated. In the editor, the component may need REFRESH_PAGE in its cq:editConfig listeners, because by default the editor refreshes only the component itself and can show a stale fragment when the change affects other parts of the page.

Q38. A component's dialog will not open. Where do you start?

Open the browser console first. The usual causes are malformed dialog XML, a field with an incorrect sling:resourceType, or a JavaScript error in a custom validator clientlib that stops the dialog from initialising.

Q39. A component works locally but not on the server. What do you check?

Check that the package's filter.xml actually includes the component's path, so it was deployed at all, and that the Java bundle deployed and is Active in the Felix console. A path missing from the filter is easy to overlook, because it works locally where the files were created by hand or by an earlier build.

5. Cross Questions — how this topic gets drilled Thread A — from "tell me about a component you built" What did the dialog look like? → Multifield? → Simple or composite? → How did you read it in the model? → What node structure resulted? → What if the author adds fifty rows? → How did you validate? → What happened when a field was empty?

Thread B — from "do you use Core Components?" Which ones? → Directly or proxied? → What is a proxy? → What's in the file? → How do you override just the markup? → How do you add one dialog field? → What is the Resource Merger? → How do you hide an inherited field? → How would you upgrade v1 to v2?

Thread C — from "how does a dialog save data?" What handles the POST? → What is the Sling Post Servlet? → What does ./ mean? → What happens without it? → What is @TypeHint? → How do you delete a property? → How does a composite multifield become child nodes?

Thread D — from "how do you decide to build a custom component?" Why not Core Components? → What can the Style System do instead? → Where are styles defined? → What if the markup must differ, not just CSS? → Extend or overlay? → Which is safer on upgrade?

6. Best Interview Answers 6.1 "Walk me through how you build a component" — about 2 minutes "I'd start by asking whether I should build one at all. My first check is whether a Core Component already does most of it, because extending one gives me accessibility and Adobe's ongoing maintenance for free.

Assuming I do need one, I create a folder under /apps//components/. The .content.xml marks it as a cq:Component with a title, description and componentGroup — and if it's a helper component authors shouldn't place directly, I set the group to .hidden.

If I'm extending a Core Component, that same file gets sling:resourceSuperType, and often that's the entire component — a proxy with no other files, inheriting everything.

The rendering script is an HTL file named after the folder, because Sling's script resolution looks for a script matching the last segment of the resource type. The HTL stays presentation-only; logic goes into a Sling Model in the core bundle that HTL calls with data-sly-use, which keeps it unit-testable.

The dialog goes in _cq_dialog as Granite UI resource types — containers and items nested down to the fields. The detail I'm careful about is the ./ prefix on every field name, because without it the Sling Post Servlet writes the value to the parent node and the component silently reads nothing.

Then optionally _cq_editConfig — I'll add REFRESH_PAGE if editing this component changes something outside itself — and _cq_template for sensible defaults.

Finally a unit test on the Sling Model with AEM Mocks, because Cloud Manager's quality gate checks coverage on new code."

6.2 The graded answer — simple, medium, complex Interviewers frequently ask for a component story twice: "give me a simple one first", then "now the most complex thing you've built." Here are all three, at the right length.

Simple — about 1 minute

"The simplest one I own is our CTA component. It's a single link that renders either as a button or as an arrow link — the pattern you see all over the site as 'Read the Press Release' or 'Explore more' with a chevron.

Three dialog fields: link text, a pathfield for the target, and a checkbox for opening in a new tab. Plus a style dropdown for button versus arrow link.

It sounds trivial but it has three details I'd call out. The link can point at an internal page or a PDF in our document publishing system, so the model resolves internal paths through resourceResolver.map() to get the short URL, and leaves external ones alone. Second, when the author ticks 'open in new tab' the model emits rel="noopener noreferrer" alongside target="_blank", because without it the opened page can manipulate window.opener. Third, the checkbox needed an uncheckedValue, because otherwise unticking it deletes the property rather than setting it false, which isn't the same thing to the model.

The value of building it was consistency — it replaced about six hand-coded link variants across the site with one component the design system controls."

Medium — about 2 minutes

"A step up is our FAQ accordion. Product category pages have FAQ sections — things like 'What is a transformer in electricity?' — and they're written by the content team primarily for SEO, because industrial buyers search technical questions.

The dialog is a composite multifield: each row has a question as a textfield and an answer as rich text. Composite matters here — with composite=true and the field node as a container, each row becomes a child node like faqs/item0 with both properties on it, rather than a flat string array. In the model I read those with @ChildResource into a list of a small nested model class.

Two things made it more interesting than it looks. First, accessibility — an accordion has a real ARIA contract. Each header is a button with aria-expanded and aria-controls, each panel has an id and role="region" with aria-labelledby back to the button. That means generating stable unique IDs, and they have to stay unique when there are two accordions on one page, so I derived them from the component's own path rather than a counter.

Second, SEO — since these exist for search, I emit FAQPage structured data as JSON-LD alongside the markup, so the questions can appear as rich results. That needed the answer's rich text stripped of HTML for the structured data while keeping it for display.

The result was that FAQ content started appearing as expandable results in search, which was the whole point of the requirement."

Complex — about 3 minutes. This is section 7's flagship story; see below.

6.3 "Tell me about a complex component you developed recently" — the full answer The structure that works: requirement → what made it complex → approach → the hard part → outcome.

The critical move is "what made it complex." Do not describe a component with lots of fields — that is tedious, not complex. Name a genuine technical challenge: an integration, a caching conflict, a performance problem, or an authoring constraint fighting the technical design.

Here it is delivered in full:

"The most involved one is our product category listing — the component behind the main Products and Solutions landing page.

The requirement looked simple: show product categories as cards, grouped into three tabs — products and systems, software, and solutions — with a Load More button because there are more than twenty categories in some tabs.

What made it complex was that the cards can't be hand-authored. We have hundreds of product category pages and the portfolio changes constantly. If an author had to add a card manually every time marketing launched a category, it would be permanently out of date. So the cards are derived from the page tree — each card is a child page under a configurable root, with its title, description and thumbnail read from that page's properties, filtered by tag.

That created three problems that fought each other.

First, the query. My initial version ran a repository-wide QueryBuilder query filtered by tag. It worked locally on a small content set and was slow on stage. Checking the Query Performance tool showed it wasn't hitting an index cleanly and Oak was traversing. I ended up restricting the search to a known path so the traversal was bounded, added a proper limit, and where a genuine tag query was needed we deployed a custom index. The lesson I'd give anyone is that a query that works on a laptop tells you nothing.

Second, the Load More. The obvious implementation fetches the next batch with a query parameter — something like ?offset=20. But query parameters aren't part of the URL path, so the dispatcher won't cache those responses, and every Load More click would go through to publish. Instead I registered a servlet by resource type with a cards selector and passed the batch number as a suffix — so the URL is a stable path that the dispatcher caches like any other file. Same data, but cacheable.

Third, invalidation. Because the listing is derived, publishing a new product page doesn't tell the listing page's cache anything — the listing stays stale until something else flushes it. We handled that with a flush rule so activating a child page invalidates the parent listing.

The hardest part was actually the first batch. For SEO and first paint, the initial set of cards has to be in the server-rendered HTML — a crawler won't click Load More. But the later batches come from the servlet. So the same card markup had to render two ways, from HTL server-side and from the JSON response client-side, and they had to be identical or the grid visibly broke at the boundary. I solved it by having the servlet return the rendered HTML fragment rather than raw JSON, so there was exactly one template for a card.

The outcome was that the listing page stayed fully dispatcher-cacheable including the Load More responses, the page stopped going stale when the portfolio changed, and the content team stopped raising tickets to add cards — the page just reflects whatever they publish."

Why this answer works. It names a specific, believable requirement. It identifies genuine trade-offs rather than listing features. It shows architectural judgment — the suffix-versus-query-parameter decision is exactly the thinking file 01 taught. It includes a mistake the candidate learned from, which reads as honest. And every sentence invites a follow-up you can answer.

7. Real Project Examples Three stories, one per level, all from the same coherent project. Pick the ones you can defend and make them yours.

Story 1 (Simple) — the CTA component Requirement. Product and news pages needed consistent call-to-action links — "Read the Press Release", "Read the Customer Success Story", "Explore more" — some rendered as buttons, some as arrow links.

Why it was worth building. Before it existed, these were hand-coded inside other components and inside rich text, so there were about six visual variants and none of them matched the design system exactly. Accessibility was inconsistent too — some were

elements with click handlers rather than real links, so keyboard users couldn't reach them.

Approach. One component, four dialog fields: link text, target path, open-in-new-tab, and a style dropdown for button versus arrow. The model resolves internal paths through resourceResolver.map() so links render as short URLs rather than /content/... paths, and leaves external URLs untouched. Links to the document publishing system open in a new tab by default and get a file-type indicator.

The details that mattered. Always a real element, never a div with a click handler. rel="noopener noreferrer" whenever target="_blank". And uncheckedValue on the checkbox, because without it unticking the box deletes the property rather than setting it false — which the model can't distinguish from "never configured."

Result. Six variants collapsed into one component. Accessibility audit findings on link semantics went to zero, and the design team could change CTA styling in one place.

Story 2 (Medium) — the FAQ accordion Requirement. Product category pages needed FAQ sections. The content team writes them for SEO, because industrial buyers search technical questions like "what does an electrical transformer do."

What made it more than trivial. Three things: a composite multifield with rich-text answers, a real accessibility contract, and structured data for search.

Approach. A composite multifield where each row is a question textfield and a rich-text answer. Read in the model with @ChildResource into a list of a nested model class.

The hard parts.

Accessibility. An accordion has a defined ARIA pattern — each header is a with aria-expanded and aria-controls, each panel has an id, role="region" and aria-labelledby pointing back. That requires stable unique IDs, and they must stay unique when two accordions appear on one page. Deriving them from a counter broke exactly that case, so I derived them from the component's own resource path instead.

Structured data. Since the content exists for SEO, the component emits FAQPage JSON-LD so questions can appear as rich results. That meant stripping HTML from the rich-text answer for the structured data while keeping it for display — and being careful not to emit invalid JSON when an author's answer contained quotes.

Result. FAQ content began appearing as expandable results in search, which was the requirement's actual goal. And the pattern was reused for a technical-specifications accordion on product detail pages.

Story 3 (Complex) — the tabbed product category listing with Load More Requirement. The main Products and Solutions landing page shows product categories as cards, grouped into three tabs, with Load More because some tabs hold more than twenty categories.

What made it complex. The cards cannot be hand-authored — there are hundreds of category pages and the portfolio changes constantly. So cards are derived from the page tree, and that single decision created three conflicting problems.

Problem one — the query. The first version ran a repository-wide tag query. Fine locally, slow on stage. The Query Performance tool showed Oak traversing rather than using an index cleanly. Fixed by restricting the search to a known root path so traversal was bounded, always setting a limit, and deploying a custom index where a genuine tag query was unavoidable.

Problem two — Load More versus caching. The obvious approach passes an offset as a query parameter, which the dispatcher will not cache — so every Load More click reaches publish. Instead, a servlet registered by resource type with a cards selector, taking the batch number as a suffix. Same data, stable path, fully cacheable.

Problem three — stale listings. A derived listing does not know when a new product page is published. Handled with a flush rule so activating a child page invalidates the parent listing.

The hardest part. The first batch has to be server-rendered for SEO and first paint, because a crawler will not click Load More. But later batches come from the servlet. Two rendering paths for identical markup meant the grid visibly broke at the batch boundary whenever they drifted apart. Solved by having the servlet return a rendered HTML fragment rather than raw JSON, so there is exactly one card template.

Result. The listing page stayed fully dispatcher-cacheable including Load More responses, stopped going stale as the portfolio changed, and the content team stopped raising tickets to add cards.

8. Coding Examples Now let's build all three, in order, so you can see the difficulty ramp.

8A. SIMPLE — the CTA component 8A.1 Component definition /apps/energy/components/cta/.content.xml

<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" jcr:primaryType="cq:Component" jcr:title="Call to Action" jcr:description="A single link rendered as a button or an arrow link" componentGroup="Energy - Content"/>Copy Copy 8A.2 Dialog /apps/energy/components/cta/_cq_dialog/.content.xml

<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" jcr:primaryType="nt:unstructured" jcr:title="Call to Action" sling:resourceType="cq/gui/components/authoring/dialog">

                        <linkText
                            jcr:primaryType="nt:unstructured"
                            sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                            fieldLabel="Link Text"
                            fieldDescription="Must make sense on its own. Screen reader users may hear it out of context, so avoid 'Click here'."
                            name="./linkText"
                            required="{Boolean}true"/>

                        <linkUrl
                            jcr:primaryType="nt:unstructured"
                            sling:resourceType="granite/ui/components/coral/foundation/form/pathfield"
                            fieldLabel="Link Target"
                            fieldDescription="Pick a page, or paste an external URL"
                            name="./linkUrl"
                            rootPath="/content"
                            required="{Boolean}true"/>

                        <style
                            jcr:primaryType="nt:unstructured"
                            sling:resourceType="granite/ui/components/coral/foundation/form/select"
                            fieldLabel="Style"
                            name="./style">
                            <items jcr:primaryType="nt:unstructured">
                                <arrow
                                    jcr:primaryType="nt:unstructured"
                                    text="Arrow link"
                                    value="arrow"
                                    selected="{Boolean}true"/>
                                <button
                                    jcr:primaryType="nt:unstructured"
                                    text="Button"
                                    value="button"/>
                            </items>
                        </style>

                        <newTab
                            jcr:primaryType="nt:unstructured"
                            sling:resourceType="granite/ui/components/coral/foundation/form/checkbox"
                            text="Open in a new tab"
                            fieldDescription="Automatically enabled for PDF and document links"
                            name="./newTab"
                            value="{Boolean}true"
                            uncheckedValue="{Boolean}false"/>

                    </items>
                </column>
            </items>
        </columns>
    </items>
</content>