Page tree
Skip to end of metadata
Go to start of metadata

The value of a form field is typically stored in a single property. For example, text field firstName stores its value in a property firstName. This page explains how to read and write values in different ways using property transformers.

Property transformer is a layer that translates the stored values into something the user can edit and vice versa. This is useful for complex fields such as multivalue and composite where more than one property is needed to store the entire field value. The transformer stands between the form and the JCR Item  representation, which means that individual form fields are not directly accessed by the Item.

Transformer classes

Property transformer classes define how field values are stored in the repository. Each field has a default transformer class. You don't need to define a class unless you want to change the default. To change the class, add a transformerClass property to your field definition and set its value to a fully-qualified transformer class name.

Default transformer classes:

  • For simple fields such as Text and Date: info.magnolia.ui.form.field.transformer.basic.BasicTransformer
  • For composite fields: info.magnolia.ui.form.field.transformer.composite.CompositeTransformer
  • For switchable fields: info.magnolia.ui.form.field.transformer.composite.SwitchableTransformer

  • For multivalue field: info.magnolia.ui.form.field.transformer.multi.MultiValueTransformer 

Other available transformer classes:

  • info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer
  • info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueFieldTransformer
  • info.magnolia.ui.form.field.transformer.composite.NoOpCompositeTransformer
  • info.magnolia.ui.form.field.transformer.multi.MultiValueJSONTransformer
  • info.magnolia.ui.form.field.transformer.multi.MultiValueChildrenNodeTransformer
  • info.magnolia.ui.form.field.transformer.multi.MultiValueChildNodeTransformer
  • info.magnolia.ui.form.field.transformer.multi.MultiValueSubChildrenNodeTransformer

Best practice

The delegating transformers classes should be your first choice since they are the most versatile. If you can, use DelegatingCompositeFieldTransformer or DelegatingMultiValueFieldTransformer rather than the other available classes.

BasicTransformer

BasicTransformer  stores the field value in a single property. The property has the same name as the field definition node. You can provide a different name with a name property in the field definition. This transformer creates a new property if the property does not yet exist.

Transformer class: info.magnolia.ui.form.field.transformer.basic.BasicTransformer

Here is an example dialog with text fields:

The BasicTransformer stores the field values like this in the JCR repository:

Node name

Value

 mmonroe


 firstName

Marilyn

 lastName

Monroe

Setting a property type

All JCR properties have a type. The basic transformer uses the String type for all properties by default. You can use a different type by adding a type property to the field definition .

Example field definition with type is set to Date. Magnolia will store the field value as a date object.

form:
  tabs:
    - name: tabText
      label: Text
      fields:
        - name: title
          class: info.magnolia.ui.form.field.definition.TextFieldDefinition
          label: Event
          type: Date
Node nameValue

 form


 tabs


 tabEvent


 fields


 eventDate


   class

info.magnolia.ui.form.field.definition.TextFieldDefinition

   type

Date


If you define a defaultValue, that value will be converted to the desired type too. If you don't define a default value, the property will have a null start value.

i18n support

If a field supports translation, an i18n language suffix is added to the property name.

For example, a simpleText field that supports translation has suffixes en, de and fr. In this example, English is the default (fallback) language so the en suffix is not used.

Node nameValue
 simpleText
Simple English text
 simpleText_de
Einfache deutsche Text
 simpleText_fr
Simple text en français

Composite transformers

CompositeTransformer

CompositeTransformer stores each child field value as a single property. Composite fields which consist of multiple child fields use CompositeTransformer by default.

Transformer class: info.magnolia.ui.form.field.transformer.composite.CompositeTransformer  

This composite event field consists of a text field and a date field.

CompositeTransformer stores the values like this:

Node nameValue
 eventdate
2015-10-31T20:30:00.00+02:00
 eventtitle
Halloween

DelegatingCompositeFieldTransformer

DelegatingCompositeFieldTransformer stores each child field value as a single property. The difference between this transformer and the other composite transformers is that it uses the child field name as the storage property  name.

Transformer class:  info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer 

Example composite field definition containing a text field and date field that uses DelegatingCompositeFieldTransformer :

form:
  tabs:
    - name: tabEvent
      label: Event
      fields:
        - name: composite
          class: info.magnolia.ui.form.field.definition.CompositeFieldDefinition
          transformerClass:  info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer
          label: Event
          fields:
            - name: title
              class: info.magnolia.ui.form.field.definition.TextFieldDefinition
              label: Title
            - name: date
              class: info.magnolia.ui.form.field.definition.DateFieldDefinition
              label: Date
Node nameValue

 form


 tabs


 tabEvent


 fields


 composite


 fields


 title


 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 label

Title

 date


 class

info.magnolia.ui.form.field.definition.DateFieldDefinition

 label

Date

 class

info.magnolia.ui.form.field.definition.CompositeFieldDefinition

 label

Event

 transformerClass

info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer

CompositeTransformer would store values like this:

Node nameValue
 eventdate
2015-10-31T20:30:00.00+02:00
 eventtitle
Halloween

DelegatingCompositeFieldTransformer stores values like this:

Node nameValue
 date
2015-10-31T20:30:00.00+02:00
 title
Halloween

When i18n=true this transformer delegates localization to the child fields. (warning) Add the i18n=true property in the parent field AND in any child fields. The property needs to be added to both levels.

Node nameValue
 date
Oct 31, 2015 12:00:00 AM
 date_de
Nov 1, 2015 12:00:00 AM
 title
Halloween
 title_de
Allerheiligen

NoOpCompositeTransformer

Use NoOpCompositeTransformer  for a  composite field that is inside a  multivalue  parent field. "NoOp" means no operation – NoOpCompositeTransformer  does not perform any  writeToItem  or  readFromItem  operations, it just acts as a property container. The transformer of the parent multivalue field does the reading and writing of the item structure to the repository. You can use any of the multivalue transformers below in the parent. The parent transformer passes the properties to the  NoOpCompositeTransformer  as a Vaadin  PropertysetItem .

Transformer class: info.magnolia.ui.form.field.transformer.composite.NoOpCompositeTransformer

SwitchableTransformer

Switchable fields use SwitchableTransformer  by default. This transformer stores the selected field value as a single suffixed property.

Transformer class: info.magnolia.ui.form.field.transformer.composite.SwitchableTransformer

Here is a switchable text editor field. It consists of alternative text and rich text fields.

SwitchableTransformer stores the values like this. The parent option field has one property (editor) and each child field has its own property (editorplainText, editorrichText). The name of the parent field is appended before the child property name.

Node nameValue

 editor

richText

 editorplainText

Boo! Halloween is around the corner.

 editorrichText

<p><strong>Boo!</strong></p> Halloween is around the corner.

Note that Magnolia discards the values for unselected options when changes are saved. In the example above, only the value entered for  editorplainText or editorRichtext is stored.

Multivalue transformers

Use multivalue transformers with multivalue fields. They are capable of storing multiple values, even in cases where the multivalue parent field contains a composite field.

(warning) Use DelegatingMultiValueTransformer when nesting more than two levels of fields. The other multivalue transformers can handle only two levels.

MultiValueTransformer

MultiValueTransformer  is the default transformer for  multivalue  fields. The transformer stores field values in a LinkedList<T> collection. The linked list is then automatically converted to a JCR multivalue property when persisted to the JCR.  In the repository it looks like a typical array: comma-separated and enclosed in square brackets.

(warning) Use this transformer only when the multivalue parent contains a single field such as text, date and checkbox.

Transformer class: info.magnolia.ui.form.field.transformer.multi.MultiValueTransformer

Here is a multivalue field that consists of a text field.

MultiValueTransformer stores the values as a JCR multivalue property that looks like a typical array.

Node nameValue

 shoppingList

 [milk, cookies, pizza]

MultiValueJSONTransformer

MultiValueJSONTransformer stores the values as a comma-separated list of Strings.

(warning) Use this transformer only for simple fields such as text, date and checkbox.

Transformer class: info.magnolia.ui.form.field.transformer.multi.MultiValueJSONTransformer

Here is a multivalue field that consists of a text field.

MultiValueJSONTransformer stores the values like this:

Node nameValue

 shoppingList

 milk, cookies, pizza

DelegatingMultiValueTransformer

DelegatingMultiValueFieldTransformer  delegates the responsibility of storing field values to the parent field. In doing so, this transformer creates a list of Item objects. The child field uses the Item to create and retrieve its own properties. Delegation makes it possible to nest unlimited levels of fields. For example, create a composite field which contains a multivalue field which contains a switchable field and so on.

(warning) Use DelegatingMultiValueTransformer when nesting more than two levels of fields. The other multivalue transformers can only handle two levels max.

Transformer class: info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueFieldTransformer

Here is a multivalue field that consists of a text field.

This is how the nested fields are defined when using DelegatingMultiValueTransformer:

form:
  tabs:
    - name: tabMain
      label: Main
      fields:
        - name: shoppingList
          class: info.magnolia.ui.form.field.definition.MultiValueFieldDefinition
          label: Shopping list
          transformerClass: info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueFieldTransformer
          field:
            class: info.magnolia.ui.form.field.definition.TextFieldDefinition
            name: shoppingitem
Node nameValue

 form


 tabs


 tabMain


 fields


 shoppingList


 field


 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 name

shoppingItem

 class

info.magnolia.ui.form.field.definition.MultiValueFieldDefinition

 label

Shopping List

 transformerClass

info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueFieldTransformer

DelegatingMultiValueFieldTransformer stores the values like this:

Node nameValue

 shoppingList0


 shoppingItem

milk

 shoppingList1


 shoppingItem

cookies

 shoppingList2


 shoppingItem

pizza

When i18n=true this transformer creates nodes with a locale suffix. The translated values are stored in properties under the nodes. (warning) Add the i18n=true property in the parent field AND in any child fields. The property needs to be added to both levels.

Node nameValue

 shoppingList0


 shoppingItem

milk

 shoppingList1


 shoppingItem

cookies

 shoppingList2


 shoppingItem

pizza

 shoppingList0_de


 shoppingItem

Milch

 shoppingList1_de


 shoppingItem

Kekse

 shoppingList2_de


 shoppingItem

Pizza

MultiValueChildrenNodeTransformer

(warning) Use the more versatile DelegatingMultiValueTransformer instead of this transformer if you can.

MultiValueChildrenNodeTransformer

MultiValueChildrenNodeTransformer doesn't create a node for the multivalue parent field at all. It creates nodes for the child fields and stores their values as properties. This structure is equivalent to the JCR structure of the form Item.

Transformer class: info.magnolia.ui.form.field.transformer.multi.MultiValueChildrenNodeTransformer

Here is a multivalue field that consists of a text field.

MultiValueChildrenNodeTransformer stores the values like this:

Node nameValue

 00


 shoppingList

milk

 01


 shoppingList

cookies

 02


 shoppingList

pizza

MultiValueSubChildNodeTransformer

(warning) Use the more versatile DelegatingMultiValueTransformer instead of this transformer if you can.

MultiValueSubChildrenNodeTransformer  first creates a node for the parent multivalue field. It then stores the child fields as numbered properties.

Transformer class: info.magnolia.ui.form.field.transformer.multi.MultiValueChildNodeTransformer

Here is a multivalue field that consists of a text field.

MultiValueSubChildNodeTransformer stores values like this:

Node nameValue

 shoppingList


 0

milk

 1

cookies

 2

pizza

MultiValueSubChildrenNodeTransformer

(warning) Use the more versatile DelegatingMultiValueTransformer instead of this transformer if you can.

MultiValueSubChildrenNodeTransformer  first creates a node for the parent multivalue field. It then stores the child fields as subnodes and their values as properties.

Transformer class: info.magnolia.ui.form.field.transformer.multi.MultiValueSubChildrenNodeTransformer

Here is a multivalue field that consists of a text field.

MultiValueSubChildrenNodeTransformer stores values like this:

Node nameValue

 shoppingList


 milk


 shoppingList

milk

 cookies


 shoppingList

cookies

 pizza


 shoppingList

pizza

MultiValueSubChildrenNodePropertiesTransformer

(warning) Use the more versatile DelegatingMultiValueTransformer instead of this transformer if you can.

MultiValueSubChildrenNodePropertiesTransformer is equivalent to MultiValueChildrenNodeTransformer but it is able to handle a composite field as the child of the multivalue parent.

Transformer class: info.magnolia.ui.form.field.transformer.multi.MultiValueSubChildrenNodePropertiesTransformer

(warning) Define a no-op transformer for the composite child field. Since the parent multivalue field handles the read and write operations, set the composite field's transformerClass to info.magnolia.ui.form.field.transformer.composite.NoOpCompositeTransformer.

Here is a multivalue event field. Each event is a composite field that consists of a title and a date.

MultiValueSubChildrenNodePropertiesTransformer stores each composite field as an item (node) and the values of the child fields as properties. 

Node nameValue

 event


 00


 date

Oct 31, 2015 12:00:00 AM

 title

Halloween

 01


 date

Dec 31, 2015 12:00:00 AM

 title

New Year's Eve

 02


 date

Feb 8, 2016 12:00:00 AM

 title

Chinese New Year

Which transformer should I use?

  • I have a multi-value field with a simple field inside (e.g. text, single-select, date, link): all multi-value transformers may be used.
  • I have a multi-value field with a complex field inside (e.g. composite, switchable, multi-selection, or any other field with a custom transformerClass): only delegating transformers should be used (same goes for nested composite & switchable fields).

Combining delegating transformers

In this complex example we nest four levels of fields. To book a seat on a flight you enter a departure city, arrival city and select one or more seats depending on the number of passengers.

We need to use delegating field transformers since normal non-delegating transformers can only handle two nesting levels. Also, since we mix multivalue and composite fields we need to use both DelegatingMultiValueTransformer and the DelegatingCompositeFieldTransformer.

It is not possible to change the order of the fields by using the Delegating*Transformer classes. These classes only delegate to other independent transformer classes which do not know about each other. The new order of the fields would not be kept after saving the change.

Here's how transforming values are delegated:

  1. DelegatingMultiValueTransformer on multivalue field flights creates a new Item and passes it to composite field flight.
  2. The Item is passed to the composite child fields fromto and seats, in order to initialize their own properties and Items.
  3. Text fields from and to add their text properties to the Item.
  4. Nested composite field seats uses the Item to create a subitem and sends the subitem to its child field seat.

The values are stored in the JCR repository like this:

Node nameValue

 flights0


 seats0


 seat

15A

 seats1


 seat

15B

 from

Boston

 to

San Francisco

 flights1


 seats0


 seat

21E

 seats1


 seat

21F

 from

San Francisco

 to

Boston
  • No labels