Multi field

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

JcrMultiValueFieldDefinition: allows you to enter multiple values of a single type to be stored as an array in a single JCR property (jcrMultiValueField).
JcrMultiFieldDefinition: allows you to create multiple JCR fields (jcrMultiField).
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.JcrMultiFieldDefinition
info.magnolia.rest.ui.field.JsonMultiFieldDefinition

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

Example definitions

JCR multi-value field

assignedSegments:
  $type: jcrMultiValueField
  field:
    $type: comboBoxField
    converterClass: info.magnolia.ui.editor.converter.JcrNodeToWorkspaceAndIdConverter
    datasource:
      $type: jcrDatasource
      workspace: segments
      describeByProperty: jcrName
      allowedNodeTypes:
        - mgnl:segment

JCR multi field

multi:
  label: Addresses
  i18n: true
  $type: jcrMultiField
  field:
    $type: compositeField
    properties:
      street:
        label: Street name
        $type: textField
      city:
        label: City name
        i18n: true
        $type: textField
      zip:
        label: ZIP code
        $type: textField

JSON multi field

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

Field properties

Field-specific 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.

entryResolution

optional, default is

ByMultiValueProperties for JcrMultiValueFieldDefinition
MultiFieldEntryResolution for JcrMultiFieldDefinition
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 is necessary in certain compatibility configurations (for example, when porting configurations that use Magnolia 5 UI multi field transformers). In problematic configurations, strict will fall back to the required value and that change will appear in the Definitions app.

orderHandler

optional, default is

MultiValuePropertyOrderHandler for JcrMultiValueFieldDefinition
DefaultJcrNodeOrderHandler for JcrMultiFieldDefinition

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

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

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.

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.

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.

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: