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 initialize a property and link it to a field. This is us full for complex fields like MultiField CompositeField that needs more than one property bound to them.

Basic Concept

A Field  is linked to a Property  used to store the field value. This Property is set by the FieldBuilder based on the passed Item .
For example a TextField named 'text' has a Property bound to the Item  Property 'text'.

Now for a MultiField, the related Property can no more be a simple Property but rather a ListProperty . This ListProperty will be populated with the individual field Property values.
This is the first information needed in order to handle complex fields: The PropertType (Basic, List, Composite,...)

The way values of the ListProperty is set and retrieve from the related Item is also something we would like to configure. For example I may want to have a MultiField composed of DateField stored in a single multi value.
The same field may be used in another place but the values have to be stored as sub item (nodes) elements.
PropertyHandler is the second information needed. PropertyHandler handle the way property element are retrieve and set to an Item.

Configuration

These configurations are done in the common fields Properties.

Default behavior

Basic Property

By default BasicProperty and BasicPropertyHandler are used.

The field is created based on the related form Item. BasicPropertyHandler 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 Property

Composite Property (CompositeProperty) are used by the following fields:

• CompositeField
• SwitchableField

CompositeField

This field is by default bound with  SimplePropertyCompositeHandler . This handler 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

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:

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:

If you want to implement your own implementation of PropertyHandler that support i18n, your implementation will need to:

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

Implemented

Implemented Property

Hierarchy

BaseProperty

BaseProperty implements the following basic mechanism:

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

Implemented Handlers

Limitation

How to