Components

Dialogs

A dialog is the authoring form that exposes a component’s configurable properties to content authors. It is shown in the editing UI when an author edits a placed component, which is why it is also called the edit dialog. This page covers what a dialog is, how you define one for a component, and the field types available.

What a dialog is

Components store their authored settings as properties on the component’s content node. A dialog is the form that lets an author read and change those properties without editing content nodes by hand. Each field in the dialog is bound to a single property by name, so what the author types is written straight back to the component instance and picked up the next time the component renders.

A dialog is made of field nodes, one per editable property. Every field declares the property it writes to, a label shown to the author, and a field type that decides the input control (a text box, a checkbox, a picker, and so on). Only properties you surface through a field are editable in the UI; anything else stays fixed at whatever the component or its template sets.

Defining a dialog

A dialog is defined on the component itself, in an edit node under the component with a .content.xml. The root node is a dialog resource, it holds a single content container, and the field nodes live inside that container:

src/content/jcr_root/apps/<project>/components/<component>/edit/.content.xml

The root sets sling:resourceType="kestros/cms2/dialog". Each field sets sling:resourceType="kestros/cms2/fields/general/<type>" (or a Kestros picker type) and binds to a property with name=. Common field attributes are label, required, disabled, and focused (which auto-focuses the field when the dialog opens). Here is a minimal dialog with a single text field:

sample-component/edit/.content.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:kes="http://kestros.io/kes/1.0"
          jcr:primaryType="nt:unstructured"
          sling:resourceType="kestros/cms2/dialog">
    <content jcr:primaryType="nt:unstructured">
        <text jcr:primaryType="nt:unstructured"
              sling:resourceType="kestros/cms2/fields/general/textfield"
              name="sampleProperty"
              label="Sample Property"
              focused="{Boolean}true"/>
    </content>
</jcr:root>

A field’s name is the exact property it writes to. Match it to the property a component reads (for example the property behind a getSampleProperty() getter) so the authored value flows straight back into rendering.

Use the cms2 dialog shape. New dialogs should set sling:resourceType="kestros/cms2/dialog", as shown above. The older kestros/cms/dialog format used a different field vocabulary (fields addressed the property with propertyName= rather than name=). A running instance still carries both /libs/kestros/cms/* and /libs/kestros/cms2/*, but the cms2 shape is the supported one for new components.

Available field types

Fields fall into two groups: general fields for the common input controls, and Kestros-specific pickers that select platform resources such as components, datasources, layouts, themes, and variations.

General fields use sling:resourceType="kestros/cms2/fields/general/<type>":

Field type	resourceType suffix	What it’s for
`textfield`	`general/textfield`	Single-line text input
`textarea`	`general/textarea`	Multi-line text input
`richtext`	`general/richtext`	Rich-text (formatted) editor
`numberfield`	`general/numberfield`	Numeric input
`checkbox`	`general/checkbox`	Single boolean checkbox
`togglefield`	`general/togglefield`	On/off toggle switch
`selectfield`	`general/selectfield`	Dropdown select from a list of options
`radiogroup`	`general/radiogroup`	Single choice from a set of radio options
`multifield`	`general/multifield`	Repeatable group of fields (a list of entries)
`pathfield`	`general/pathfield`	JCR path input / browser
`tagfield`	`general/tagfield`	Tag selection input
`hiddenfield`	`general/hiddenfield`	Non-visible field carrying a fixed value
`datefield`	`general/datefield`	Date input
`timefield`	`general/timefield`	Time input
`datetimefield`	`general/datetimefield`	Combined date and time input
`datetimelocalfield`	`general/datetimelocalfield`	Local (no-timezone) date and time input
`dynamic-datasource-path`	`general/dynamic-datasource-path`	Path input driven by a datasource
`dynamic-page-type-select`	`general/dynamic-page-type-select`	Select populated with available page types
`dynamic-route-handler-select`	`general/dynamic-route-handler-select`	Select populated with available route handlers

Kestros-specific pickers use sling:resourceType="kestros/cms2/fields/kestros/<type>":

Picker	resourceType suffix	What it selects
`component-picker`	`kestros/component-picker`	A component
`datasource-picker`	`kestros/datasource-picker`	A datasource
`layout-picker`	`kestros/layout-picker`	A layout
`theme-picker`	`kestros/theme-picker`	A theme
`variations-picker`	`kestros/variations-picker`	Component variations

These field types are the set registered under /libs/kestros/cms2/fields on a running 0.9.0 instance, so the list reflects the field set that ships with the platform. If a field type is missing on your instance, confirm what is registered under that path before relying on it.

For how dialogs fit into building a component end to end, see Custom Components. For the variations-picker and how variations are registered and applied, see Variations.