Org Skills

Granite UI dialogs — structures that are easy to get wrong

Supporting material for aem-component-development. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://developer.adobe.com/experience-manager/reference-materials/cloud-service/administering/components/coral-ui/ and https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/components-templates/multifields

Open this for the exact XML of a dialog, a multifield, a validator, an overlay of a Core dialog, or an edit config.

A tabbed dialog

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    xmlns:nt="http://www.jcp.org/jcr/nt/1.0" xmlns:granite="http://www.adobe.com/jcr/granite/1.0"
    jcr:primaryType="nt:unstructured" jcr:title="Hero"
    sling:resourceType="cq/gui/components/authoring/dialog">
  <content jcr:primaryType="nt:unstructured"
      sling:resourceType="granite/ui/components/coral/foundation/container">
    <items jcr:primaryType="nt:unstructured">
      <tabs jcr:primaryType="nt:unstructured"
          sling:resourceType="granite/ui/components/coral/foundation/tabs"
          maximized="{Boolean}true">
        <items jcr:primaryType="nt:unstructured">
          <properties jcr:primaryType="nt:unstructured" jcr:title="Properties"
              sling:resourceType="granite/ui/components/coral/foundation/container">
            <items jcr:primaryType="nt:unstructured">
              <title jcr:primaryType="nt:unstructured"
                  sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                  fieldLabel="Title" name="./title" required="{Boolean}true"/>
              <showBadge jcr:primaryType="nt:unstructured"
                  sling:resourceType="granite/ui/components/coral/foundation/form/checkbox"
                  text="Show badge" name="./showBadge" value="{Boolean}true"
                  uncheckedValue="false"/>
            </items>
          </properties>
        </items>
      </tabs>
    </items>
  </content>
</jcr:root>
  • Property names start with ./. A checkbox without uncheckedValue never clears once ticked — the property simply is not submitted.
  • Force a type with a @TypeHint hidden field (name="./count@TypeHint" value="Long") or a typed default ({Boolean}, {Long}).
  • granite:class and granite:data attach CSS hooks and data for dialog JavaScript.

Composite multifield

<links jcr:primaryType="nt:unstructured"
    sling:resourceType="granite/ui/components/coral/foundation/form/multifield"
    fieldLabel="Links" composite="{Boolean}true">
  <field jcr:primaryType="nt:unstructured"
      sling:resourceType="granite/ui/components/coral/foundation/container"
      name="./links">
    <items jcr:primaryType="nt:unstructured">
      <label jcr:primaryType="nt:unstructured"
          sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
          fieldLabel="Label" name="./label"/>
      <path jcr:primaryType="nt:unstructured"
          sling:resourceType="granite/ui/components/coral/foundation/form/pathfield"
          fieldLabel="Target" name="./path" rootPath="/content/acme"/>
    </items>
  </field>
</links>

This stores links/item0, links/item1, … and is read with:

@ChildResource private List<Resource> links;
// or, with a model per row:
@ChildResource private List<HeroLink> links;   // HeroLink is a Resource-adaptable @Model

Without composite="{Boolean}true" the multifield stores a String array on ./links instead, and @ChildResource returns null. That mismatch — composite XML vs String[] injection, or the reverse — is the usual cause of "my multifield values are empty in the model". Check the XML before changing the Java.

Overlaying a Core Components dialog

Your component declares sling:resourceSuperType on the component node; the dialog then only describes the differences:

<jcr:root jcr:primaryType="nt:unstructured"
    sling:hideChildren="[linkURL]"            <!-- remove an inherited field -->
    sling:orderBefore="badge">                <!-- reorder -->
  <badge jcr:primaryType="nt:unstructured"
      sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
      fieldLabel="Badge" name="./badge"/>
</jcr:root>

sling:hideResource="{Boolean}true" on a node hides that single inherited node. Copying the whole Core dialog instead means re-doing the copy at every Core Components release.

Validation

<title … required="{Boolean}true" maxlength="{Long}60"
    validation="acme.title-length"/>

Register the validator from a clientlib in category cq.authoring.dialog (or a component-specific category listed in extraClientlibs):

(function ($, window) {
  $(window).adaptTo("foundation-registry").register("foundation.validation.validator", {
    selector: "[data-validation='acme.title-length']",
    validate: function (el) {
      if (el.value.length > 60) { return "Keep the title under 60 characters."; }
    }
  });
})(Granite.$, window);

Design dialog vs author dialog

_cq_design_dialog/.content.xml is the policy dialog for editable templates. Anything a template author decides once for every instance — allowed heading levels, image widths, whether lazy loading is on, which style groups exist — belongs there, and is read in the model with @ScriptVariable private Style currentStyle. Per-instance authored content belongs in _cq_dialog.

_cq_editConfig.xml

<jcr:root jcr:primaryType="cq:EditConfig">
  <cq:dropTargets jcr:primaryType="nt:unstructured">
    <image jcr:primaryType="cq:DropTargetConfig"
        accept="[image/.*]" groups="[media]" propertyName="./fileReference"/>
  </cq:dropTargets>
  <cq:listeners jcr:primaryType="cq:EditListenersConfig" afteredit="REFRESH_PAGE"/>
</jcr:root>

Use afteredit="REFRESH_PAGE" only when the component genuinely cannot re-render itself — it is a full page reload for the author on every edit. cq:inplaceEditing wires the RTE for in-context text editing.