Universal Editor Overview for AEM Developers developer-overview

If you are an AEM developer interested in how the Universal Editor works and how to use it in your project, this document gives you an end-to-end introduction by leading you through instrumenting the WKND project to work with the Universal Editor.

Purpose purpose

This document serves as a developer’s introduction to both how the Universal Editor functions and how to instrument your application to work with it.

It does this by taking a standard example that most AEM developer’s are familiar with, the Core Components and the WKND site, and instruments a few example components to be editable using the Universal editor.

Prerequisites prerequisites

To follow along with this overview, you need the following available.

Beyond general familiarity with web development, this document assumes basic familiarity with AEM development. If you are not experienced with AEM development, consider reviewing the WKND tutorial before continuing.

Start AEM and Sign In to the Universal Editor sign-in

If you haven’t already, you must have your local AEM development instance running with WKND installed and HTTPS enabled as detailed in the prerequisites. This overview assumes that your instance is running at https://localhost:8443.

Universal Editor Attempts to Load the Content sameorigin

The Universal Editor loads content to be edited in a frame. AEM’s default settings for X-Frame options prevent this, which can clearly be seen in the browser as an error and detailed in the console output when trying to load your local copy of WKND.

The X-Frame option sameorigin prevents rendering AEM pages within a frame. You must remove this header to allow the pages to be loaded in the Universal Editor.

Now if you reload the Universal Editor, you see that your AEM page loads.

Handling Same Site Cookies samesite-cookies

When the Universal Editor loads your page, it loads to the AEM sign-in page to ensure that you are authenticated to make changes.

However, you can not successfully sign in. Showing the browser console, you can see that the browser has blocked input on the frame

The login token cookie is sent to AEM as a third-party domain. Therefore the same-site cookies must be allowed in AEM.

Now if you reload the Universal Editor, you can successfully sign in to AEM and your target page loads.

Universal Editor Connects to the Remote Frame ue-connect-remote-frame

With the page loaded in the Universal Editor and you signed into AEM, the Universal Editor tries to connect to the remote frame. This is done via a JavaScript library that must be loaded in the remote frame. If the JavaScript library is not present, the page ultimately creates a timeout error in the console.

You must add the necessary JavaScript library to the page component of the WKND app.

The page now loads with the proper JavaScript library to allow the Universal Editor to connect to your page and the timeout error no longer appears in the console.

Defining a Connection to Persist Changes connection

The WKND page now loads successfully in the Universal Editor and the JavaScript library loads to connect the editor to your app.

However you likely noticed that you can not interact with the page in the Universal Editor. The Universal Editor can not actually edit your page. For the Universal Editor to be able to edit your content, you need to define a connection so it knows where to write the content. For local development, you need to write back to your local AEM development instance at https://localhost:8443.

Now the Universal Editor can not only load your content successfully from your local AEM development instance, but also knows where to persist any changes you make using your local Universal Editor service. This is the first step in instrumenting your app to be editable with the Universal Editor.

Instrumenting Components instrumenting-components

However, you probably notice that you still can do little with the Universal Editor. If you attempt to click the teaser at the top of the WKND page in the Universal Editor, you can not actually select it (or anything else on the page).

Your components must also be instrumented to be editable with the Universal Editor. To do this, you must edit the teaser component. Therefore you need to overlay the Core Components since the Core Components are under /libs, which is immutable.

Instrument Subcomponents of the Teaser subcomponents

You can now select the teaser, but still not edit it. This is because the teaser is a composite of different components such as the image and title component. You must instrument these sub-components in order to edit them.

You can now edit the title of the teaser component!

What does it all mean? what-does-it-mean

Now that you can edit the title of the teaser, let’s take a moment to review what you have accomplished and how.

You have identified the teaser component to the Universal Editor by instrumenting it.

You have also instrumented the title component within the teaser component.

Defining Authentication Headers auth-header

Now you can edit the title of the teaser in-line and changes are persisted in the browser.

However, if you reload the browser, the previous title is reloaded. This is because although the Universal Editor knows how to connect to your AEM instance, it editor can’t yet authenticate to your AEM instance to write back changes to the JCR.

If you show the network tab of the browser developer tools and search for update, you can see that it is encountering a 401 error when you try to edit the title.

When using the Universal Editor to edit your production AEM content, the Universal Editor uses the same IMS token that you used to log on to the editor to authenticate to AEM to facilitate writing back to the JCR.

When you are developing locally, you can’t use the AEM identity provider since IMS tokens are only passed to Adobe-owned domains. You need to manually provide a way to authenticate by explicitly setting an authentication header.

There are no longer any errors reported in the browser console and the changes are persisted back to your local AEM development instance.

If you investigate the traffic in the browser developer tools and look for the update events, you can see the detail of the update.

{
  "connections": [
    {
      "name": "aem",
      "protocol": "aem",
      "uri": "https://localhost:8443"
    }
  ],
  "target": {
    "resource": "urn:aem:/content/wknd/language-masters/en/jcr:content/root/container/carousel/item_1571954853062",
    "type": "text",
    "prop": "jcr:title"
  },
  "value": "Tiny Toon Adventures"
}

You can see the change persisted in the JCR.

Instrumenting the App for the Properties Rail properties-rail

You now have an app that is instrumented to be editable using the Universal Editor!

Editing is currently limited to in-line editing of the teaser’s title. However, there are cases when editing in-place is not sufficient. Text such as the title of the teaser can be edited where it is with keyboard input. However more complicated items need to be able to display and allow editing of structured data separate from how it is rendered in the browser. This is what the properties rail is for.

To update your app to use the properties rail for editing, return to the header file of the page component of your app. This is where you already established the connections to your local AEM development instance and your local Universal Editor service. Here you must define the components that are editable in the app and their data models.

What does it all mean? what-does-it-mean-2

To be editable using the properties rail, the components must be assigned to groups, so each definition begins as a list of groups containing the components.

Each group then has an array of components.

Each component then has a plugin definition that defines how the component is mapped to AEM.

Each component then must be mapped to a model to define the individual editable fields.

Instrumenting the Component for the Properties Rail properties-rail-component

You also need to define at the component level, which model the component should use.

Now you are ready to test out the properties rail instrumented for your component.

You can now edit the title of the teaser either in-line as you had before, or in the properties rail. In both cases, the changes are persisted back to your local AEM development instance.

Add Additional Fields to the Properties Rail add-fields

Using the basic structure of the data model for the component that you already implemented, you can add additional fields, following the same model.

For example, you can add a field to adjust the styling of the component.

Any field in the JCR for the component can be exposed in the Universal Editor in this way.

Summary summary

Congratulations! Now you can instrument your own AEM apps to work with the Universal Editor.

When you start instrumenting your own app, keep in mind the basic steps you performed in this example.

You can follow these same steps to instrument your own app for use with the Universal Editor. Any properties in the JCR can be exposed to the Universal Editor.

Additional Resources additional-resources

Have a look at the following documents for more information and details on the Universal Editor features.