Universal Editor Routing and Local Development — What Matters for EDS Projects

Content Objective

This chapter covers:

• When Universal Editor is useful in an EDS or AEM Cloud project
• What is worth reusing from a Touch UI to Universal Editor migration guide
• How to route Edit actions away from Touch UI and into Universal Editor
• What page instrumentation Universal Editor needs to work correctly
• How to run a local Universal Editor service for development
• Which parts of the guide are not useful for pure Document Authoring projects

This chapter is not about replacing every EDS pattern with Universal Editor patterns. It is about identifying the pieces that are actually useful when your EDS work touches AEM Cloud Service and xwalk-style authoring.

If your project is pure Document Authoring, most of this chapter is optional. If your project uses AEM content, Universal Editor, or a hybrid delivery model, this chapter becomes practical immediately.

Why This Guide Matters

The source guide describes a real AEM Cloud Service setup where Edit in Sites opens Universal Editor instead of Touch UI. That is valuable because it solves a real problem for teams that still rely on classic AEM authoring entry points but want a modern editing experience.

For EDS work, the useful idea is not "migrate Touch UI for the sake of migration." The useful idea is:

Use Universal Editor when authors need inline editing, page context, and AEM-backed persistence.

That makes it relevant in three cases:

1. You are building an xwalk project that needs properties panels and in-context editing.
2. You are connecting EDS-style delivery to AEM Cloud content.
3. You want a cleaner authoring workflow than Touch UI pages and dialogs.

Useful Parts

These are the parts worth keeping for EDS and xwalk work:

• Route Edit actions from Sites to Universal Editor instead of /editor.html.
• Use data-aue-* attributes to connect rendered HTML to authored fields.
• Keep the component definition JSON and model JSON in sync with your block or component structure.
• Run a local Universal Editor service when developing against localhost.
• Use HTTPS everywhere during local development.
• Use explicit authentication headers when AEM runs locally and IMS is not available.

These are the parts that are mostly implementation details, not strategy:

• The exact internal feature toggle name.
• The exact local login workflow used in the browser toolbar.
• The specific OSGi PID names, unless you are implementing the AEM Cloud route yourself.

What To Ignore In A Pure EDS Project

If your site is authored through Document Authoring and delivered as standard EDS blocks, you do not need most of the AEM Cloud Universal Editor plumbing.

You can ignore:

• The AEM Sites Edit button routing change.
• The local UE service and its auth header setup.
• OSGi configs that only matter inside the AEM author instance.
• Touch UI replacement work.

You still may want to borrow one idea from the guide:

• The discipline of annotating content clearly so authoring actions map cleanly to content fields.

The EDS-Friendly Interpretation

The practical translation for EDS is simple.

If you are using Universal Editor in an EDS-connected project, the page must expose enough structure for the editor to understand what is editable.

That means:

1. The root element must identify the resource.
2. Editable child elements must identify the property they represent.
3. The component model must define the fields the editor can show.
4. The local dev stack must let the editor reach AEM over HTTPS.

If any one of those is missing, the authoring experience becomes unreliable.

Minimal Universal Editor Checklist

Use this checklist when you need Universal Editor support in an EDS-related project.

1. Decide whether the project actually needs UE

Use Universal Editor when:

• Authors need to edit on the rendered page.
• The content lives in AEM JCR.
• The project already depends on AEM Cloud Service.
• You need properties panels and inline authoring.

Do not force Universal Editor into a project just because it sounds modern. Use the simplest authoring model that fits the content workflow.

2. Add clear page instrumentation

Your rendered HTML needs to tell UE what the element is and where it belongs.

Typical pattern:

<div data-aue-resource="urn:aem:/content/site/en/page/jcr:content/root/component"
     data-aue-type="component"
     data-aue-model="teaser"
     data-aue-label="Teaser">
  <h1 data-aue-prop="title"
      data-aue-type="richtext"
      data-aue-label="Title">
    Welcome
  </h1>
</div>

The important point is not the syntax itself. It is the mapping:

• data-aue-resource points to the content node.
• data-aue-model points to the model definition.
• data-aue-prop points to the editable field.
• data-aue-type tells UE how to edit the value.

3. Keep model JSON aligned with the rendered DOM

The properties panel only works when the model and the annotations describe the same fields.

Example:

[
  {
    "id": "teaser",
    "fields": [
      { "component": "text", "name": "title", "label": "Title", "valueType": "string" },
      { "component": "richtext", "name": "description", "label": "Description", "valueType": "string" }
    ]
  }
]

If the DOM says data-aue-prop="title" but the model calls the field headline, authors will get a broken editing experience.

4. Use local HTTPS development

UE local development usually needs three pieces to work together:

• AEM running on HTTPS.
• A local UE service.
• Browser trust for the local certificates.

If any of those are missing, your editor session will fail in ways that look like auth, CORS, or iframe problems.

5. Add authentication headers for localhost

For local AEM development, the editor service often needs explicit credentials.

The main thing to remember is this:

• Local UE development is not the same as cloud-authenticated production use.
• If requests to /details, /configuration, or /patch fail with 401, the auth header layer is usually the problem.

A Practical Setup Sequence

If you are implementing UE in an EDS-style project, follow this order:

1. Confirm whether the content really needs AEM-backed authoring.
2. Make the rendered page expose stable data-aue-* annotations.
3. Define the component model and field names first.
4. Wire the editor routing so the author lands in Universal Editor.
5. Bring up the local UE service and verify HTTPS connectivity.
6. Test one component end to end before scaling to the rest of the site.

Do not start by instrumenting everything. Start with one page, one component, and one editable field.

Common Failure Modes

These are the failures worth watching for.

Edit still opens Touch UI

Usually means one of these is wrong:

• The routing config did not take effect.
• The page is missing the Universal Editor-specific mode mapping.
• The browser session is still falling back to classic authoring.

Properties panel opens but is empty

Usually means:

• The data-aue-model value does not match the model JSON.
• The data-aue-prop name does not match the field name.
• The element was not annotated at the right DOM level.

Local editor loads but requests fail

Usually means:

• HTTPS is not trusted.
• The local UE service cannot reach AEM.
• The auth headers are missing.

The editor works for one field but not another

Usually means one field is correctly modeled and the other is only partially annotated.

What To Reuse In Your EDS Series

If you want this chapter to support the rest of the EDS series, the next additions are:

• A short decision rule for when to choose DA vs UE.
• A clear explanation of how annotations map rendered HTML back to authored content.
• A checklist for local development when the authoring stack depends on localhost.

That makes this chapter a bridge between the conceptual DA vs UE discussion and the practical implementation chapters.

Final Instruction

Use Universal Editor when the project needs AEM-backed in-context editing. Use Document Authoring when the project needs simpler, document-style content management.

That is the cleanest rule for EDS work:

Choose the authoring system that matches the content workflow, not the one that looks more advanced.

When you keep that rule in mind, you avoid a lot of unnecessary complexity.

Next Steps

The next chapter, EDS Migration Mental Model, zooms out from routing details to the question that should come before any migration: what authoring and delivery model the content actually needs, rather than how to port AEM one-to-one.