If you are an AEM developer reading this blog, there is a good chance you've heard of Edge Delivery Services (EDS). If so, then you have worked through the developer tutorial. And in a short time you got up and running with document-based authoring.
But as an AEM user, you may ask: "Where are all the web content management features that come with AEM?". Things like the MSM, workflows and translations. I was thinking the same thing, so I looked a little deeper. And found that you can bring that content into AEM where you get those WCM features. And do WYSIWYG authoring for EDS content by using the Universal Editor (UE) instead of the AEM Page Editor. I followed this tutorial and AEM GEM webinar.
By the time I got done, I became a little more interested in the UE. You see, with content delivery, you have a choice of EDS or headless.
If you chose EDS, you have a choice of content authoring. Document-based or WYSIWYG.
And if you chose the EDS WYSIWYG then you would be using the UE. But if you chose AEM headless instead of EDS, you could also use the UE.
So I set about ramping up on the UE. And I found that I had achieved three things. I set up a local Universal Editor Service. I used the UE to edit headless content. And I used it to edit EDS content. Hence the title: "Three Laps Around the Universal Editor".
First Lap: Setting up the Universal Editor Service
The UE gets hosted on the cloud. There is no way to run a local instance. But, the Universal Editor Service (UES) is the API layer that binds the editor to the backend system. It does it by using one of the available extensions in the registry to persist content.
To edit a local page via the UE, we need a local instance of the UES. The setup can be a little tricky because it must be running on HTTPS. To simplify things I built on my previous post about devcontainers. I put together a new devcontainer feature called aem-universal-editor-service.
I am following this tutorial. It goes over how to instrument aem-guides-wknd. Which is a traditional headful AEM application. The devcontainer feature takes care of the UES setup. So you only need to focus on the code updates. I created the following video. And explain the basic steps below.
First, create a new devcontainer.
Create a new folder and open it with VS Code
Run the Dev Containers: Add Dev Container Configuration Files... command
Use my devcontainer template: ghcr.io/juan-ayala/devcontainer-templates/aem
Don't re-open in a dev container yet...
Update the devcontainer.json file
Run the Dev Containers: Reopen in Container command.
Next, download the AEM SDK and Universal Editor Service. And start the author and UES.
Download the UES and AEM SDK zip files from Adobe's software distribution
Save them to the .devcontainer folder
Start AEM author: start-aem author & the Universal Editor Service: start-ues.
Open the UES and AEM local HTTPS apps, and accept the SSL certificate:
Finally, instrument the title in the teaser component.
Clone aem-guides-wknd
Update the customheaderlibs.html with the following markup
Update the teaser component by overlaying the teaser.html file. And adding the following AUE attributes
And the title.html file by adding the folowing AUE attributes
Run the Maven build to install aem-guides-wknd
Open a page in the Universal Editor and update a teaser. The UE may not work if you have turned on an ad blocker. So turn it off.
The aem-guides-wknd is a headful AEM site built on the core components. And editable via the Page Editor. Instrumenting it, or your own headful AEM apps makes no sense. But it is a good starting point if this is your first time around the UE and its service. Take your time and poke around. The original tutorial goes a little further with the properties rail.
Second Lap: Universal Editor and a Headless Site
The traditional headless model in AEM uses content fragments. And provides content to client apps via GraphQL endpoints. Such as a React SPA. So there is a separation between what the author edits and what they see on the page. The UE solves this problem by providing an in-context authoring experience.
So for this second lap, I took a look at instrumenting the aem-guides-wknd-graphql app. I started with the basic tutorial. And then moved to the instrumentation tutorial. You can compare the basic-tutorial branch & the basic-tutorial-instrumented-for-UE branch here.
I used the same devcontainer and UES feature as before. The only difference is that I had to update the ports in the code. I also had to install the WKND Teams content package. This is one of the pre-reqs in the tutorial. The config package is not needed. The UES feature installs those OSGi configurations. I created the following video. And explain the basic steps below.
Download and install the sample content. It contains the content fragments for the headless app.
Clone the aem-guides-wknd-graphql project and check out the basic-tutorial-instrumented-for-UE branch.
Update the code with the correct port numbers:
The .env.development file has a REACT_APP_HOST_URI variable
The App.js has the urn:adobe:aue:system:aemconnection and urn:adobe:aue:config:service URLs.
Run npm install and npm start.
Open the local https://localhost:3000 site in the UE.
Third Lap: Universal Editor and Edge Delivery Services
Up until this point, I had been running apps and content on my local machine. With the only remote piece being the UE. This proved to be a challenge for EDS.
If you are developing the application code (JavaScript/CSS) you will be using @adobe/aem-cli. This local dev server will use a proxy to fetch the content from EDS based on the git repo name/owner/branch. This isn't a problem if you forked the project. And created the site content with the EDS with AEM authoring template. Currently on version 0.0.16.
You can also use the EDS with AEM authoring template to create the site content on your local machine. And you can use the UE to edit the content. But again, it depends on the repo name/owner/branch on GitHub. If you look at the rendered page, you will find the JavaScript/CSS gets fetched through a servlet proxy from EDS.
So you will never be able to run content and code at the same time on your local machine. And it makes sense because publishing on EDS is not the same as the traditional publish tier on AEM. The client side application is working with semantic markup. Processed by EDS and placed on the edge. And not rendered by the core/franklin/components/* components. Those are for authoring only and should not get customized. The markup they render is a stable contract. It gets consumed by helix-html2md when publishing to Edge Delivery Services. And by aem.js when loading a page in the Universal Editor.
In the end, the customization will happen on the front-end JavaScript/CSS. And the AEM content should use the out-of-the-box core/franklin/components/* components. To create the pages with the sections and blocks that gets consumed by EDS.
I created the following video that shows how to set up the EDS content on your local machine. So that you can go over the content modeling for EDS. I'll explain the steps below.
Create a GitHub repo by using adobe-rnd/aem-boilerplate-xwalk as a template.
Install the AEM Code Sync GitHub App and give it access to your new repo. This app will publish your code to EDS.
Install the site template on your local instance. And create a new site configured to use your GitHub repo. Change this later by Tools -> Cloud Services -> Edge Delivery Services Configuration.
If you try to open a page in the UE, you will get an error. The page did not get instrumented with the correct meta tags. urn:adobe:aue:system:aemconnection and urn:adobe:aue:config:service are set via OSGi configs. Which in turn are using environment variables. So add two new environment variables to the remoteEnv section of devcontainer.json.
After you rebuild the container, start the AEM author & UES back up again.
The page is now instrumented. And can get edited by the UE at https://localhost:44302/content/my-eds-site/index.html
Conclusion
If you're jumping on board with Edge Delivery Services, you have two options for authoring. Document-based or WYSIWYG. At first, as an AEM old-timer, I struggled to see the value in the document-based feature. But as I have come to find, some clients, especially those new to AEM, are open to it. Adobe’s guidance on this: Start simple, and migrate document content to AEM when needed.
If you’re curious about the Universal Editor, I encourage you to try out the three laps I’ve outlined. And if you want to dive deeper into developing AEM within a dev container, check out my previous post. Developing AEM Inside a Dev Container.