CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/aem-edge-delivery-services

Skills for building AEM Edge Delivery Services sites — site creation, block development, content modeling, code review, testing, and page import.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

SKILL.mdskills/ue-component-model/

name:
ue-component-model
description:
Use this to set up an AEM Edge Delivery Services block for the Universal Editor in an AEM-authoring (xwalk) project: the block's component definition, model (properties-panel fields) and filters in `blocks/<name>/_<name>.json`, adding it to the editor's add menu, option fields, multi-value fields, and tabs or containers. Also use it to fix a block missing from the add menu, or edits to component-definition.json, component-models.json or component-filters.json that disappear (those files are generated by build:json). Use content-modeling first to decide the block's structure; this skill only maps that structure to Universal Editor fields. Not for document-based authoring (Word, Google Docs, DA) or for decorate JS and CSS.
license:
Apache-2.0
metadata:
{"version":"1.0.1"}

Universal Editor Component Models

In AEM-authoring projects (aem-boilerplate-xwalk) authors fill properties-panel fields instead of a table. AEM renders those properties as the same table structure that document authors would type, so one block serves both. The structure therefore comes from content-modeling; this skill maps it to fields and registers the block. Skip it for document-based projects.

Steps

  1. Get the content model (rows, cells, variants) from content-modeling. If it does not exist, create it first. Do not derive fields from decorate().
  2. Map it to properties. Each row (or group of cells) is one property, in table order. Container blocks (cards, carousel): the container has a filter, each item has its own model, one row per item and one column per property.
  3. Write the partial blocks/<name>/_<name>.json with definitions, models and filters. Register it where authors can add it, or they cannot: a block id goes into the section filter in models/_section.json; a custom section type (for example a tab panel) goes into the main filter in models/_component-filters.json. Then run npm run build:json: it regenerates the root component-definition.json, component-models.json and component-filters.json, which you never edit by hand (the pre-commit hook also runs it).
  4. Check ids match (definition template.model or filter to the model or filter id), JSON is valid, and decorate() keeps data-aue-* instrumentation when it moves elements (moveInstrumentation(), defined in scripts/scripts.js of aem-boilerplate-xwalk).

Rules

The fields produce the same table a document author would type, so content-modeling's rules still apply to it (default content in cells, limited columns, no key/value for content, no nested blocks). The rules below are only the Universal Editor specifics.

  • Block definitions use resource type core/franklin/components/block/v1/block and a template name; without either the block renders nothing. Do not write custom AEM components. Default content (text, title, image, button) already has components.
  • Field names control the markup. image + imageAlt become one picture; link + linkText, linkTitle, linkType one link (type primary or secondary adds strong or em); title + titleType one heading. Suffixes are case sensitive: Title, Type, MimeType, Alt, Text.
  • Group fields into one cell by prefixing <group>_ (teaserText_title, teaserText_cta1): authors get separate fields, the block gets one cell of semantic elements.
  • Block options: a classes property (select or multiselect) becomes the options in the block header. classes_<name> fields extend it; a boolean classes_ field adds its name when on. Prefer options to key/value rows.
  • One level of nesting. Tabs, accordions and similar are modelled as sections (core/franklin/components/section/v1/section) that client-side auto-blocking combines into one block, not as blocks authored inside blocks. Auto-blocking producing a nested result is fine. For tabs, each tab panel is a section whose model has a tab-label field (section metadata); the tab list is auto-blocked from it. This is the maintainers' example pattern (see below), even though a heading would be the preferred label in document authoring.
  • Short lists of simple parts in one block (logos with alt text, keywords, several CTAs, carousel images) are multi-value fields: multi: true, as a container with its fields when each entry has several parts (for example image + imageAlt). Use child items (a container block with a filter and an item model) when each entry is rich content. Multi-value fields render as lists only when multi-field is enabled: public.xwalk.multi-field.enabled: true in xwalk.json (or the site config); check it and enable it if you rely on it. Otherwise values arrive as one comma-separated string. Containers cannot nest inside multi-fields.
  • Columns has no content model: only rows, columns and classes, default content in the cells.
  • "key-value": true renders name | value rows. Only for configuration-style blocks, never for content.
  • Field types: text, textarea, richtext, reference (assets), aem-content (any AEM content, for links), select, multiselect, checkbox-group, radio-group, boolean, number, date-time, container, tab, aem-content-fragment, aem-experience-fragment, aem-tag. Always set valueType as the type requires (string[] for checkbox-group, boolean, number).
  • Page metadata fields: a model with id page-metadata (or <template>-metadata).

Examples

Before inventing a pattern, read the example PRs in adobe-rnd/aem-boilerplate-xwalk (titles start with "Example:", by the xwalk maintainers; they are best practice): Tabs (#69), Multi-Fields and Composite Multi-Fields (#79), Column Layout (#72), Content Fragment Block (#76), Authoring Governance (#81). gh pr view <n> and gh pr diff <n> show the definition, model, filter and code.

skills

ue-component-model

README.md

tile.json