Page History
Table of Contents |
---|
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 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 passedItem
. - 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.
Mockup | ||||
---|---|---|---|---|
|
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).
For example a TextField
named 'text' has a Property
bound to the Item
Property
'text'.
Mockup | ||
---|---|---|
|
Mockup | ||
---|---|---|
|
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.
Assume that we have a new requirement regarding our form example: The Item (2) stay the same, but the form should only display one text field containing the full name (first and last name) . This is now possible by defining a TransformerClass
property on the Field Definition:
Mockup | ||
---|---|---|
|
In this case, the field builder will create a TransformedProperty
as field property datasource. This TransformedProperty
delegate to the Transformer
the get and set value field calls.
Another good example for illustrating the Transformer
behavior is the MultiValueField.
The the related field 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. PropertHandler
is the second information needed. PropertHandler
handle the way property element are retrieve and set to an Item
.
Configuration
Default behavior
Implemented
Implemented Property
Implemented Handlers
Limitation
a complex property containing several values. This property is a PropertysetItemt
(a Property
containing several Property
).
Mockup | ||||
---|---|---|---|---|
|
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 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, ...
Configuration
This configurations are done in the common fields Properties.
Property | Description | Default value | Valid values |
---|---|---|---|
transformerClass | Concrete implementation of |
Default behavior
Basic Field
By default, basic fields (Textm Date, Checkbox,...) uses BasicTransformer
.
The field is created based on the related form Item
. BasicTransformer
will:
- Retrieve the
Item.property
if thisproperty
already exist on theItem
.property
is search based on the Field name defined as name property on the field definition. - Create the
Item.property
if thisproperty
do not yet exist on theItem
.property
is created based on the following field definition:type
:property
will get the desiredtype
defaultValue
: if define, the string representation of the default field value is converted to a newtyped value.
Composite Fields
Composite Transformer
(CompositeTransformer SwitchableTransformer
) are used by the following fields:
CompositeField
SwitchableField
CompositeField
CompositeField
This field use by default the
. This CompositeTransformer
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:
Advanced Tables - Table Plus | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
SwitchableField
SwitchableField
This field used by default the
. This SwitchableTransformer
Transformer
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:
Advanced Tables - Table Plus | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||
|
Multi-Value Field
Multi-Value Transformer
are used by the following field:
MultiField
MultiField
This field is by default bound with MultiValueTransformer
. This Transformer
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 Transformer
implementation support the i18n definition.
If for example you have two language defined ('en', 'de') with 'en' set as default language:
Advanced Tables - Table Plus | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||
|
If you want to create your own implementation of Transformer
that support i18n, your implementation will need to:
- return
true
forTransformer
.hasI18NSupport() - implement a compatible Magnolia i18n logic.
Default Value
ConfiguredFieldDefinition.defaultValue
contains the String representation of the default value.
The default value is only showed the first time the related form is displayed.
This behavior is only supported by basic field .
Implemented
Property
A field needs to be linked to a property as data source. The value of the property is used to store the value entered/selected by the user on the field.
In Magnolia 5.1, every field are bound to a property that support Transformer
called TransformedProperty
.
This property is initialized with the configured Transformer
and set to the field as datasource by the FieldFactory
.
Mockup | ||
---|---|---|
|
A ConfiguredField is linked to a TransformedProperty<T>
.
TransformedProperty<T>
is initialized with aTransformer
.
TransformedProperty<T>
extend ObjectProperty<T>
.
- value T :
Transformer.readFromItem()
- T :
Transformer.getType()
The Transformer
has the responsibility to retrieve the initial value and to set the property class type.
TransformedProperty<T>
may be of any type. For a TextField configured to handle Long (ConfiguredFieldDefinition.type = Long
), the <T>
will be of type Long
.
For complexer Field (Multi, Composite) the <T>
is of type PropertysetItem
. This let the complex field easily handle multi property.
Implemented Transformer
BasicTransformer
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.
- As
property
are typed, the createdproperty
will be of the type defined by the property namedtype
coming from the field definition. (type=Date
the property will be aDate Object
). Default type isString
- If the property
defaultValue
is defined in the field definition, this value will be converted to the appropriatetype
and assigned to the newly createdproperty
. Otherwise the property will have anull
value.
If the related field support i18n
a language suffix is added to the property
name:
For example, a field is called 'simpleText' and has support for 'en, de, fr'. Default language is 'en'
Advanced Tables - Table Plus | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||
|
CompositeTransformer
In addition to the CompositeField
and SwitchableField
default Transformer
, we provide an additional Transformer
:
NoOpCompositeTransformer
NoOpCompositeTransformer
is useful if you want to combine a Multi filed storing individual field value into sub nodes with composite field as Multi field component.
Mockup | ||
---|---|---|
|
In this case, the Multi field
will read/write the Item structure and pass a properties as Transformer
PropertysetItem
to the NoOpCompositeTransformer
. This
just act as a property container.Transformer
MultiTransformer
MultiValueTransformer
This is the default
set for Multi value fields. The fields values are stored in a Transformer
. This LinkedList
<T>
is then automatically convert to a JCR multi-value-property once it is persisted. LinkedList
<T>
This will only work for simple fields like text/date/radio...
MultiValueJSONTransformer
storing the fields values as a Transformer
String
with ',' as separator.
This will only work for simple fields like text/date/radio... and values are stored as String
.
MultiValueChildrenNodeTransformer
storing the fields values in sub item property: (Equivalent Jcr Structure of the form Item)Transformer
Advanced Tables - Table Plus | |||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||
|
MultiValueSubChildrenNodePropertiesTransformer
storing each field values into a sub Item. Equivalent to Transformer
MultiValueChildrenNodeTransformer
but this
is able to handle multiple values. Based on the previous Transformer
NoOpCompositeTransformer
example:
Advanced Tables - Table Plus | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
MultiValueSubChildrenNodeTransformer
creating first a child node (named as the multi field) and storing the fields values in sub node property (equivalent to Transformer
MultiValueChildrenNodeTransformer
) :
Advanced Tables - Table Plus | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||
|
...