Ue Component Model

Universal Editor Component Model Configuration

This skill helps you create or edit the three JSON configuration files that control how AEM Edge Delivery Services (EDS) blocks appear and behave in the Universal Editor (UE):

1. component-definition.json — Registers blocks in the UE component palette
2. component-models.json — Defines property panel fields for each block
3. component-filters.json — Controls where blocks can be placed

When to Use

• Creating a new block that needs UE authoring support
• Adding/modifying fields on an existing block's property panel
• Registering a block so it appears in the author's component palette
• Setting up container blocks with child items
• Adding block variants/style options

Workflow

Step 1: Understand the Block

Before generating any configuration, read and analyze:

1. The block's JS file (blocks/<name>/<name>.js) — understand what content the decorate(block) function expects:

   • What does it read from the block div? (images, links, text, classes)
   • Does it expect a flat structure or rows of items?
   • Does it use block.querySelector('a') (links/URLs), block.querySelector('picture') (images), etc.?
   • Does it check for CSS classes/variants?

2. The block's CSS file (blocks/<name>/<name>.css) — look for variant-specific styles.

3. Existing config — check if entries already exist:

   • Search component-definition.json for the block ID
   • Search component-models.json for the model ID
   • Search component-filters.json for the block in the section components list
   • Check for a blocks/<name>/_<name>.json distributed config file

Step 2: Determine the Block Type

Based on the JS analysis:

• Simple block: One component with its own fields. Most blocks are this type.

  • Example: Hero, Embed — single model, no children

• Container block: Has repeatable child items (cards, slides, tabs).

  • Clue: JS iterates over block.children or creates items from rows
  • Needs: container definition + item definition + filter

• Key-value block: Configuration-style block (2-column key-value pairs).

  • Clue: Each property is independent, not a grid of content
  • Needs: "key-value": true in template

Step 3: Design the Model Fields

Map the block's content expectations to component model fields. Read references/field-types.md for the full field type reference.

Common field mappings:

Field naming rules (semantic collapsing):

• image + imageAlt → collapsed into <picture><img alt="...">
• link + linkText + linkTitle + linkType → collapsed into <a href="..." title="...">text</a> with optional class
• title + titleType → collapsed into <h2>title</h2> (level from titleType)
• Fields prefixed with group_ (underscore separator) are grouped into a single cell

Step 4: Generate the Configuration

Generate entries for all three files. The approach depends on whether the project uses centralized or distributed config.

Check for distributed config pattern: If the block directory contains _<blockname>.json files (e.g., blocks/hero/_hero.json), create a distributed config file instead of editing the central files.

For Centralized Config (editing the three root JSON files):

component-definition.json — Add to the "Blocks" group's components array:

{
  "title": "<Block Display Name>",
  "id": "<block-id>",
  "plugins": {
    "xwalk": {
      "page": {
        "resourceType": "core/franklin/components/block/v1/block",
        "template": {
          "name": "<Block Name>",
          "model": "<model-id>"
        }
      }
    }
  }
}

For container blocks, add both the container AND item definitions. The container gets "filter" instead of "model", and the item uses "core/franklin/components/block/v1/block/item" as resourceType.

For key-value blocks, add "key-value": true to the template.

Template can include default values for any model field (e.g., "titleType": "h3", "classes": ["light"]).

component-models.json — Add a new model entry:

{
  "id": "<model-id>",
  "fields": [
    {
      "component": "<field-type>",
      "name": "<property-name>",
      "label": "<Display Label>",
      "valueType": "string"
    }
  ]
}

component-filters.json — Add the block ID to the section filter's components array. For container blocks, also add a new filter entry defining allowed children.