Accessible forms (tech preview)

This is a technical preview of the Accessible forms feature, do not use in production. We encourage you to try the technical preview or read about it and share your experience, impressions and inputs with us at feedback@magnolia-cms.com.

Forms often have accessibility issues due to design or through the underlying technology. These problems can make it hard for some people to use them. Magnolia is developing a new UI based on front-end technology (React) and a custom front-end design system built from the ground up for accessibility.

Magnolia’s accessible 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.

Viewing accessible forms

Accessible 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 accessible 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.

To compare the new Accessible forms with the Vaadin forms (for a form that displays the accessible forms), you can force it to render the Vaadin forms by adding a :vaadinForm parameter at the end of the query string.

Example:

http://localhost:8080/testWarp/.magnolia/admincentral#app:cakes-app:detail;/Banana-Cake:edit:vaadinForm

Support for more fields is in development, but not all of 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.

Click the images to enlarge and compare.
Vaadin form	New UI form

How to try accessible forms

There are a few different options to get started with the new forms.

Watch a video

Watch a 10-minute overview of the Accessible forms in action.

Live demo

Email us at feedback@magnolia-cms.com to book a live demo, and share your feedback with us directly.

Local installation

The feature requires Magnolia 6.3.5 or later. If your project isn’t on 6.3, consider upgrading to 6.3.

Alternatively, try it on a fresh Magnolia 6.3.5 (or later) instance and bring over some of your forms, such as a content app or templating components, to see how they render.

We recommend one of the following installation routes.

With Maven

Create a custom webapp, including the form-engine dependency below.

<dependency>
    <groupId>info.magnolia.warp</groupId>
    <artifactId>form-engine-vaadin-components</artifactId>
    <version>1.0.0-beta0</version>
</dependency>

Add the webapp to a local Tomcat server if needed.

With Jars
1. Get a webapp with the Magnolia CLI jumpstart command.
2. Add the webapp to a local Tomcat server if needed, or just use the one that the CLI provides.
3. Download and copy the following five jars into the …/WEB-INF/lib folder of the webapp:
Download a full webapp

This option requires a DX Core license.
1. Sign in to Magnolia Nexus.
2. Download the full form-engine-webapp-dev webapp from there and add it to your local Tomcat server. (You will get a blank screen or error if you are not signed into Nexus.)

Add the demo project and try it out

There’s a demo project called demo-warp-forms, which demonstrates all of the features so far implemented in Accessible forms.

Download the demo project and copy the demo-warp-forms-lm directory into your configured magnolia.resources.dir directory (into the light-modules directory).
Start your Magnolia instance.
Open the Cakes app and create a new item to try out the Accessible forms.

Usage

Determine why a form is displaying Vaadin forms

Open the Definitions app, and switch to the Problems subapp. Use the new Problem type filter and choose UNSUPPORTED.

You will now see the problems that cause the form to display the Vaadin form.

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

Check which properties are being ignored

Open the Definitions app, and switch to the Problems subapp. Use the new Problem type filter and choose IGNORED.

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.

...
    detail:
        label: My App detail
        form:
            $type: vaadinForm
            properties:
...

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

See all the problems of a form

In the Problems subapp, only the first problem of each definition is displayed. To see all the problems of a form, check the checkbox on the left to select the problem and use the Export problems action in the Action bar. A text file will be exported.

Use Accessible forms and Vaadin forms in parallel

Even once the Accessible forms feature is released, not every form will be supported due to the many custom fields included in extensions or customer projects. There will be a transition period. You can continue to use Vaadin forms and upgrade them to Accessible forms as appropriate.

Current and planned support

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

Features not yet supported

For the standard fields, several features aren’t supported yet:

Editing multi-language content.
Form layouts.
Previews in a linkField.
Reordering items in a multiField.
Supplying a custom fieldType.
Tabs.
The richTextField editor doesn’t have Magnolia plugins.

In the Page Editor, when you add a page or component, you always get the Vaadin form. However, when you edit a page or component, you get the Accessible form if all fields are supported.

Standard form fields supported

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

Supported fields	Fields not yet supported
checkBoxField	jsonComboBoxField
checkBoxGroupField	jsonLinkField
comboBoxField	passwordField
compositeField	sliderField
damLinkField	staticField
dateField	switchableField
jcrMultiField
jcrMultiLinkField (renders as jcrMultiField)
jcrMultiValueField
linkField
listSelectField
pageLinkField
radioButtonGroupField
richTextField
textField
tokenField (renders as comboBoxField)
twinColSelectField (renders as comboBoxField)

Supported fields

Fields not yet supported

jcrMultiLinkField (renders as jcrMultiField)

radioButtonGroupField

richTextField

textField

tokenField (renders as comboBoxField)

twinColSelectField (renders as comboBoxField)

The fields from the Magnolia Extensions and custom fields are not yet supported.

Field properties supported

Key

Fallback to Vaadin: Vaadin renders the entire form. Problems are logged in the Definitions app. To work with the new forms, the definition requires changes to the form definition in the project. Support is not planned for this feature.
Ignored: The form is rendered by the new UI. Your definition doesn’t require migration to work with the new forms, the respective property however has no effect. This means that the new form engine silently ignores such properties without falling back to Vaadin forms.
Supported
Backlog: The property hasn’t been implemented yet. Support is planned.
Not supported
TBA

Common properties

Common simple field properties

$type
(non-default) factoryClass
class
converterClass
defaultValue
description
fieldBinderClass
i18n
label
name
readOnly
requiredErrorMessage
required
styleName
type
validators

Common option group field properties

layout

Common select field properties

datasource
filteringMode

Common complex field properties

$type
description
i18n
implementationClass
itemProvider
label
name
styleName

Common multi field properties

buttonSelectAddLabel
buttonSelectRemoveLabel
canRemoveItems
chooserId
entryResolution
field
itemCountErrorMessage
maxItems
minItems
orderHandler
requiredErrorMessage
required

Common comboBoxField properties

emptySelectionAllowed
emptySelectionCaption
pageLength
placeholder
popWidth
scrollToSelectedItem
textInputAllowed

Field-specific properties

Specific textField properties

maxLength
placeHolder
rows
valueChangeTimeout

Specific richTextField properties

alignment
ckEditorVersion
colors
editorType
fonts
fontSizes
height
images
linkFieldDefinitions
lists
source
tables

Specific dateField properties

dateFormat
resolution
timeFormat
time

Specific checkBoxField properties

buttonLabel

Specific checkBoxGroupField properties

No field-specific properties.

Specific radioButtonGroupField properties

No field-specific properties.

Specific listSelectField properties

rows

Specific linkField properties

buttonSelectNewLabel
buttonSelectOtherLabel
chooserId
editable
implementation class
preview
showOptions

Specific twinColSelectField properties (renders as comboBoxField)

leftColumnCaption
rightColumnCaption

Specific tokenField properties (renders as comboBoxField)

comboBox

Specific compositeField properties

idPropertyName
layout
properties

Specific jcrMultiValueField properties

No field-specific properties.

Specific jcrMultiField properties

No field-specific properties.

Feedback

DX Core