Creating Custom Granite UI Widgets for AEM Touch Dialogs
Adobe Experience Manager touch UI dialogs give content authors a structured way to configure components, but the standard Granite UI field set cannot cover every editorial or technical requirement. Teams often need richer selectors, conditional controls, remote data pickers, visual previews, or inputs that understand a project’s content model.
Creating Custom Granite UI Widgets for AEM Touch Dialogs involves more than adding a JavaScript file to a component. A reliable widget must fit Granite’s rendering model, communicate with Sling endpoints safely, support authoring workflows, and remain maintainable when AEM is upgraded.
This matters to Australian organisations operating across Sydney, Melbourne, Brisbane, Perth, and regional offices. Authors may work across different time zones, publish regulated content, and manage large product or service catalogues. A carefully designed dialog reduces training time and prevents incorrect values from reaching production.
The best implementations treat the widget as a small product within the AEM platform. Its authoring experience, server-side contract, accessibility, validation, and deployment process should be considered together rather than assembled as isolated code fragments.
Define The Authoring Requirement First
Start by describing the author’s task in plain language. A custom field may appear to require a dropdown, yet the real need could be searching thousands of products, filtering options by market, selecting multiple references, or displaying a helpful preview. Choosing the widget type before understanding that task often produces a slow or confusing dialog.
Granite UI provides foundations such as text fields, path fields, select fields, multifields, and Coral UI components. Reuse these wherever possible. A custom widget should fill a genuine gap, such as a searchable taxonomy selector or a field that retrieves approved campaign data from an internal service.
Consider the author’s permissions and publishing responsibilities early. A widget that exposes every repository path or API result can create governance problems. For an Australian bank, healthcare provider, or government service, the field may need to restrict values by business unit, accessibility status, region, or approval state.
Understand Granite UI And Coral UI
A touch dialog is assembled from Granite UI resources, usually through nodes under the component’s cq:dialog definition. The field’s sling:resourceType, name, value type, validation rules, and client library categories determine how it renders and behaves. A custom control still needs to honour those conventions.
Coral UI supplies the visual components and interaction patterns used by modern AEM authoring interfaces. Rather than replacing Coral markup with a completely independent design, extend its patterns where practical. This helps the widget respond correctly to dialog resizing, fullscreen mode, keyboard interaction, and AEM’s authoring overlays.
The data contract deserves equal attention. Decide whether the value is stored as a string, array, child node, JSON object, or reference. Keep persisted values stable and human-readable when possible. If an implementation stores transient labels instead of durable identifiers, a renamed item or changed API response can leave existing content difficult to edit.
Build The Widget Around Clear Boundaries
A useful custom Granite control generally has three layers: dialog configuration, client-side behaviour, and an optional server-side resource or servlet. The dialog configuration declares the field. The client library initialises Coral elements, handles events, and synchronises the selected value. The server side supplies controlled data or performs validation.
Use data attributes and namespaced events to keep the client code predictable. Initialise the control when the dialog becomes available, including when AEM loads it dynamically. Clean up listeners when necessary, and avoid assuming that a component exists only once on the page. Authors may open several nested dialogs during a single editing session.
If the widget calls an endpoint, return a deliberately small response. Include identifiers, display labels, and only the metadata needed for filtering or previewing. Apply permission checks on the server, encode output, and protect endpoints from unbounded queries. Client-side restrictions are useful for convenience, never as the security boundary.
A field that integrates an external recommendation or classification service can follow the same principle: isolate the service adapter from the dialog control. For a useful comparison of this separation, see this recommendation engine example, where application behaviour depends on a distinct service layer rather than UI code containing every integration detail.
Handle Values, Validation And Accessibility
Validation should happen as close as possible to the authoring action. Add Granite validation for required values, accepted formats, and business rules that can be checked immediately. Server-side validation must remain authoritative because content can be imported, modified through APIs, or written by automation.
Error messages should explain how to fix the problem. “Invalid selection” is weaker than “Choose an approved campaign from the current market.” Preserve the author’s input when validation fails, and ensure asynchronous errors do not silently reset a field. Slow responses should show a loading state and provide a clear retry path.
Accessibility is essential for Australian organisations subject to the Disability Discrimination Act and for teams publishing to public services. Provide labels, descriptions, focus management, keyboard operation, and meaningful status announcements. A visual colour marker cannot be the sole indication of state, and a mouse-only autocomplete will exclude some authors.
| Requirement | Recommended approach | Common failure |
|---|---|---|
| Stored value | Use stable IDs or paths with a documented format | Saving display labels that later change |
| Remote results | Paginate, filter, and limit responses server-side | Loading an entire catalogue into the browser |
| Validation | Combine Granite rules with server checks | Trusting only client-side JavaScript |
| Accessibility | Support labels, focus, keyboard use, and status text | Relying on colour or hover behaviour |
| Upgrade safety | Use supported Coral and Granite extension points | Replacing large sections of AEM internals |
Connect Widgets To Existing AEM Systems
Many custom fields exist because AEM sits beside older commerce, product information, customer, or campaign systems. A widget can provide a modern authoring experience while leaving those systems in place. The integration should define ownership clearly: AEM may store a reference, while the source platform remains responsible for the underlying record.
For legacy applications, an intermediary service can translate authentication, payload formats, and identifiers. This is often safer than exposing a decades-old endpoint directly to browser code. The legacy application bridge approach is particularly relevant when an Australian enterprise has acquired systems over time and cannot replace them during a single delivery cycle.
Design for latency and partial failure. Authors in Perth accessing services hosted in Sydney, or teams working through corporate proxies, may experience different response times. Cache suitable reference data, debounce searches, set timeouts, and distinguish “no results” from “service unavailable”. Never make a dialog unusable because an optional enrichment service is temporarily offline.
Keep environment configuration outside the widget source. Development, staging, and production may use separate endpoints, client credentials, or content roots. OSGi configuration and secure secret handling provide a more dependable path than hard-coded URLs in a client library.
Test, Package And Maintain The Control
Test the widget in the actual AEM authoring shell, not only in an isolated browser page. Verify creation, editing, copying, inheritance, cancel actions, validation failures, multifield use, and reopening existing content. Test with different author permissions and with content that contains old or incomplete values.
Automated browser tests can cover keyboard navigation, search behaviour, error states, and persistence. Unit tests should focus on value conversion, response handling, and event logic. On the server, test permission checks, malformed requests, pagination, and upstream failures. Include upgrade testing when moving between AEM service packs or Cloud Service releases.
Package the widget in a predictable client library and content structure. Document the resource type, stored value format, required endpoint permissions, configuration properties, and supported AEM versions. Avoid depending on private DOM selectors or undocumented internal APIs, as those are common sources of upgrade regressions.
A useful deployment workflow separates code, configuration, and content migration. Use code review for dialog definitions and security-sensitive servlet changes, then promote through environments with repeatable pipelines. If a control changes its stored format, provide a migration strategy and retain backward compatibility during the transition.
For teams maintaining both old and new authoring experiences, compare the implementation assumptions carefully. A discussion of Classic UI widget patterns can provide historical context, but Classic UI techniques should not be copied directly into a touch UI project without checking Coral UI and current Granite conventions.
A well-made widget gives authors immediate feedback, stores dependable values, and fails safely when integrations are unavailable. It also respects the practical conditions of the local market: distributed Australian teams, accessibility obligations, large enterprise repositories, and publishing schedules that may span AEST, ACST, and AWST.
Treat the control as a supported AEM component rather than a one-off dialog trick. Define its contract, secure its data source, test its authoring behaviour, and document its upgrade path. Then build a small prototype with real author roles and representative content before expanding it across the platform.