Building custom AEM widgets for the Classic UI touchscreen
Adobe Experience Manager Classic UI was built around ExtJS components, server-rendered dialogs, and a desktop-first authoring experience. Yet many teams eventually needed those interfaces to work on touchscreen laptops, tablets, kiosks, and hybrid devices. Creating a custom widget for that environment requires more than adding a larger button. The control must fit AEM’s component model, respond correctly to mouse and touch input, and remain usable inside the authoring shell.
The most reliable approach combines a clear widget contract, carefully scoped ExtJS code, and deliberate testing in the actual authoring workflows. A widget should solve a specific authoring problem, such as selecting a reusable content fragment, entering structured metadata, or managing a list of related pages.
The practices below are especially relevant to developers maintaining older CQ5 or AEM implementations. They also provide useful architectural context when a project is gradually moving from Classic UI to Touch UI.
Understand the Classic UI widget model
Classic UI widgets are generally based on ExtJS classes and are assembled through component definitions, dialogs, listeners, and configuration objects. A field may appear in a dialog, while a more advanced control can include a data store, custom renderer, validation logic, and event handlers. The widget should still behave like a native part of the AEM authoring environment.
Before writing code, identify the value that the component must store. A simple text value may be handled by a standard field with custom validation. A selection widget may need to persist a path, an identifier, or a serialized list. Defining that format first prevents the visual interface from becoming disconnected from repository content.
Classic UI also depends heavily on naming conventions. The field name, dialog structure, xtype, and server-side component logic must agree. A visually polished control that writes to the wrong property is still a failed authoring tool.
Design for touch without abandoning desktop input
A touchscreen does not automatically turn a Classic UI dialog into a mobile interface. ExtJS controls may rely on hover states, small hit areas, drag handles, or right-click behavior that is difficult to use with a finger. Custom controls should therefore support both pointer styles rather than assuming that touch replaces the mouse and keyboard.
Increase the effective hit area around buttons, checkboxes, and list items. Keep destructive actions visually separate from selection actions, and avoid interactions that require precise dragging. A tap should provide a clear state change, while keyboard focus and tab order should remain available for desktop authors and accessibility tools.
Touch support also depends on the browser and device combination. Some environments translate touch events into mouse events, while others expose separate touch events. Registering handlers without considering event duplication can cause an action to fire twice. Use the event model supported by the target AEM browser matrix, and test taps, long presses, scrolling, and focus changes independently.
Separate the widget from repository behavior
A custom AEM field should focus on presentation and interaction. Repository reads, writes, permissions, and business rules belong in well-defined services or servlet endpoints. Keeping those responsibilities separate makes the widget easier to test and reduces the risk of exposing internal repository logic in client-side code.
For example, a path picker may request permitted options from a JSON endpoint rather than embedding a large content tree in the dialog definition. The endpoint can apply access checks, filter invalid paths, and return only the data needed by the control. The widget then renders the response and writes the selected value into the configured field.
This separation is particularly important for older AEM systems, where client libraries can become difficult to trace. Place custom JavaScript in a dedicated client library category, keep dependencies explicit, and avoid modifying product overlays unless there is no supported extension point. A small, isolated implementation is easier to preserve during maintenance or migration.
Build the interaction around author tasks
A widget should reflect how authors make decisions, not how developers organize repository nodes. If an author needs to select several related pages, provide search, clear selection states, and a concise summary of chosen items. If an author enters a campaign code, validate the format immediately and explain the expected value beside the field.
Use progressive disclosure for complex controls. Show essential choices first, then reveal advanced filters or metadata only when needed. On a touchscreen, long forms create excessive scrolling and make context easy to lose. Group related controls and preserve selections when an overlay or picker closes.
The event agenda from the CIRCUIT conference provides useful context for the broader AEM engineering ecosystem, including architecture and implementation subjects covered by practitioners; developers can review the conference agenda when comparing widget work with wider platform concerns. A custom authoring control is ultimately part of an application architecture, not an isolated front-end experiment.
Validate data, states, and failure paths
Client-side validation improves the authoring experience, but it cannot be the only safeguard. Values must also be validated on the server before they are persisted or used by rendering logic. This protects content integrity when a request comes from a script, an outdated browser, or a user with unusual permissions.
A robust widget defines visible states for loading, empty results, invalid input, permission denial, network failure, and successful persistence. Avoid leaving authors with a blank panel after an asynchronous request fails. A short error message and a retry action are more useful than a generic JavaScript exception.
Pay attention to localization as well. Labels, validation messages, date formats, and search prompts should use AEM’s internationalization facilities rather than fixed English strings. Teams building multilingual authoring workflows can also examine guidance on AEM translation services to understand how language requirements affect broader content operations.
| Design area | Classic UI consideration | Touchscreen consideration | Practical implementation |
|---|---|---|---|
| Input control | ExtJS xtype and dialog configuration | Larger targets and visible focus | Extend a supported field or container |
| Selection | Repository path or property value | Clear tap feedback and easy deselection | Use a store with explicit selected state |
| Events | Click, change, select, and blur listeners | Avoid duplicate touch and mouse actions | Normalize events and test on target browsers |
| Validation | Client-side field rules | Immediate, readable feedback | Validate in the browser and on the server |
| Data loading | Servlet or service response | Loading and failure states | Return compact JSON with permission checks |
| Maintenance | Client library dependencies | Consistent behavior across devices | Isolate code and document supported AEM versions |
Test the widget inside real dialogs
A widget that works in a standalone browser page may fail inside a Classic UI dialog. Dialog rendering can alter dimensions, focus behavior, z-index, and event propagation. Test the control when opened from a component, reopened after saving, and used alongside other fields.
Include authoring scenarios rather than only technical unit tests. Create a new component, edit an existing component, cancel without saving, submit invalid data, and reopen the dialog after a successful save. Verify that values survive page refreshes and that the rendered component reflects the stored property.
Device testing should cover touch laptops, tablets, desktop browsers with emulation, and the actual AEM browser versions supported by the organization. Check portrait and landscape layouts, browser zoom, slow network conditions, and reduced screen height. If a picker opens a modal window, ensure it can be closed with touch and that the original dialog regains focus.
Plan for Classic UI maintenance and migration
Classic UI customizations can be valuable in a long-lived AEM installation, but they should be treated as compatibility-sensitive code. ExtJS APIs, overlays, client library loading order, and browser behavior may change across service packs. Record the AEM version, dependencies, dialog paths, stored property formats, and supported devices alongside the implementation.
Avoid creating a widget that has no migration path. Keep the underlying content model independent from the Classic UI presentation, and document how the same property would be edited in Touch UI or through another authoring interface. This makes future migration a data and interaction exercise rather than a repository reconstruction project.
A useful review should cover these practical checks:
- Define the stored property format before designing the visual control.
- Support keyboard, mouse, and touch input with consistent state changes.
- Keep repository access and permission logic outside the browser widget.
- Provide loading, empty, validation, and failure states for every asynchronous action.
- Test the complete authoring lifecycle across supported AEM versions and devices.
Custom Classic UI widgets work best when they are modest, predictable, and aligned with author behavior. Touch support should improve access to the existing task without introducing gestures that are difficult to discover or reproduce. Strong validation, isolated client-side code, and a stable content contract will matter more over time than visual complexity.
Use these principles to review an existing AEM dialog or shape a new authoring control. Then prototype the smallest useful interaction, test it in a real component workflow, and document the compatibility boundaries before releasing it to authors.