New UI Forms

Magnolia 6.4 UI is based on front-end technology (React) and a custom front-end design system built from the ground up for accessibility.

Magnolia’s New UI Forms and design system support equal access for everyone. They offer a modern design and help you build more readable, consistent, performant, and usable forms. Furthermore, it preserves your current features and improves their accessibility.

New UI Form example

Viewing New UI Forms

In 6.4, New UI Forms are used in content apps, not in dialogs, or the Page Editor.

New UI Forms use the existing Magnolia form definitions but don’t support every field or every property. When a form definition is fully supported, the new form is displayed. Otherwise, the system will fall back to the standard Vaadin form. In this case, problems are shown in the Definitions app to indicate which features aren’t supported in the new UI. Set the new Problem type filter to UNSUPPORTED or IGNORED to see them.

Support for more fields is in development, but not everything in the current behavior will be supported. To streamline the product, we’ll remove some rarely used features. See Current and planned support for more details.

There will be a transition period where most projects will have some forms still rendering with Vaadin and some forms with the New UI.

Migrating to New UI Forms

When a feature in a form isn’t supported, the entire form falls back to Vaadin. Because of this, usually no form migration is required. All of your forms should still work.

You can choose if, and when you want to invest time to clean up the form definitions or to get a form that is still displayed with Vaadin to be displayed in the New UI. However, you may have forms that you want to adjust differently from the default behaviour.

Overview

Test the forms in your content apps to check that the behaviour is as expected. Consider that decorations can introduce unsupported fields, for example from an extension.

To identify why a form renders in Vaadin, or has unexpected behaviour:

Open the Definitions app and use the Problems subapp.
Filter by Problem type:
- UNSUPPORTED - fields that cause the form to fall back to Vaadin.
- IGNORED — properties that the New UI Forms will ignore.

You can choose not to use the New UI Forms by adding the $type property to the existing form definition and setting it to vaadinForm:

...
    detail:
        form:
            $type: vaadinForm
            properties:
...

Example: Tours app - Detail subapp

This model definition, together with one decoration from the travel-demo-content-tags module (to add a TagsField), creates the Tours subapp you can see on the online demo.

model:
  nodeType: mgnl:content
  properties:
    - name: name
      required: true
    - name: description
      i18n: true
    - name: isFeatured
      type: Boolean
    - name: image
      required: true
      type: asset
    - name: tourTypes
      multiple: true
      type: reference:tourCategory
    - name: destination
      multiple: true
      type: reference:tourCategory
    - name: location
    - name: date
      type: Date
    - name: duration
      options:
        2-days:
          name: 2-days
          value: 2
        7-days:
          name: 7-days
          value: 7
        14-days:
          name: 14-days
          value: 14
        21-days:
          name: 21-days
          value: 21
      type: Long
    - name: author
    - name: body
      i18n: true
      type: richText

If you add a Slider field definition to the form definition of the detail subapp, the whole form falls back to Vaadin fields.

/tours/apps/tours.yaml

...
  detail:
    form:
      properties:
        name:
          i18n: true
        slider: (1)
          $type: sliderField
          label: Percentage
          defaultValue: 50
          stepSize: 5
          displayStepSize: 25
          valueFormat: PERCENTAGE

1	Unsupported `slider` field definition.

Recommended procedure

In case you decide to review all of your content app forms, here is the recommended procedure:

Identify forms with ignored properties.
- Open the Definitions app and switch to the Problems subapp.
- Set the Module filter to include all of your project modules.
- Set the Problem type filter to IGNORED.
- Use the new Export filtered problems action.
Decide what to do with the ignored properties.
- Review each of the problems in the downloaded file.
- If you need the behavior of an ignored property, force the form to display the Vaadin form by adding the $type: vaadinForm property to the form definition.
- Otherwise, you can clean up your definition by removing the property.
Identify forms with unsupported properties.
- Open the Definitions app and switch to the Problems subapp.
- Set the Module filter to include all of your project modules.
- Set the Problem type filter to UNSUPPORTED.
- Use the new Export filtered problems action.
Decide what to do with the unsupported properties.

Some properties are not yet supported. The most common case are the field types that aren’t yet implemented in the New UI. When a form has an unsupported property, then it displays the Vaadin form.

Review each of the problems in the downloaded file.
Consider if you still need the unsupported property.
If you need it, keep using the existing property and keep using the Vaadin form for the time being.

Using the Vaadin form may be your only option if the unsupported property is in an extension that you use.
If you need it, and it’s a field type, you could implement a new custom field type.
Otherwise, you can clean up your definition by removing the property.

Once there are no more unsupported properties in the definition, the form will render in the New UI.

Troubleshooting

Compare the Vaadin vs. the New UI display of a form

When checking the New UI version of a form, it’s useful to view it side-by-side with the Vaadin version.

You can easily force a form to render in Vaadin by appending :vaadinForm to the end of the url. You need to copy the full url and paste it in a new browser tab.

For example, https://demo.magnolia-cms.com/.magnolia/admincentral#app:tours:detail;/magnolia-travels/Kyoto:edit:vaadinForm.

Determine why a form is displayed as a Vaadin form

Are you seeing Vaadin forms instead of the New UI Forms?

Open the Definitions app, and switch to the Problems subapp.
Use the new Problem type filter and choose UNSUPPORTED.
Find your form in the list.
You will now see the problems causing the form to display the Vaadin form.

The Problems subapp displays only one problem per definition. To view all problems for a selected definition, use the Export filtered problems action.

See Current and planned support for details on which features we still plan to support in the future.

Check which properties of a form are being ignored

Open the Definitions app, and switch to the Problems subapp.
Use the new Problem type filter and choose IGNORED.
Find your form in the list. If it’s important for you that these properties are used in the form and not ignored, you can force a form to be displayed in Vaadin by setting the $type of the form to vaadinForm.

See Current and planned support for a full list of which properties are ignored.

Current and planned support

This section outlines which standard Magnolia fields and related features are supported in the new UI.

Standard form fields supported

The standard fields are described in the Field definition section of the Magnolia documentation.

Supported fields Fields not yet supported

Supported fields	Fields not yet supported
checkBoxField	jsonComboBoxField
checkBoxGroupField	jsonLinkField
compositeField	sliderField
damLinkField	codeField
comboBoxField
dateField
jcrMultiField
jcrMultiLinkField (renders as jcrMultiField)
jcrMultiValueField
listSelectField
pageLinkField
radioButtonGroupField
richTextField See the note below about the `colors`, `fonts`, and `fontSizes` properties.
textField
tokenField (renders as comboBoxField)
twinColSelectField (renders as comboBoxField)
switchableField
passwordField
linkField
staticField

jcrMultiLinkField (renders as jcrMultiField)

jcrMultiValueField

listSelectField

pageLinkField

radioButtonGroupField

richTextField

See the note below about the colors, fonts, and fontSizes properties.

textField

tokenField (renders as comboBoxField)

twinColSelectField (renders as comboBoxField)

The fields from Magnolia and Marketplace Extensions are not yet supported.

Features not yet supported

Several features aren’t supported yet:

Tabs: Tabs are ignored. The form renders all fields together.
The jcrNodeToPathConverter converter class. It forces a fallback to Vaadin.
A MultiField cannot directly contain switchable fields. It forces a fallback to Vaadin.
Usage in all dialogs.
Usage in the Page editor.
The colors, fonts, and fontSizes properties in the Rich text field (CKEditor5).

Until the fix is released (WARPFORM-704), you can configure the form to display in Vaadin forms instead, where the properties work correctly. On the form node, add $type: vaadinForm:
```
...
    form:
      $type: vaadinForm
...
```

Features that will no longer be supported

Form layouts aren’t supported as they lack the flexibility of previous versions and therefore aren’t planned for future development.

In 6.4 switchable fields, setting removePreviouslySelected=false isn’t supported in New UI Forms.

If you rely on this property in your templates, see the migration information on page Migrating the removePreviouslySelected property.

Creating custom fields in New UI Forms

JavaScript fields are the supported way to build custom fields for Magnolia’s New UI Forms.

The JavaScript UI module lets you build custom form fields with your own frontend, loaded from a module or an external URL, and embedded via an iframe.

Feedback

DX Core