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 withoutuncheckedValuenever clears once ticked — the property simply is not submitted. - Force a type with a
@TypeHinthidden field (name="./count@TypeHint" value="Long") or a typed default ({Boolean},{Long}). granite:classandgranite:dataattach 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.