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.
Property | Description | Default value | Valid values |
---|---|---|---|
propertyBuilder | Concrete property Type and Handler definition. Optional. | ||
propertyHandler | Implementation class of PropertyHandler set to the propertyType used to set and get values in certain format. | ||
propertyType | Implementation class of CustomPropertyType set as Field PropertyDatasource . |
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 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 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:
Node name | Value |
---|---|
compositesimpleText | some text value |
compositesimpleDate | 2006-05-01T21:47:58.230+02:00 |
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:
Node name | Value |
---|---|
switchable | text (last tab selected) |
switchablesimpleText | some text value |
switchablesimpleDate | 2006-05-01T21:47:58.230+02:00 |
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:
Node name | Value |
---|---|
formNode |
|
simpleText | Simple English Text |
simpleText_de | Einfache deutsche Text |
multiValueText | English1,English2,English3 |
multiValueText_de | Deutsche1,Deutsche2 |
If you want to implement your own implementation of PropertyHandler
that support i18n, your implementation will need to:
- return
true
forPropertyHandler.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 whenproperty.getValue()
andproperty.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.
- 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
) - If the property
defaultValue
is defined in the field definition, this value will be converted to the appropriatetype
and assigned to the newly createdproperty
.
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'
Node name | Value |
---|---|
simpleText | Simple English Text |
simpleText_de | Einfache deutsche Text |
simpleText_fr | Simple text en francais |
OptionGroupPropertyHandler
TextCodePropertyHandler
TwinSelectPropertyHandler
CompositeHandler
MultiHandler
Limitation