# Granite UI dialogs — structures that are easy to get wrong

> **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
<?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

```xml
<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:

```java
@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:

```xml
<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

```xml
<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`):

```js
(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`

```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.
