Multi field

info.magnolia.ui.field.MultiFieldDefinition renders a complex field composed of one or more field sets (for example, three sets of two text fields). Magnolia provides four preconfigured multi field definitions:

  • info.magnolia.ui.field.JcrMultiValueFieldDefinition: allows you to enter multiple values of a single type to be stored as an array in a single JCR property (jcrMultiValueField).

  • info.magnolia.ui.field.JcrMultiLinkFieldDefinition: allows you to select multiple values of a single type in a chooser dialog to be stored as an array in a single JCR property (jcrMultiLinkField).

  • info.magnolia.ui.field.JcrMultiFieldDefinition: allows you to create multiple JCR fields (jcrMultiField).

  • info.magnolia.rest.ui.field.JsonMultiFieldDefinition: allows you to create multiple JSON fields to be used in an app with its own JSON data source (jsonMultiField).

These multi field definitions are part of the Magnolia 6 UI framework. Their fully qualified class names are:

  • info.magnolia.ui.field.JcrMultiValueFieldDefinition

  • info.magnolia.ui.field.JcrMultiLinkFieldDefinition

  • info.magnolia.ui.field.JcrMultiFieldDefinition

  • info.magnolia.rest.ui.field.JsonMultiFieldDefinition

In the Magnolia 5 UI framework, the field functionally parallel to the JCR fields is Multivalue field. There is no corresponding 5 UI implementation for the JSON multi field.

Example definitions

  • JCR multi-value field

  • JCR multi-link field

  • JCR multi field

  • JSON multi field

assignedSegments:
  $type: jcrMultiValueField
  label: Multi-value field
  field:
    $type: comboBoxField
    label: Path
    datasource:
      $type: jcrDatasource
      workspace: website
jcrMultiLinkField:
  $type: jcrMultiLinkField
  label: Multi-link field
  field:
    $type: linkField
    label: Page
    datasource:
      $type: jcrDatasource
      workspace: website
damMultiLinkField:
  $type: jcrMultiLinkField
  label: Multi-link field
  chooserId: dam-app-core:multiChooser
  field:
    $type: damLinkField
    label: Asset
multi:
  i18n: true
  $type: jcrMultiField
  label: Address list
  field:
    $type: compositeField
    label: Address
    properties:
      street:
        $type: textField
        label: Street
      city:
        i18n: true
        $type: textField
        label: City
      zip:
        $type: textField
        label: ZIP code
stationboard:
  label: Station Board
  $type: jsonMultiField
  itemProvider:
    $type: jsonMultiFieldProvider
  field:
    $type: jsonCompositeField
    idPropertyName: name
    properties:
      name:
        label: Name
        $type: textField
        readOnly: true
      to:
        label: To
        $type: textField
        readOnly: true
      operator:
        label: Operator
        $type: textField
        readOnly: true

JSON data source is read-only. Therefore, it only supports read-only fields in, typically, the content detail subapp of a read-only REST app. jsonMultiField is designed to show field data from REST sources; you cannot add, edit, or delete a field entry.

The example above is used in the Stations app contained in the field-examples-module. See also Composite field.

You can preview this example using the field-examples-module. See Field examples module for more information.

Field properties

Common multi field properties

Property Description

field

required

Node containing an editor property definition item (typically, a field).

All field types are supported. See List of fields for more information.

JcrMultiLinkFieldDefinition supports only link and combobox fields.

chooserId

optional (used only in JcrMultiLinkFieldDefinition), default is ui-framework-jcr:multiChooser

Unique identifier for the multi-chooser dialog. If none is specified, the JCR multiChooser will be used by default.

entryResolution

optional, default is

  • ByMultiValueProperties for JcrMultiValueFieldDefinition

  • MultiFieldEntryResolution for JcrMultiFieldDefinition

  • MultiJcrBlockEntryResolution for MultiJcrBlockDefinition

  • JsonMultiFieldEntryResolver for JsonMultiFieldDefinition

Implementation class that defines how the child entries of a multi field should be resolved.

MultiFieldEntryResolution of JcrMultiFieldDefinition extends ByIndexedChildNodes, which resolves entry nodes regardless of node names. To enable this non-strict resolution behavior, there is a strict property that is set to false by default.

Setting strict to true ensures backward compatibility (for example, when porting configurations that use Magnolia 5 UI multi field transformers). In configurations such as the two below, strict falls back to the required value and that change appears in the Definitions app.

  • itemProvider specifies the type of data binding for subnodes in complex fields. When you configure a multi field with CurrentItemProvider and set entryResolution to MultiFieldEntryResolution, the strict node resolution is set to false. This ensures that nodes, which aren’t multi fields, don’t get resolved as multi fields.

  • When you configure a multi field with isSupportI18N set to false, the strict property of entryResolution is set to false. The isSupportI18N configuration flattens localized multi parent nodes into a single parent. However, you need to resolve child nodes in a way that considers their locale suffix and doesn’t take everything beneath the parent, so strict is set to true.

orderHandler

optional, default is

  • MultiValuePropertyOrderHandler for JcrMultiValueFieldDefinition

  • DefaultJcrNodeOrderHandler for JcrMultiFieldDefinition

  • MultiJcrBlockOrderHandler for JcrMultiFieldDefinition

Implementation class that sorts nodes and ensures that the suffixes in index names correspond to the order in which they are stored.

When MultiFormDefinition$OrderHandlerDefinition$Noop is used, the order of the items of a multi field cannot be changed retroactively.

canRemoveItems

optional, default is true for JcrMultiValueFieldDefinition and JcrMultiFieldDefinition

When false, the items of a multi field cannot be removed from a dialog.

buttonSelectAddLabel

optional, default is translated buttons.add key (translated dialogs.buttons.select.multiple key for JcrMultiLinkFieldDefinition)

Button label for adding an item. The value is i18n-able.

buttonSelectRemoveLabel

optional, default is translated buttons.delete key

Button label for removing an item. The value is i18n-able.

minItems

optional, default is 0

Specifies the minimum number of items to be added.

maxItems

optional, default is Integer.MAX_VALUE

Specifies the maximum number of items to be added.

If minItems is greater than maxItems, item count validation will be disabled.

itemCountErrorMessage

optional, default is translated validators.multi.itemCount.errorMessage key

Error message shown when the number of items is less than minItems or greater than maxItems. The value can be literal or a key of a message bundle.

required

optional, default is false

Makes the field required. An asterisk is displayed next to the field label.

requiredErrorMessage

optional, default is translated validation.message.required key

Error message shown when required is set to true and the user saves an empty field. The value can be literal or a key of a message bundle.

Common complex field properties

Property Description

name

required

Name of the field definition item. Derived from the configured node name. Use alphanumeric characters without spaces.

class

required (unless $type is used)

Type of the field definition item. The value must be a fully qualified class name and a subtype of info.magnolia.ui.field.FieldDefinition. See Field types for possible values.

$type

You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.field.FieldType. The proper value is defined by the annotation.

Example class annotation
@FieldType("textField")
public class TextFieldDefinition extends ConfiguredFieldDefinition<String> {
...
}

See Field types for possible values.

itemProvider

required, default is

  • JcrPropertyProvider for JcrMultiValueFieldDefinition

  • JcrChildNodeProviderDefinition for JcrMultiFieldDefinition

  • CurrentItemProviderDefinition for StaticFieldViewDefinition

Node with a $type property that specifies the type of data binding for the subnodes in complex fields.

See Item providers for more information.

Do not use JcrMultiValueFieldDefinition with any item provider other than the default JcrPropertyProvider.

description

optional

Help text displayed when the user clicks the help icon. The value can be literal or a key of a message bundle.

i18n

optional, default is false

Enables i18n authoring support, which allows editors to write foreign-language or regionally targeted content. A two-letter language identifier (en, de, fr, etc.) is displayed on controls where i18n is set to true.

When defining the property for a multi field, the following configurations are possible:

  • To translate a unique set of entries, set i18n to false for the multi field and to true for its inner fields.

  • To translate different sets of entries, set i18n to true for the multi field and to false for its inner fields (no fallback here between languages).

We do not recommend setting i18n to true on both levels.

label

optional

Field label displayed to editors. The value can be literal or a key of a message bundle.

If you do not provide the property, Magnolia will fall back to a generated i18n key.

If you do not want to have any label, set the property to an empty string such as label: "" in YAML.

styleName

optional

Additional style information for an editor property definition item applied to the element when the form is rendered. The value can be a CSS class or a list of CSS classes separated by white spaces.

The style name will be rendered as an HTML class name, which can be used in a CSS definition. The class name is added to the field by calling the Vaadin method addStyleName.

The referenced class can be defined in:

Form validation of multiple values

To validate that jcrMultiValueField has only unique values, you can create UniqueValuesMultiFormView as an implementation class that extends MultiFormView.

public class UniqueValuesMultiFormView<T> extends MultiFormView<T> {

    @Inject
    public UniqueValuesMultiFormView(MultiFormDefinition<T> definition, LocaleContext localeContext, Datasource<T> datasource) {
        super(definition, localeContext, datasource);
    }

    @Override
    public List<BinderValidationStatus<?>> validate() {
        final List<BinderValidationStatus<?>> validate = super.validate();
        if (validate.stream().allMatch(BinderValidationStatus::isOk)) {
            List<String> valuesStringList = validate.stream()
                    .map(v -> v.getBinder().getFields().findFirst().get().getValue()) // could be any data type other than string
                    .map(String::valueOf)
                    .collect(Collectors.toList());
            if (new HashSet<>(valuesStringList).size() != valuesStringList.size()) {
                final Binder.Binding<?, ?> binding = validate.stream()
                        .flatMap(binderValidationStatus -> binderValidationStatus.getFieldValidationStatuses().stream())
                        .map(BindingValidationStatus::getBinding)
                        .findFirst()
                        .orElse(null);
                final BindingValidationStatus<?> validationStatus = new BindingValidationStatus<>(Result.error("All values has to be unique"), binding);
                binding.getValidationStatusHandler().statusChange(validationStatus);
                validate.add(new BinderValidationStatus<>(null, Collections.singletonList(validationStatus), new ArrayList<>()));
            }
        }
        return validate;
    }
}
uniqueValues:
  $type: jcrMultiValueField
  implementationClass: info.magnolia.ui.editor.UniqueValuesMultiFormView
  field:
    $type: textField
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules