Developer Tools / Component Management / Dialog Fields /

Widgets glossary

Accordion

  • @Accordion
  • Resource type: /libs/granite/ui/components/coral/foundation/accordion
  • See spec: Accordion

Used to create an accordion widget containing other widgets organized in panels. See the following sample:

public class DialogWithAccordion {
    @DialogField
    @TextField
    private String field1;

    @Accordion(
        value = {
            @AccordionPanel(title = "Main panel", disabled = true),
            @AccordionPanel(title = "Description panel")
        },
        variant = AccordionVariant.LARGE,
        margin = true
    )
    AccordionFieldSet accordion;

    private static class AccordionFieldSet { // Used as the source of the nested accordion contents
        @DialogField
        @TextField
        @Place("Main panel")
        String name;

        @DialogField
        @TextArea
        @Place("Description panel")
        String description;
    }
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

The @Accordion annotation can be added to an arbitrary class member (field or method); its return type does not matter. Other widgets can refer to the columns with their @Place directives. See the "Placing widgets" section below for more detail.

Apart from this usage, @Accordion can be specified at the class level as the layout hint for the entire dialog. See Laying out your dialog for details.

Alert

  • @Alert
  • Resource type: /libs/granite/ui/components/coral/foundation/alert
  • See spec: Alert

Used to render a component responsible for showing conditional alerts to the users in Touch UI dialogs. Usage is similar to the following:

Note: this widget annotation does not need to be accompanied by a @DialogField.

public class DialogWithAlert {
    @Alert(
        size = AlertSize.LARGE,
        text = "Alert content",
        title = "Alert title",
        variant = StatusVariantConstants.SUCCESS
    )
    String alertField;
}

AnchorButton

This is a component to represent a standard HTML hyperlink (<a>), but to look like a button in Touch UI dialogs. Usage is as follows:

public class DialogWithAnchorButton {
    @AnchorButton(
        href = "https://acme.com/en/content/page.html",
        hrefI18n = "https://acme.com/fr/content/page.html",
        text = "Button Text",
        linkChecker = LinkCheckerVariant.SKIP,
        icon = "search",
        actionConfigName = "actionConfig"
    )
    String field;
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

Autocomplete

Used to render the Autocomplete component in Touch UI dialogs. Options that appear as the user enters text depend on the value of the namespaces property of the @AutocompleteDataSource. If unset, all tags under the <content/cq:Tags> JCR directory will be available. Otherwise, you specify one or more particular <cq:Tag> nodes as in the snippet below:

public class AutocompleteDialog {
    @DialogField
    @Autocomplete(
        multiple = true,
        datasource = @AutocompleteDatasource(namespaces = {"workflow", "we-retail"})
    )
    String field;
}

Button

  • @Button
  • Resource type: /libs/granite/ui/components/coral/foundation/button
  • See spec: Button

Helps to create buttons in Touch UI dialogs. Usage is as follows:

public class DialogWithButton {
    @Button(
        type = ButtonType.SUBMIT,
        text = "save",
        icon = "edit",
        command = "shift+s",
        variant = ElementVariantConstants.PRIMARY,
        block = true
    )
    String field;
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

ButtonGroup

Used to render button groups in Touch UI dialogs. A @ButtonGroup contains one or more manually specified @ButtonGroupItems or declares an @OptionProvider. It has the selectionMode to define how many values will be stored at once (the widget does not store values to JCR unless you select "single" or "multiple"). You can also specify the ignoreData and deleteHint flags.

Each of a @ButtonGroup's manual items is initialized with mandatory text and value. Use checked to define a button that is selected by default. You can specify several more optional parameters, such as icon or size. A visually textless button can be rendered with hideText = true while Adobe recommends that you never set the text property to an empty string.

Next is a code snippet for a @ButtonGroup usage:

public class DialogWithButtonGroup {
    @ButtonGroup(items = {
        @ButtonGroupItem(text = "Empty", value = ""),
        @ButtonGroupItem(text = "One", value = "1", hideText = true, icon = "/content/some/icon"),
        @ButtonGroupItem(text = "Two", value = "2", checked = true)
    },
        selectionMode = SelectionMode.SINGLE,
        ignoreData = true,
        deleteHint = false)
    String options;
}

You can define an optionProvider that will produce options based on a variety of supported media such as a JCR node tree, a tag folder, etc. See the chapter on OptionProvider.

Checkbox

  • @Checkbox
  • Resource type: /libs/granite/ui/components/coral/foundation/form/checkbox
  • See spec: Checkbox

Used to produce either simple or complex (nested) checkbox inputs in Touch UI dialogs.

Simple checkbox usage is as follows:

public class DialogWithCheckbox {
    @DialogField
    @Checkbox(
        text = "Is option enabled?",
        value = "{Boolean}true",            // These are the defaults. You may override them
        uncheckedValue = "{Boolean}false",  // to, e.g., swap the field's meaning to "disabled" without migrating content
        autosubmit = true,
        tooltipPosition = Position.RIGHT
    )
    private boolean enabled;
}

Checkbox nesting

Sometimes you’ll need to supply a list of sub-level checkboxes to a parent checkbox whose displayed state will be affected by the states of child inputs. You can achieve this by specifying a sublist property of @Checkbox with a reference to a nested class encapsulating all the sub-level options. This is actually a full-feature rendition of Granite UI NestedCheckboxList .


@Dialog
public class NestedCheckboxListDialog {
    @DialogField
    @Checkbox(text = "Level 1 Checkbox", sublist = Sublist.class)
    private boolean option1L1;

    private static class Sublist {
        @DialogField
        @Checkbox(text = "Level 2 Checkbox 1")
        boolean option2L1;

        @DialogField
        @Checkbox(text = "Level 2 Checkbox 2", sublist = Sublist2.class)
        boolean option2L2;
    }

    private static class Sublist2 {
        @DialogField
        @Checkbox(text = "Level 3 Checkbox 1")
        boolean option3L1;

        @DialogField
        @Checkbox(text = "Level 3 Checkbox 2")
        boolean option3L2;
    }
}

ColorField

  • @ColorField
  • Resource type: /libs/granite/ui/components/coral/foundation/form/colorfield
  • See spec: ColorField

Used to render inputs for storing color values in Touch UI dialogs.

public class DialogWithColorField {
    @DialogField
    @ColorField(
        value = "#4488CC",
        emptyText = "test-string",
        variant = ColorVariant.SWATCH,
        autogenerateColors = GenerateColorsState.SHADES,
        showSwatches = false,
        showDefaultColors = false,
        showProperties = false,
        customColors = {"#FF0000", "#00FF00", "#0000FF"}
    )
    String color;
}

DatePicker

  • @DatePicker
  • Resource type: /libs/granite/ui/components/coral/foundation/form/datepicker
  • See spec: DatePicker

Used to render date/time pickers in Touch UI dialogs. You can set the type of DatePicker (whether it stores only the date, only the time, or both). You can also display format (see Java documentation on possible formats) and minimal and maximal date/time to select (may also specify a timezone). To make the formatter effective, set typeHint = TypeHint.STRING to store date/time to JCR as only a string and not a numeric value.

public class DatePickerDialog {
    @DialogField
    @DatePicker(
        type = DatePickerType.DATETIME,
        displayedFormat = "DD.MM.YYYY HH:mm",
        valueFormat = "DD.MM.YYYY HH:mm",
        minDate = @DateTimeValue(day = 1, month = 1, year = 2019),
        maxDate = @DateTimeValue(day = 30, month = 4, year = 2020, hour = 12, minute = 10, timezone = "UTC+3"),
        typeHint = TypeHint.STRING
    )
    String currentDate;
}

FieldSet

  • @FieldSet
  • Resource type: /libs/granite/ui/components/coral/foundation/form/fieldset
  • See spec: FieldSet

Creates a fieldset (a group of fields that can be managed as one) in a Touch UI dialog. See the dedicated section on the fieldsets.

FileUpload

  • @FileUpload
  • Resource type: /libs/granite/ui/components/coral/foundation/form/fileupload
  • See spec: FileUpload

Used to render the FileUpload components in Touch UI dialogs. You can specify acceptable MIME types of files and graphic styles of the created component. You’ll be required to provide the uploadUrl to an accessible JCR path (you may also specify a sub-node of an existing node that will be created as needed). Sling shortcut ${suffix.path} for component-relative JCR path is also supported.

public class FileUploadDialog {
    @DialogField
    @FileUpload(
        uploadUrl = "/content/dam/my-project",
        autoStart = true,
        async = true,
        mimeTypes = {
            "image/png",
            "image/jpg"
        },
        buttonSize = ButtonSize.LARGE,
        buttonVariant = ButtonVariant.ACTION_BAR,
        icon = "dataUpload",
        iconSize = IconSize.SMALL
    )
    String currentDate;
}

FixedColumns

Used to create a container which consists of one or more columns. See the following sample:

public class DialogWithFixedColumnsWidget {
    @DialogField
    @TextField
    @Place("First column")
    private String field1;

    @FixedColumns(
        value = {
            @Column(title = "First column"),
            @Column(title = "Second column")
        },
        maximized = false, // optional
        margin = true // optional
    )
    private Object columnsHolder;

    @DialogField
    @TextField
    @Place("Second column")
    private String field2;

}

Note: this widget annotation does not need to be accompanied by a @DialogField.

The @FixedColumns annotation can be added to an arbitrary class member (field or method). Its return type does not matter. Titles of columns do not get rendered: they are used merely for "binding" other widgets to particular columns. Other widgets can refer to the columns with their @Place directives. See the "Placing widgets" section below for more detail.

Apart from this usage, @FixedColumns can be specified at the class level as the layout hint for the entire dialog. See Laying out your dialog for details. Take a note that additional @FixedColumns properties, such as maximized, are only meaningful for the in-dialog usage.

Heading

  • @Heading
  • Resource type: /libs/granite/ui/components/coral/foundation/heading
  • See spec: Heading

Renders a heading element in Touch UI dialogs. See the following usage example:

public class DialogWithHeading {
    @Heading(text = "Heading text", level = 2)
    String heading;
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

Hidden

  • @Hidden
  • Resource type: /libs/granite/ui/components/coral/foundation/form/hidden
  • See spec: Hidden

Used to render hidden inputs in Touch UI dialogs.

public class DialogWithHiddenFields {
    @DialogField
    @Hidden("bundled-value")
    String field;

    @DialogField(name = "field@Delete") // Can be used as a Sling POST servlet hint
    @Hidden
    String fieldRemover;
}
  • @Hyperlink
  • Resource type: /libs/granite/ui/components/coral/foundation/hyperlink
  • See spec: Hyperlink

Used to represent HTML hyperlinks(<a>)in Touch UI dialogs. See the usage sample below:

public class DialogWithHyperlink {
    @Hyperlink(
        href = "https://acme.com/en/content/page.html",
        hrefI18n = "https://acme.com/fr/content/page.html",
        text = "Link Text",
        hideText = true,
        linkChecker = LinkCheckerVariant.SKIP
    )
    String field;
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

ImageUpload

  • @ImageUpload
  • Resource type: cq/gui/components/authoring/dialog/fileupload

Designed as a companion to @FileUpload, it mimics the features of the FileUpload component that was there before Coral 3 was introduced and the built-in upload component situated at cq/gui/components/authoring/dialog/fileupload in your AEM installation. Technically, this is just another rendition of the FileUpload logic aimed at mainly uploading images via drag-and-drop. Use it like you’ll see in the following code snippet:

public class ImageFieldDialog {
    @DialogField
    @ImageUpload(
        mimeTypes = {
            ImageUploadConstants.MIME_TYPE_PNG,
            ImageUploadConstants.MIME_TYPE_JPG
        },
        sizeLimit = 100000,
        fileNameParameter = "./image/fileName",
        fileReferenceParameter = "image/fileRef",
        allowUpload = true,
        icon = "search"
    )
    String file;
}

Include

  • @Include
  • Resource type: /libs/granite/ui/components/coral/foundation/include
  • See spec: Include

Used to set up embedded resources in Touch UI dialogs. An inclusion can be any resource resolvable by a Sling ResourceResolver. See the usage sample below:

public class DialogWithInclude {
    @Include(
        path = "/content/path/to/resource",
        resourceType = "component/resource/type"
    )
    String field;
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

MultiField

  • @MultiField
  • Resource type: /libs/granite/ui/components/coral/foundation/form/multifield
  • See spec: Multifield

Creates a multifield (a group of one or more fields that will be reproduced multiple times) in a Touch UI dialog. See the dedicated section on the multifields.

NumberField

Used to render inputs for storing numbers in Touch UI dialogs. Use it as follows:

public class DialogWithNumberField {
    @DialogField
    @NumberField(
        value = "", // Or else a particular value can be specified
        min = -10,
        max = 10,
        step = 2
    )
    String number;
}

Password

  • @Password
  • Resource type: /libs/granite/ui/components/coral/foundation/form/password
  • See spec: Password

Used to render password inputs in Touch UI dialogs. If you wish to engage a "confirm the password" box in your dialog's layout, create two @Password-annotated fields in your Java class, then feed the name of the second field to the retype property for the first one. If the values of the two fields do not match, you’ll see a validation error.

public class DialogWithPasswordField {
    @DialogField
    @Password(retype = "confirmPass")
    String pass;

    @DialogField
    @Password
    String confirmPass;
}

PathField

  • @PathField
  • Resource type: /libs/granite/ui/components/coral/foundation/form/pathfield
  • See spec: PathField

Used to produce path selectors in Touch UI dialogs. You can implement it as in the following example:

public class DialogWithPathField {
    @DialogField
    @PathField(
        rootPath = "/content/dam",
        emptyText = "Enter a path here",
        forceSelection = true,
        droppable = true,
        multiple = true,
        filter = NodeFilter.NOSYSTEM
    )
    String path;
}

Note: droppable property is supported since AEM 6.5.10.

RadioGroup

  • @RadioGroup
  • Resource type: /libs/granite/ui/components/coral/foundation/form/radiogroup
  • See spec: RadioGroup

Renders groups of RadioButtons in Touch UI dialogs. The usage is as follows:

public class DialogWithRadioGroup {
    @DialogField
    @RadioGroup(
        buttons = {
            @RadioButton(text = "Button 1", value = "1", checked = true),
            @RadioButton(text = "Button 2", value = "2"),
            @RadioButton(text = "Button 3", value = "3", disabled = true)
        }
    )
    String field;
}

Note that you can set this up to use a datasource instead of a list of buttons. This way your @RadioGroup would look like this:

public class DialogWithRadioGroup {
    @DialogField
    @RadioGroup(datasource = @DataSource(path = "my/path", resourceType = "my/res/type"))
    String field;
}

You can define an optionProvider that will produce options based on a variety of supported media such as a JCR node tree, a tag folder, etc. See the chapter on OptionProvider.

RichTextEditor

Renders a full-featured editor for rich text. See the dedicated section on the usage of RTE.

Select

  • @Select
  • Resource type: /libs/granite/ui/components/coral/foundation/form/select
  • See spec: Select

Used to render select inputs in Touch UI dialogs. @Select consists of a set of @Option items. Each of them must be initialized with mandatory value and several optional parameters, such as text (represents an option label), boolean flags selected and disabled, and String values responsible for visual presentation of an option: icon, statusIcon, statusText and statusVariant.

Here is a code snippet for a typical @Select usage:

public class DialogWithDropdown {
    @DialogField(label = "Rating")
    @Select(
        options = {
            @Option(
                text = "1 star",
                value = "1",
                selected = true,
                statusIcon = "/content/dam/samples/icons/1-star-rating.png",
                statusText = "This is to set 1-star rating",
                statusVariant = StatusVariantConstants.SUCCESS
            ),
            @Option(text = "2 stars", value = "2"),
            @Option(text = "3 stars", value = "3"),
            @Option(text = "4 stars", value = "4", disabled = true),
            @Option(text = "5 stars", value = "5", disabled = true)
        },
        deleteHint = false,
        emptyOption = false,
        emptyText = "Select rating",
        forceIgnoreFreshness = false,
        multiple = false,
        ordered = false,
        translateOptions = false,
        variant = SelectVariant.DEFAULT
    )
    String dropdown;
}

Note that you can set this up to use a datasource instead of a list of options. This way your @Select would look like this:

public class DialogWithDropdown {
    @DialogField(label = "Rating")
    @Select(
        datasource = @DataSource(path = "my/path", resourceType = "my/res/type"),
        emptyText = "Select rating"
    )
    String dropdown;
}

You can define an optionProvider that will produce options based on a variety of supported media such as a JCR node tree, a tag folder, etc. See the chapter on OptionProvider.

Switch

  • @Switch
  • Resource type: /libs/granite/ui/components/coral/foundation/form/switch
  • See spec: Switch

Used to render an on-off toggle switch in a Touch UI dialog.

public class DialogWithSwitch {
    @DialogField
    @Switch(
        value = "{Boolean}true",            // These are the defaults. You may override them
        uncheckedValue = "{Boolean}false",  // to, e.g., swap the field's meaning to "disabled" without migrating content
        checked = true,
        onText = "TurnedOn",                // These values are optional
        offText = "TurnedOff"
    )
    private boolean enableOption;
}

Tabs

  • @Tabs
  • Resource type: /libs/granite/ui/components/coral/foundation/tabs
  • See spec: Tabs

Used to create a nested tabs container possessing other widgets organized in tabs. See the following sample:

public class DialogWithTabs {
    @Tabs(
        value = {
            @Tab(
                title = "First Inner",
                trackingElement = "first"
            ),
            @Tab(
                title = "Second Inner",
                trackingElement = "second",
                active = true,
                icon = "some/icon",
                padding = true
            )
        },
        maximized = true,
        trackingFeature = "feature1",
        trackingWidgetName = "widget1"
    )
    private TabsFieldset tabsHolder;

    private static class TabsFieldset { // Used as the source of widgets for the nested tabs structure
        @DialogField(label = "Field 1 in the inner Tab")
        @TextField
        @Place("First Inner")
        String field1;

        @DialogField(label = "Field 2 in the inner Tab")
        @TextField
        @Place("Second Inner")
        String field2;
    }
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

The @Tabs annotation can be added to an arbitrary class member (field or method); its return type does not matter. Other widgets can refer to the columns with their @Place directives. See the "Placing widgets" section below for more detail.

Apart from this usage, @Tabs can be specified at the class level as the layout hint for the entire dialog (see Laying out your dialog for details). Take note that the @Tabs annotation contains properties for both usages, but not every property has meaning for either. Refer to the Javadoc on @Tabs to learn which properties should be used for tabs at class level and tabs as a widget, respectively.

Text

  • @Text
  • Resource type: /libs/granite/ui/components/coral/foundation/text
  • See spec: Text

Used to produce a text component that is rendered as in Touch UI dialog. That's how it may look like:

public class DialogWithText {
    @Text("Just a string notice")
    String textHolder;
}

Note: this widget annotation does not need to be accompanied by a @DialogField.

TextArea

  • @TextArea
  • Resource type: /libs/granite/ui/components/coral/foundation/form/textarea
  • See spec: Textarea

Used to render a textarea-type HTML input in Touch UI dialogs.

public class DialogWithTextArea {
    @DialogField(label = "Edit the TextArea here")
    @TextArea(
        value = "Default value",
        emptyText = "Empty text",
        autocomplete = "on",
        autofocus = true,
        rows = 10,
        cols = 50,
        resize = TextAreaResizeType.BOTH
    )
    String text;
}

TextField

  • @TextField
  • Resource type: /libs/granite/ui/components/coral/foundation/form/textfield
  • See spec: TextField

Used to produce text inputs in Touch UI dialogs. The usage is as follows:

public class DialogWithTextField {
    @DialogField
    @TextField
    String text1;

    @DialogField
    @TextField(
        value = "Predefined value",
        emptyText = "Empty text",
        autocomplete = "on",
        autofocus = true,
        maxLength = 255
    )
    String text2;
}