CIRCUIT

Customising AEM dialog interfaces with Coral UI

Adobe Experience Manager dialogs sit between content authors and every page they ship, so for Australian teams running editorial workflows out of Sydney, Melbourne or Brisbane, getting these authoring screens right is rarely cosmetic. Coral UI, bundled with AEM since 6.0, gives developers a structured way to build dialogs that feel native while still allowing meaningful change. Many of the patterns now considered standard were first shared at gatherings such as the CIRCUIT conference in Chicago, where systems engineers compare notes on real production pain points.

The shift from classic ExtJS widgets to Coral 3 marked a quiet revolution. Coral sits on the Granite UI foundation, leans on web components where it can, and aligns with W3C custom element semantics, which suits teams that also ship React or Angular front-ends. For Australian organisations operating under consumer law and accessibility expectations, the predictable semantics of Coral reduce the amount of bespoke ARIA code that has to be hand-written for each new field type.

This piece walks through the practical decisions a developer faces when tailoring dialogs, from choosing widget variants to writing client libraries that survive future upgrades. Readers preparing for the next round of conference talks can browse the conference agenda to find sessions touching on these themes directly.

Australian English, the legislation that shapes accessibility work, and the realities of multi-time-zone delivery are woven in throughout, because dialog design rarely exists in a vacuum.

Coral UI foundations for author interfaces

Coral UI ships as a set of client libraries inside AEM and can be requested from any component using the granite.ui.coral.foundation and granite.ui.coral.components categories. Underneath, it relies on jQuery 2.x for legacy support and on native custom elements for newer widgets such as coral-textfield, coral-multifield and coral-select. Understanding this layering matters because decisions about bundle size depend on whether the target deployment tolerates a heavier payload.

The Granite UI resource type hierarchy is the map every dialog author must internalise. A field declared with sling:resourceType="granite/ui/components/coral/foundation/form/textfield" renders with full Coral markup, validation hooks and integration with the Foundation Form framework. Deviating tends to break Sling POST Servlet handling and disables out-of-the-box error states. For Australian teams delivering into healthcare or financial services, those built-in states often decide whether an accessibility audit passes or becomes a remediation cycle.

Granite 3 introduces data-foundation attributes that allow configuration through markup rather than script, closer to how modern designers expect to author. Choosing between Granite 2 and 3 usually comes down to whether the team is maintaining older dialogs or building new ones.

Mapping dialog fields to Coral widgets

Each common authoring need has a Coral equivalent, and selecting the right one early avoids retrofitting later. Text inputs become coral-textfield, which supports placeholder text, validation patterns and a disabled state that respects the surrounding form context. Pathfields remain one of the trickiest widgets because they need to communicate with the Sling repository resolver, and getting the predicate string right can save hours of debugging for content authors in Adelaide or Perth who work with deeply nested DAM structures.

Multifields are where most teams slip. The coral-multifield widget allows nested templates, useful for components like configurable card lists, but the JSON serialisation must round-trip cleanly through Sling. Australian projects that export structured content to mobile apps, common in retail and tourism, often need additional client-side validation to guarantee the payload conforms to a JSON schema.

Date pickers, colour pickers and switch toggles each carry their own configuration grammar. A coral-datepicker requires both an ISO format string and a display format, and forgetting the latter produces a field that stores the right value but confuses every author who tries to use it. Switches must be paired with a hidden input so the form serialises a boolean rather than the literal string on.

Visual styling without breaking conventions

Customising the visual layer starts with the client library system. Dialogs load their CSS through categories declared on the component, and the safest place to override Coral styles is in a cq:ClientLibraryFolder scoped to the project with a dependency on granite.ui.coral.foundation. Specificity battles are the most common reason dialog customisation regressions appear: a Coral style declared with .coral-Textfield is hard to override, while the same style written under a project-specific namespace can be adjusted without fighting the cascade.

Less is usually more. Most Australian teams lean on a small design token sheet covering spacing scale, three type sizes and two brand colours, then translate those tokens into Coral variable overrides rather than rewriting components. This keeps upgrades clean: when Adobe ships a Coral patch, project styles survive because they target hooks rather than full selectors.

There is a legitimate case for stronger visual change in sectors such as tourism boards in Queensland or education providers in Victoria, where brand identity is tightly guarded. A hybrid approach works well: keep Coral for structure and behaviour, then layer a design-system skin over the top using BEM-style class names added to the dialog container.

Accessibility under Australian standards

Australian accessibility expectations are anchored in the Disability Discrimination Act 1992 and reinforced through Australian Human Rights Commission guidance, which references WCAG 2.1 Level AA as the practical benchmark. Coral dialogs, when used as designed, clear most of the bar: labels are associated programmatically, focus is trapped inside modal overlays, and error messages are announced through ARIA live regions. The risk appears when customisation introduces markup that breaks these assumptions.

Teams should test every custom field with keyboard navigation alone before shipping. A coral-multifield that adds an "Add item" button needs that button to be reachable by tab order, and the resulting items need to expose a focusable remove control. Skipping this step is the kind of defect that surfaces in an internal audit at an Adelaide government portal and turns into a remediation project measured in weeks. Dialogs handling sensitive content should pair with a broader security review; the security mitigations guide walks through input validation patterns that complement Coral's client-side checks.

Australian projects that touch personal information should also remember the Privacy Act 1988 and the Notifiable Data Breaches scheme. A dialog field that asks for a Medicare number needs to be tagged appropriately in the schema, and any custom validation must not echo the value back into error messages where it could be cached by browser autocomplete.

Reusable field configurations

Large AEM implementations rarely repeat themselves: a single hero component might appear on a homepage, a campaign landing page and an email template, each with slightly different authoring needs. Building a small library of reusable field configurations pays off within the first sprint, particularly for distributed teams in Sydney and Perth who cannot afford to argue over naming conventions across every pull request.

A pragmatic starting point looks like this:

  • A shared _config folder containing cq:dialog snippets for common field types
  • Sightly templates that compose those snippets via data-sly-resource inclusions
  • A JavaScript use object that exposes a typed API for reading complex multifield data
  • A simple documentation page generated from the snippets for non-technical authors

The list deliberately stops short of a full design system, because over-investing in abstraction before the second or third use case usually produces a framework nobody wants to touch.

Testing dialog behaviour across browser conditions

Australian end-user analytics consistently show a long tail of older browsers in the government and education sectors, particularly in regional New South Wales and Tasmania where device refresh cycles run longer. Coral dialogs behave predictably in evergreen Chromium, Firefox and Safari, but Internet Explorer 11 support is still on the menu for some institutions, which means accepting the limitations of Coral's older polyfills.

A reasonable test matrix for dialog customisation looks like:

  • Chromium on Windows and macOS for the primary authoring audience
  • Safari on iPadOS for editorial teams that prefer tablets
  • Firefox on Linux for systems engineers running local author instances
  • Internet Explorer 11 only when contractually required, with documented gaps

Automated tooling catches regressions early, but the most useful test is still a five-minute pass with a content author watching over a developer's shoulder. They spot the field that loads off-screen, the tab order that misses a button, and the validation message that disappears too fast, all without writing a single line of test code.

Operational habits for teams spanning time zones

Dialog work tends to happen late in the project, when editorial teams have had time to actually use the system, which means bug reports arrive during Australian business hours but often originate from developers in completely different parts of the world. Establishing a clear handover window, somewhere between 7 am and 9 am Australian Eastern Standard Time, keeps reviews short and reduces the risk of a Coral upgrade being merged just before someone's morning standup.

Version control discipline matters more here than in many other areas. Coral's client libraries are cached aggressively, both on the author instance and on the dispatcher, so a CSS change that looks correct in development can vanish behind a CDN cache in production. Tagged commits, release notes that call out which cq:ClientLibraryFolder categories changed, and a quick smoke test on a freshly cleared dispatcher all belong in the standard routine.

The most valuable habit is to keep a record of design rationale. A short note in the pull request explaining why a particular Coral override exists prevents the next developer, possibly someone in another time zone picking up the work months later, from reverting it back to the default. Over time, those notes become a small body of institutional knowledge more useful than any framework upgrade.

Customising AEM dialogs with Coral UI rewards teams who treat it as a craft rather than a checkbox, where consistency matters more than novelty. Built-in widgets cover the majority of authoring needs, and the time saved by not reinventing the foundation is best spent on accessibility, testing and documentation. Anyone keen to deepen their practice should grab the conference companion app to keep up with recordings, slides and speaker follow-ups from the most recent CIRCUIT gatherings, then put one of the patterns above to work on a real component.