Composite field

CompositeFieldDefinition renders a complex field composed of one or more fields (compositeField). Use the field for objects that cannot be expressed as simple text strings or numbers such as:

Setting conditions for selecting the next step in a multistep form.
Assigning categories to a content item where the composite field consists of a category dropdown and a button for reordering categories.
Defining an image gallery using a media select field where the composite media field consists of a thumbnail and caption text.
Specifying an access control list for JCR workspaces where the composite ACL field consists of permission, scope and path.

There is also JsonCompositeFieldDefinition to be used in an app with its own JSON data source (jsonCompositeField).

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

info.magnolia.ui.field.CompositeFieldDefinition
info.magnolia.rest.ui.field.JsonCompositeFieldDefinition

If you work with the Magnolia 5 UI framework, see Composite field for Magnolia 5 UI instead. There is no corresponding 5 UI implementation for the JSON composite field.

Example definitions

Composite field
JSON composite field

composite:
  $type: compositeField
  label: Location
  itemProvider:
    $type: jcrChildNodeProvider
  properties:
    city:
      label: City
      $type: textField
    country:
      label: Country
      $type: textField

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. jsonCompositeField is designed to show field data from REST sources; you can’t add, edit, or delete a field entry.

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

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

Field properties

Field-specific properties

Property Description

Property	Description
`properties`	required List of editor property definition items (typically, a list of fields). All field types are supported. See List of fields for more information.
`idPropertyName`	optional (used only in JSON composite field) Defines a unique property name for a JSON node.
`layout`	optional, default is `info.magnolia.ui.framework.layout.StackedLayoutProducer` Defines the field layout. The value must be a subtype of `info.magnolia.ui.framework.layout.LayoutDefinition`. See Layout types for more information.

properties

required

List of editor property definition items (typically, a list of fields).

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

idPropertyName

optional (used only in JSON composite field)

Defines a unique property name for a JSON node.

layout

optional, default is info.magnolia.ui.framework.layout.StackedLayoutProducer

Defines the field layout. The value must be a subtype of info.magnolia.ui.framework.layout.LayoutDefinition.

See Layout types for more information.

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

optional, default is

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.

You can’t configure this property through YAML but it can be used in your Java code.

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:

Feedback

DX Core

Composite field

Example definitions

Field properties

Field-specific properties

Common complex field properties

Location

Main doc sections