Introduction

Magnolia 5.1 introduce a new way to handle properties bound to a dialog field. Until Magnolia 5.1 the only way to modify the default behavior (a field is bound to a simple property) was to override the FieldBuilder.getOrCreateProperty(..  method.
Now by configuration we have the possibility to define custom way to read and write a value or values from a property linked to a field. This is us full for complex fields like MultiValueField or CompositeField that needs more than one simple property bound to them.

Basic Concept

A Field  is linked to a Property  used to store the field value. This Property :

...

The previous mockup display a Date multi value field (3). This field is associated to a PropertysetItemt that contains the individual Date Property. This property delegate the read and write to a Transformer (1) This Transformer knows how to read and write the individual  Date Property from and to the related form item. In this example the Transformer is bound to an Item property of type list. This introduce another big advantage introduce by of the Transformer's. For the same field it is possible to define several read/write strategy:
Store the field values into a single array, or into sub items, ... 

REVIEW THE SECTION DOWN HERE

Configuration

These This configurations are done in the common fields Properties.

Default behavior

Basic

...

Transformer

By default BasicProperty and BasicPropertyHandler are default BasicTransformer is used.

The field is created based on the related form Item. BasicPropertyHandler BasicTransformer will:

• Retrieve the Item.property if this property already exist on the Item.
  property is search based on the Field name defined as name property on the field definition. 
• Create the Item.property if this property do not yet exist on the Item.
  property is created based on the following field definition:
  
  • type: property will get the desired type
  • defaultValue: if define, the string representation of the default field value is converted to a new typed value.

Composite

...

Transformer

Composite Property (CompositePropertyComposite Transformer (CompositeTransformer SwitchableTransformer) are used by the following fields:

• CompositeField
• SwitchableField

...

CompositeTransformer

This field is by default bound with  SimplePropertyCompositeHandler . This handler Transformer  will store each single field part of the CompositeField as single suffixed property.
Assume that your CompositeField is called 'composite' and contains two fields: a text field called 'simpleText' and a date field called 'simpleDate'. The  values will be stored as following:

SwitchableField

SwitchableTransformer

This Transformer  This field is by default bound with  SwitchableSimplePropertyCompositeHandler . This handler will store each single field part of the SwitchableField as single suffixed property.
Assume that your SwitchableField is called 'switchable' and contains two fields: a text field called 'simpleText' and a date field called 'simpleDate'. The  values will be stored as following:

REVIEW THE SECTION DOWN HERE

List Property

List Property (ListProperty) are used by the following field:

• MultiField

MultiField

This field is by default bound with  MultiValuesPropertyMultiHandler . This handler will store each single field part of the MultiField as a multiValue property (Basically a JCR multiValue property represented a a Typed List property).

i18n

All default implementation support the i18n definition.
If for example you have two language defined ('en', 'de') with 'en' set as default language:

...

• return true for PropertyHandler.hasI18NSupport() 
• implement a compatible Magnolia i18n logic.

Implemented

Implemented Property

Hierarchy

BaseProperty

...

• Handle i18n support.
• Delegate the configured handler the request  when property.getValue() and property.setValue() are called.

Implemented Handlers

BasicPropertyHandler

Overview

BasicPropertyHandler

The property linked to a field is retrieved and stored based on the Field's  property name defined in the field definition.
A new property is created in case id does not yet exist.

...

OptionGroupPropertyHandler

In case of an OptionGroup field is defined as multiselect, the selected values are stored as a JCR multi-value-property. This JCR multi-value-property is normally handled as a List, but the underlying Vaadin field is only working with Set . This handler simply convert  List to Set . 

TextCodePropertyHandler

Simple TextCode Handler that return an empty String instead of a null property value.

TwinSelectPropertyHandler

Like for the OptionGroup field, the underlying Vaadin Field need additional convertor between List to Set.

CompositeHandler

In addition to the CompositeField and SwitchableField default Handler, we provide two additional CompositeHandler:

SubNodeCompositeHandler

 SubNodeCompositeHandler  will store the  property values of the fields composing the composite field under the following format:

...

This Handler do not support i18n (in Magnolia 5.1).

NoOpCompositeHandler

NoOpCompositeHandler is useful if you want to combine a Multi filed storing individual field value into sub nodes with composite field as Multi field component.

...

In this case, the Multi field handler will create/read the node structure and pass a properties as PropertysetItem to the NoOpCompositeHandler. This handler just act as a property container.

MultiHandler

MultiValuesPropertyMultiHandler

This is the default Handler set for Multi fields. The fields values are stored in a JCR multi-value-property.
This will only work for simple fields like text/date/radio...

CommaSeparatedMultiHandler

Handler storing the fields values as a String with ',' as separator.
This will only work for simple fields like text/date/radio... and values are stored as String.

SubNodesMultiHandler

Handler storing the fields values in sub node property:

SubNodesMultiPropertysetItemHandler

Based on the previous NoOpCompositeHandlero example:

SubNodesMultiIdentifierHandler

Handler creating first a child node (named as the multi field) and storing the fields values in sub node property:

Limitation

How to

Open Issue

Default value handling

The field definition allows to define a default value as a String:

...