Setup Universal Editor

Universal Editor is supported on Author Bus via Adobe's Early Access Technology program. You can store your content in Author Bus (the repository that powers da.live) while editing the content using Universal Editor.

Requirements

  1. You have a "DX Handle" - ie. @nameofmycompany (found in the URL on experience.adobe.com)

  2. Your IMS Org / DX Handle has Universal Editor enabled (this currently requieres AEM Sites credits)

  3. You have a site on da.live.

  4. You have AB-compatible UE instrumentation

    1. component-models.json
    2. component-definitions.json
    3. component-filters.json
    4. Any code necessary to make an intuitive authoring experience (see ue folder in da-block-collection)

  5. Currently we support Chrome and Safari browsers only.

For 4. see details below.

Hint: da-block-collection already comes with all UE instrumentation baked in. If you want to get a sense of how much effort it is to add to your own project, inspect the ue folder of this repo.

Setup

Add the editor path to your DA org data config https://da.live/config#/{{name-of-org}}/ (available in the breadcrumb on the org):

key value 
editor.path

/org/site/path/to/content=https://experience.adobe.com/#/@adobecomdx/aem/editor/canvas/main--da-block-collection--aemsites.ue.da.live

Three callouts:

  1. If the browsing path is a descendant of config path, users will automatically be taken to Universal Editor. If the user is in the org, they will be presented with an option to open in Universal Editor from a document.
  2. Note the @adobecomdx handle. You will need to supply your own.
  3. Note the final hostname after /canvas/. You will need to update this to match your project's subdomain + ue.da.live.

Enable your project

As noted above starting with da-block-collection which already comes with all UE instrumentation baked in is a good idea.

Additional UE instrumentation might be needed for you custom blocks. It is recommended to do this in a branch of your project. This is how you can easily add them:

  1. Add the block for a (test) page. This can be done with the document editor. If the block supports different format or block options it is recommended to add each version.
  2. Open the page in Universal Editor The page should full render in UE already.
  3. Navigate to the content tree in UE and select the block The overall site structure is automatically detected by UE. This includes all the block. Blocks in your project without UE instrumentation will be shown as " (no definition)".
  1. Open developer console and change to the network tab
  2. Open the block properties

The properties panel will be empty as the block has no instrumentation yet.

  1. Inspect the /details call via the network tab

Inspect the call response via the "preview" tab, it should look similar to:

You we get a detailed list of the parsed block content with CSS selectors. These CSS selectors are needed for the next step to create the component definition and component model of your block.

  1. Create the block instrumentation

To register a new block for UE, 3 configurations are required for the corresponding JSON files.

Within you project in the block folder next to the block CSS & JavaScript files create an .json file with /ue/models/blocks. The JSON file has 3 arrays: * definitions: enables the block for the Universal Editor. The id corresponds to block name. Each block has a da plugin which defines the initial content structure used by the block when added to the page. * models: defines all the fields of the UE properties panel, including field type, behavior and validation. Fields are linked to the content of the block via one CSS selector of the previous step * filters: is only used for container blocks (like Cards or Accordion block), otherwise an empty array.

Finally, the block must be made “known”. This means it must be added to the section filter list in /ue/models/section.json.

For examples see the da-block-collection and review the UE documentation on the available field types and options.

  1. Push the branch
  2. Change the UE URL to you branch and test Open UE for your DA site and change the URL to the created branch.

Using block options

Some blocks may support one or more block options. Instead of authors writing the block class names in the block header, we have a nice way to achieve this with the Universal Editor.

You can either provide your authors with a block options field. This is usually a single or multiple select component, depending on the block options supported by the block. Of course, a simple text field will also work, but this is rather inconvenient for the author. Unlike content components, block options are not defined by a CSS selected as a name in the component models. The fields are simply named classes.

You can also configure multiple block options fields to support more complex combinations. These fields must start with classes_ and will be combined into a class list during rendering.

Building the component definition files

The tree component definition files component-models.json , component-definitions.json , component-filters.json controlling the UE instrumentation must be stored in the project root folder. You can either edit these files directly — which is not really recommended, as they can grow quickly if you have more blocks — or use the simple bundling tool that we provide.

Instead of maintaining three massive JSON files with all our component configurations, we keep them organized in separate files per component. We recommend following the da-block-collection approach and keeping the files organised in the ue/models folder. The file structure looks like the following:

ue/models/
├── blocks/
│   ├── accordion.json     # Contains definitions, models, and filters for accordion
│   ├── cards.json         # Contains definitions, models, and filters for cards
│   └── ...
├── component-models.json      # Template that references all block models
├── component-definition.json  # Template that references all block definitions
└── component-filters.json     # Template that references all block filters

This repo also contains a build:json script build pipeline that consolidates Universal Editor from ue/models into the final configuration files. Think of it like a bundler, but for JSON configuration instead of JavaScript. You can run npm run build:json to regenerate the consolidated files in the repo's root folder. Additionally, the sample repository also uses husky to install a pre-commit hook. This is optional, but it helps you to bundle the UE JSON files with every commit.

When you add a new component:

  1. Create ue/models/blocks/your-block.json with the proper structure
  2. Add the new block to the filters list of ue/models/blocks/section.json
  3. Run npm run build:json to regenerate the consolidated files
  4. The new component will automatically be included in all three output files

This approach keeps our codebase organized while ensuring Universal Editor gets the configuration format it expects.

Additional Scripts for UE

In some situations, it is necessary to execute additional JavaScript code only when the page is loaded using the Universal Editor and while content changes are done by the partitioner.

The most common cases for this are:

This can be achieved by loading extra JavaScript code via ue.js. Hint: see the ue.js of the block collection with examples for both cases explained above. It covers the boilerplate blocks like carousel, accordion or tabs.

Custom page template for new pages (optional)

Page templates are used when creating new pages. By default, an empty page with only one section is always created. This is an optional configuration if you want to use custom page templates.

If you want to create pages with initial content or layout, you can create 1 or more page templates. These are simply HTML files in the project Git repository. See https://github.com/mhaack/special-project/blob/main/scripts/ue-template.html. The templates are registered in DA site or org properties on a specific path. A project can use multiple page templates e.g. per language or region or sub site area. See screenshot:

FAQ

Can I edit the same document in both editors?

Yes.

If I decide DA today, but want UE tomorrow, am I stuck?

No. If you go with one path today, you can change change at any point down the road.

Are plugins, extensions, etc. compatible between the two editors?

As of today, these are different implementations. Please reach out if you have an existing plugin / extension you would like in a different editing context.

Do I need to create UE instrumentation for sections, default content or images.

No. This is already done for you in the da-block-collection and can be copied more or less one to one.

Can I edit content fragments with UE on AB.

At the time of this writing, no.

Does this mean my investments in XWalk are obsolete?

No. XWalk is still the official, non-early access, expression of Universal Editor.

If I want to move from XWalk to UE on AB, can I do this?

It's early days, but in theory: yes. The UE instrumentation of your blocks can be mostly reused with some minor adjustments. Please reach out to the team for additional assistance.

I am a partner, how should I help my customer decide a direction?

First, there is never a right or wrong direction, but a mismatch of needs vs feature set. Adobe's stance is to pick the content repository and editing interface that actual authors want to use. As a partner, you should provide the benefits of each authoring modality (WYSIWYG, Forms, Document), let actual authors try each for themselves, and guide them based off their needs and feedback from their experiences.