Migrating the removePreviouslySelected property

Overview

This page provides steps to migrate form templates that use removePreviouslySelected=false in configurations of the Switchable field. The property is now UNSUPPORTED in Accessible forms in Magnolia 6.4. You might need to migrate especially in the following cases:

  • You need to avoid losing data of subforms from non-selected options, when using the Accessible forms.

  • You use custom templates that make use of this property.

Setting removePreviouslySelected=false forces forms to render as Vaadin instead.

It also triggers an UNSUPPORTED warning in the Definitions app.

Background

The removePreviouslySelected property of the Switchable field controls whether data from non-selected options is kept or removed. Setting it to false in Vaadin forms lets you store data in multiple options. This is possible in Vaadin form definitions in Magnolia 6.2, 6.3, and even in 6.4 Vaadin forms.

However, in Magnolia 6.4 Accessible form definitions, it’s no longer supported, to keep data consistent, reduce UI confusion, and reduce logic complexity.

Switchable field data persistence

How switchable field stores data

A Switchable field saves data in the JCR repository like this:

Click to expand or collapse

/content/mypage/
  switchableField/
    field: "selectedOption" (1)
    [option-specific properties] (2)
1 Stores the selected option.
2 Properties from the selected option’s form.

The field property tracks the current option. Properties or sub-nodes from that option’s form are stored under the switchableField node.

Example: Link switcher with two options

Imagine a Switchable field with two options:

  • Internal: Has a linkUuid property.

  • External: Has a url property.

Field definition

Click to expand or collapse

switchableField:
  $type: switchableField
  field:
    class: info.magnolia.ui.field.ComboBoxFieldDefinition
    datasource:
      $type: optionList
      options:
        - name: internal
          value: internal
          label: Internal Link
        - name: external
          value: external
          label: External Link
  forms:
    - name: internal
      properties:
        - name: linkUuid
          $type: pageLinkField
    - name: external
      properties:
        - name: url
          $type: textField

Data persistence with removePreviouslySelected=true (default/supported)

When you pick the "external" option and enter https://example.com:

Click to expand or collapse

/content/mypage/
  switchableField/
    field: "external"
    url: "https://example.com"

Switching to "internal" and selecting a page:

Click to expand or collapse

/content/mypage/
  switchableField/
    field: "internal"
    linkUuid: "uuid-of-selected-page"
    # url property is REMOVED

Data persistence with removePreviouslySelected=false (unsupported)

When you pick the "external" option and enter https://example.com:

Click to expand or collapse

/content/mypage/
  switchableField/
    field: "external"
    url: "https://example.com"

Switching to "internal" and selecting a page:

Click to expand or collapse

/content/mypage/
  switchableField/
    field: "internal"
    linkUuid: "uuid-of-selected-page"
    url: "https://example.com" (1)
1 PRESERVED (problematic!).

Why removePreviouslySelected=false is problematic

  • Keeping properties from multiple options creates messy data states.

  • Users might see old, outdated data from previous options.

  • Validation rules from different options can clash.

  • Unused data piles up over time.

  • Business logic gets tricky handling mixed states.

Migration strategy: using compositeField

The best approach is to accept that data for non-selected options is dropped with removePreviouslySelected=true. This keeps the Switchable field simple, as intended.

If you need to keep data from all options, swap Switchable fields with removePreviouslySelected=false for a CompositeField.

This approach needs no data migration—existing content works right away.

  • It lets you view and edit all properties from subforms of all options in a single flat composite subform.

  • It keeps the same JCR storage structure.

  • You only need to update the form definition.

Migration example

Original use in a switchableField (unsupported)

Click to expand or collapse

linkSwitcher:
  $type: swtichableField
  removePreviouslySelected: false  # UNSUPPORTED!
  field:
    class: info.magnolia.ui.field.ComboBoxFieldDefinition
    datasource:
      class: info.magnolia.ui.datasource.optionlist.ConfiguredOptionListDefinition
      options:
        - name: internal
          value: internal
          label: Internal Link
        - name: external
          value: external
          label: External Link
  forms:
    - name: internal
      properties:
        - name: linkUuid
          class: info.magnolia.ui.field.LinkFieldDefinition
    - name: external
      properties:
        - name: url
          class: info.magnolia.ui.field.TextFieldDefinition

Migrated compositeField (supported)

Click to expand or collapse

linkSwitcher:  # Keep the SAME field name
  $type: compositeField
  properties:
    - name: field  # Keep the SAME switcher property name
      $type: comboBoxField
      label: "Link Type"
      datasource:
        $type: optionList
        options:
          - name: internal
            value: internal
            label: Internal Link
          - name: external
            value: external
            label: External Link
    - name: linkUuid  # From internal option
      $type: pageLinkField
      label: "Internal Page"
    - name: url  # From external option
      $type: textField
      label: "External URL"

Resulting data structure

The JCR structure stays the same, so existing content works instantly:

Click to expand or collapse

/content/mypage/
  linkSwitcher/
    field: "external" (1)
    linkUuid: "uuid-of-some-page" (2)
    url: "https://example.com" (3)
1 The field property indicates the originally selected subform. Previously, the field that would switch to subforms now just shows which subform was originally selected. It only carries historical information. Unless you need to keep this information, you can remove the field from your form definition. If you remove it, the field will remain in the JCR but will not be rendered or used.
2 From previous internal selection.
3 External URL.

Benefits of compositeField

  • No data migration: Existing content works without changes.

  • Same storage: Keeps the exact JCR structure.

  • No data loss: All properties stay visible and editable.

  • Clear for users: All properties from the previous subforms of various options can be edited within a single, streamlined composite subform.

  • Accessible form support: Fully works with the Accessible form engine.

Implementation steps

  1. Identify affected forms

    Find Switchable fields with removePreviouslySelected=false:

    Click to expand or collapse

    find . -name "*.yaml" -exec grep -l "removePreviouslySelected.*false" {} \;

  2. Analyze data dependencies

    For each form, check:

    • Which data needs to stick around from all options.

    • How the UI should show multiple options.

      To improve clarity and organization, consider ordering or rendering properties with static fields to separate different sections, similar to how they were previously grouped in subforms. This approach can help group related properties effectively, if needed.

  3. Update form definition

    Swap the Switchable field for a compositeField. Use the same property names to keep data intact.

  4. Test existing content

    Make sure existing content renders correctly with the new setup. No data changes should be needed.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules