> For AI agents: the complete documentation index is available at https://nhanbe.id.vn/llms.txt, the full documentation bundle is available at https://nhanbe.id.vn/llms-full.txt.
# Component Dialogs
## 1. Basic Dialog Structure
On Touch UI, all dialogs follow a strict nested XML structure built using Granite UI libraries. Below is the basic skeleton:
```xml
```
This file must be located at `_cq_dialog/.content.xml` inside the component directory.
To understand data storage mechanics, consider the interaction flow between UI and JCR:
```mermaid
sequenceDiagram
participant Author as Content Author
participant Dialog as "Touch UI Dialog\n(Granite UI)"
participant Servlet as Sling POST Servlet
participant JCR as "JCR Repository\n(Content Node)"
Author->>Dialog: Enter content & Click "Save"
Dialog->>Servlet: Send HTTP POST (mapped via name attribute)
Servlet->>JCR: Write properties to current Node
JCR-->>Servlet: Success response
Servlet-->>Dialog: Reload Component UI with new data
```
## 2. Core Field Types (Common Widgets)
Below are common Granite UI field types (widgets), serving as building blocks for Dialogs.
### Textfield (Single-line Text)
```xml
```
### Textarea (Multi-line Text)
```xml
```
### Rich Text Editor (RTE)
```xml
```
### Number Field
```xml
```
### Checkbox
```xml
```
### Select Dropdown
```xml
```
### Path Browser (Select Page or Asset)
```xml
```
**`filter` Parameter Table:**
| `filter` Value | Visibility Scope |
| ------------------ | --------------------------------------------- |
| `hierarchyNotFile` | Display Page structures only (exclude Assets) |
| `nosystem` | Hide system paths |
| _(unspecified)_ | Display all paths |
### Image Upload
```xml
```
### Hidden Field
```xml
```
### Date Picker & Color Picker
```xml
```
## 3. UI Organization using Tabs
For complex components, grouping fields into Tabs optimizes Authoring experience.
```xml
```
**Standard Tab Division Pattern:**
| Tab | Typical Fields |
| ------------ | ------------------------------------------------------------------ |
| **Content** | Title, text, images (Core content). |
| **Style** | Alignment, colors, size (Visual styling configuration). |
| **Advanced** | HTML ID, CSS class, Accessibility attributes (Technical settings). |
## 4. Multifield Mechanics (Data Arrays)
Multifield allows authors to generate repeating field groups (e.g., Carousel Slides, Link Lists).
The key attribute is `composite="{Boolean}true"`. When enabled, AEM saves each multifield item as an independent **child node** containing its own properties. Without this attribute, data is saved as a String Array (applicable only for multifields containing a single Textfield).
```xml
```
JCR structure when using `composite=true`:
```mermaid
graph TD
A["Component Node: /content/.../hero"] -->|name='./links' attribute| B["Folder: links"]
B --> C["Child Node: item0"]
B --> D["Child Node: item1"]
C --> C1["label = 'Home'"]
C --> C2["url = '/content/home'"]
D --> D1["label = 'About'"]
D --> D2["url = '/content/about'"]
```
## 5. Reading Values via Sling Models
When configuring Image Upload with `fileReferenceParameter="./fileReference"`, the selected DAM Asset path is saved as a String property.
In Sling Models, map this value using `@ValueMapValue`:
```java
@Model(adaptables = Resource.class)
public class HeroModel {
@ValueMapValue
private String fileReference; // DAM Path, e.g. "/content/dam/mysite/hero.jpg"
public String getFileReference() {
return fileReference;
}
}
```
## 6. Understanding the `name` Attribute
The `name` attribute determines the exact JCR location where data will be persisted:
| `name` Syntax | Storage Location in JCR |
| --------------------- | ------------------------------------------------------------ |
| `./title` | Directly on component content node (property named `title`). |
| `./jcr:title` | Directly on content node (using standard `jcr` namespace). |
| `./links/item0/label` | Nested inside sub-node `links/item0`. |
The `./` prefix specifies a relative path relative to the active content resource being edited.
## 7. Comprehensive Structure: Hero Component Dialog
Below is reference XML source code for a Hero banner dialog including column layout, tabs, and full field types:
```xml
```
## 8. Dynamic Visibility (Conditional Show/Hide)
A common project requirement is to toggle visibility of fields based on another field's value. Granite UI provides built-in client library `cq-dialog-dropdown-showhide`.
Example: Display "Custom URL" field only when selecting "Custom Link" in Dropdown.
```xml
```
Add CSS class `hero-link-options` to target containers (or wrap containers in `granite:class="hero-link-options"`).
## Summary
- Touch UI Dialogs are configured via XML in `_cq_dialog/.content.xml`.
- The `./` prefix in `name` stores properties on the current component content node.
- `composite="{Boolean}true"` is required for multifields to store entries as child nodes.
- Use `cq-dialog-dropdown-showhide` for conditional field toggling.