Magnolia 6 UI ports of 5 UI field transformer classes

Magnolia 5 UI field transformer classes no longer exist in the Magnolia 6 UI framework. The transformer functionality is now distributed among different components. The following is a summary of what the components do:

  • Modify the target property name by appending a locale suffix or by prepending a field prefix. This is done by concrete PropertySet implementations (JcrItemPropertySet) and/or by PropertyNameDecorator.

  • Resolve an item data source of complex fields, a functionality usually covered by item providers.

  • Manage item data sources of multi-value field entries. This is handled by MultiFormView.EntryResolution, which resolves the children and binds each of them to the item provider strategy.

Replacements for transformers

Default classes

info.magnolia.ui.form.field.transformer.* Magnolia 6 UI

basic.BasicTransformer

Not needed. Its functions are obsolete; some are taken over by Vaadin PropertySet.

composite.CompositeTransformer

Use info.magnolia.ui.editor.CurrentItemProvider and set CompositeFieldDefinition#propertyNameDecorator to info.magnolia.ui.field.PrefixNameDecorator.

composite.SwitchableTransformer

Use info.magnolia.ui.editor.CurrentItemProvider and set:

  • ConfiguredSwitchableFieldDefinition#propertyNameDecorator to info.magnolia.ui.field.PrefixNameDecorator

  • name for ConfiguredSwitchableFieldDefinition#field to the same name used for the switchable field itself

Other classes

info.magnolia.ui.form.field.transformer.* Magnolia 6 UI

composite.DelegatingCompositeFieldTransformer

Use info.magnolia.ui.editor.CurrentItemProvider.

composite.NoOpCompositeTransformer

Not needed.

multi.DelegatingMultiValueFieldTransformer

Use info.magnolia.ui.editor.CurrentItemProvider and set entryResolution#strict to true.

multi.DelegatingMultiValueSubnodeTransformer

Use info.magnolia.ui.editor.JcrChildNodeProvider and set:

  • The now deprecated itemProvider#supportI18N to false

  • entryResolution#class to info.magnolia.ui.editor.MultiFieldEntryResolution$Definition

  • entryResolution#propertyNameDecorator to info.magnolia.ui.field.AlwaysEmptyPrefixNameDecorator

  • entryResolution#strict to true

multi.MultiValueChildNodeTransformer

Use info.magnolia.ui.field.JcrMultiValueFieldDefinition and set itemProvider#class to the now deprecated info.magnolia.ui.editor.MultiValueAsMultipleProperties$Definition.

multi.MultiValueChildrenNodeTransformer

Use info.magnolia.ui.editor.CurrentItemProvider and set:

  • entryResolution#class to the now deprecated info.magnolia.ui.editor.ByLexicographicallyIndexedChildNodes$Definition

  • entryResolution#propertyNameDecorator to info.magnolia.ui.field.AlwaysEmptyPrefixNameDecorator

  • entryResolution#strict to true

  • orderHandler#class to the now deprecated info.magnolia.ui.editor.LexicographicallyIndexedJcrNodeOrderHandler$Definition

Example definition
multiName:
  $type: jcrMultiField
  itemProvider:
    $type: currentItemProvider
  entryResolution:
    class: info.magnolia.ui.editor.ByLexicographicallyIndexedChildNodes$Definition
    propertyNameDecorator: info.magnolia.ui.field.AlwaysEmptyPrefixNameDecorator
    strict: true
  orderHandler:
    class: info.magnolia.ui.editor.LexicographicallyIndexedJcrNodeOrderHandler$Definition
  field:
    name: multiName # Name of the property where the value is stored within the multi node
    $type: textField

multi.MultiValueJSONTransformer

Deprecated, no automatic conversion.

multi.MultiValueSubChildrenNodePropertiesTransformer

Use info.magnolia.ui.editor.JcrChildNodeProvider and set:

  • The now deprecated itemProvider#supportI18N to false

  • entryResolution#class to the now deprecated info.magnolia.ui.editor.ByLexicographicallyIndexedChildNodes$Definition

  • entryResolution#strict to true

  • orderHandler#class to the now deprecated info.magnolia.ui.editor.LexicographicallyIndexedJcrNodeOrderHandler$Definition

multi.MultiValueSubChildrenNodeTransformer

Use info.magnolia.ui.field.JcrMultiFieldDefinition and set:

  • JcrMultiFieldDefinition#field to $type: compositeField

  • CompositeFieldDefinition#properties to a single field that shares the same name with the JCR multi field

Example definition
relatedUUID:
  $type: jcrMultiField
  field:
    $type: compositeField
    properties:
      - name: relatedUUID
        $type: linkField
        datasource: *categoryDatasource

Personalization transformers

Transformers with personalization-related functions still use the Magnolia 5 UI framework (magnolia-personalization-compatibility).

When using such a personalization converterClass in your YAML definition, the rule field is implicitly wrapped inside MultiField in Magnolia 6.2.x. Complete examples for creating custom traits with complex fields are given here.

info.magnolia.personalization.* Description

cookie.CookieFieldTransformer

Custom transformer for cookie traits.

ui.SimpleTraitValueTransformer

Now functions as the default trait transformer.

visitor.transformer.VisitorTraitListToSetTransformer

Still exists, but is no longer needed.

Transforming simple values into complex structures

To transform a simple value:

myDialog.yaml
form:
  properties:
    simple:
      $type: damLinkField

into a complex structure in Magnolia 6 UI:

website.myPage.myArea.myComponent.yaml
myComponent:
  assetLink: jcr:uuid
  assetName: myImage.jpg

you can create CompositeAssetLinkView as an implementation class that extends FormView:

public class CompositeAssetLinkView<T> extends FormView<Node> {

    @Inject
    public CompositeAssetLinkView(FormDefinition<Node> formDefinition, LocaleContext localeContext) {
        super(formDefinition, localeContext);
    }

    @Override
    public void write(Node node) {
        super.write(node);
        getPropertyValue("assetLink")
                .map(Asset::getName)
                .ifPresent(name -> node.setProperty("assetName", name));
    }
}

In Magnolia 6 UI, you have to be more explicit about the structure in the dialog configuration:

composite:
  $type: compositeField
  implementationClass: my.package.CompositeAssetLinkView
  itemProvider:
    $type: jcrChildNodeProvider # creating a `composite` node to store the link
  properties:
    assetLink:
      $type: damLinkField

Example definitions

The following configurations in both frameworks will produce the same results.

  • Magnolia 5 UI

  • Magnolia 6 UI

form:
  tabs:
    - name: tabSwitch
      fields:
        - name: switchable
          fieldType: switchable
          options:
            - name: text
              value: text
            - name: richText
              value: richText
          fields:
            - name: text
              fieldType: text
            - name: richText
              fieldType: richText

    - name: tabMultiBasic
      fields:
        - name: multitext
          fieldType: multiValue
          transformerClass: info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueFieldTransformer
          field:
            name: text
            fieldType: text

    - name: tabMultiDeleg
      fields:
        - name: items
          fieldType: multiValue
          transformerClass: info.magnolia.ui.form.field.transformer.multi.DelegatingMultiValueSubnodeTransformer
          field:
            name: itemComposite
            fieldType: composite
            transformerClass: info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer
            fields:
              - name: text
                fieldType: text
              - name: link
                fieldType: text

    - name: multiValueChild
      # i18n: true
      fieldType: multiValue
      field:
        name: text
        fieldType: text
      transformerClass: info.magnolia.ui.form.field.transformer.multi.MultiValueChildNodeTransformer

    - name: tabMultiLex
      fields:
        - name: itemsLex
          fieldType: multiValue
          transformerClass: info.magnolia.ui.form.field.transformer.multi.MultiValueSubChildrenNodePropertiesTransformer
          field:
            name: itemComposite
            fieldType: composite
            transformerClass: info.magnolia.ui.form.field.transformer.composite.NoOpCompositeTransformer
            fields:
              - name: text
                fieldType: text
              - name: link
                fieldType: text
form:
  properties:
    switchable:
      $type: switchableField
      field:
        name: switchable
        $type: radioButtonGroupField
        datasource:
          $type: optionListDatasource
          options:
            - name: text
              value: text
            - name: richText
              value: richText
      itemProvider:
        $type: currentItemProvider
      propertyNameDecorator: info.magnolia.ui.field.PrefixNameDecorator
      forms:
        - name: text
          properties:
            text:
              $type: textField
        - name: richText
          properties:
            richText:
              $type: richTextField

    multitext:
      $type: jcrMultiField
      itemProvider:
        $type: currentItemProvider
      entryResolution:
        class: info.magnolia.ui.editor.MultiFieldEntryResolution$Definition
        strict: true
      field:
        name: text
        $type: textField

    items:
      $type: jcrMultiField
      itemProvider:
        $type: jcrChildNodeProvider
        supportI18N: false
      entryResolution:
        class: info.magnolia.ui.editor.MultiFieldEntryResolution$Definition
        propertyNameDecorator: info.magnolia.ui.field.AlwaysEmptyPrefixNameDecorator
        strict: true
      field:
        $type: compositeField
        properties:
          text:
            $type: textField
          link:
            $type: textField

    multiValueChild:
      $type: jcrMultiValueField
      # i18n: true
      itemProvider:
        class: info.magnolia.ui.editor.MultiValueAsMultipleProperties$Definition
      field:
        $type: textField

    itemsLex:
      $type: jcrMultiField
      itemProvider:
        $type: jcrChildNodeProvider
        supportI18N: false
      entryResolution:
        class: info.magnolia.ui.editor.ByLexicographicallyIndexedChildNodes$Definition
        strict: true
      orderHandler:
        class: info.magnolia.ui.editor.LexicographicallyIndexedJcrNodeOrderHandler$Definition
      field:
        $type: compositeField
        properties:
          text:
            $type: textField
          link:
            $type: textField
Feedback