Page History

...

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 read and write a value or values from a property and link it linked to a field. This is us full for complex fields like MultiField 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 :

• is set by the FieldBuilder based on the passed Item .
• has a name and a value.
  • name of the property is generally the name used to store the property 
  • value contains the user input.

In other words a field has a property, this property has a value.
For example a TextField named 'text' has a Property bound to the Item  Property 'text'.

The field property is normally simply linked to an Item property. Let's take a simple example. Assume that we have a Form displaying five fields. The following schema display the Jcr representation (1), his equivalent Item representation (2) (used in Magnolia UI and also to build the form) and the form view (3).

A form is build by the form builder using the Item (2). Each individual form field are build by the field builder. This builder used the field definition (that contains the field class, name,...) and the related item property to create an individual field.
In the previous example, (2.1) the field definition says that we have to create a field of type Text that has a value coming from a property called 'firstName'. The field builder, request from the Item (2) the property 'firstName'. It create a text field, a new property set as property datasource of the field, and associate the value of (2.1) to this property datasource (3.1).

The transformation dome between (1) and (2) is performed by the Actions (Open Dialog action and Save Dialog action). All changes done in the item (2) will be propagated to the Jcr structure once a user click to the save button (adding/removing/changing a property, or adding a sub item, ....)

Until Magnolia 5.1, the transformation between (2) and (3) was a 1:1 translation, meaning that the individual fields where directly accessing the Item. Now Magnolia 5.1 introduce a new layer between (2) and (3) allowing to perform complexer mapping. This layer is called Transformer.

  MockupAlignmentLeftNameitem

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,...)

...