Form definition
Forms define fields and similar components as well as their layout. Form definition is used in dialogs and the detail subapps of content apps.
This form definition is part of the Magnolia 6 UI framework. The fully
qualified class name is If you work with the Magnolia 5 UI framework, see Form definition for Magnolia 5 UI instead. |
Example definition
form:
properties:
salutation:
label: Salutation
$type: textField
i18n: true
firstName:
label: First name
$type: textField
required: true
lastName:
label: Last name
$type: textField
required: true
email:
label: Email
$type: textField
required: true
validators:
email:
$type: emailValidator
phone:
label: Phone
$type: textField
required: true
Form properties
Property | Description |
---|---|
|
required List of editor property definition items (typically, a list of fields). See Field definition for more information. |
|
optional, default is
Defines the form layout. The value must be a subtype of
See Layout types for more information. |
Layout types
$type | class |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Default layout
info.magnolia.ui.framework.layout.FormLayoutDefinition (form
) is the default layout.
Use this layout when there is no need for customization.
Tab layout
With info.magnolia.ui.framework.layout.TabbedLayoutDefinition (tabbedLayout
),
you can organize components into tabs.
form:
layout:
$type: tabbedLayout
tabs:
personal:
fields:
- name: salutation
- name: firstName
- name: lastName
details:
fields:
- name: email
- name: phone
Alternatively, you can use info.magnolia.ui.editor.TabWithFieldsFormDefinition (tabbedForm
) to configure fields in tabs.
This form comes with a tab layout, which is similar to how a form is defined by default in Magnolia 5 UI.
form:
$type: tabbedForm
tabs:
firstTab:
fields:
foo:
label: foo
$type: textField
secondTab:
fields:
bar:
label: bar
$type: textField
required: true
i18n keys from Magnolia 5 UI are not compatible with myLightModule/dialogs/myDialog.yaml
myLightModule/dialogs/myDialog.yaml
|
Stacked layout
With info.magnolia.ui.framework.layout.StackedLayoutProducer (stacked
),
you can arrange components vertically. Any captions are placed above the
respective components, which means that more horizontal space is
allocated to the components themselves. This is the default layout for
composite fields.
form:
properties:
composite:
$type: compositeField
layout:
$type: stacked
itemProvider:
$type: currentItemProvider
properties:
first:
$type: textField
second:
$type: textField
Horizontal layout
With info.magnolia.ui.framework.layout.HorizontalLayoutDefinition (horizontal
),
you can arrange components horizontally. To disable spacing between components,
set the spacing
property to false
. Use this layout mainly for
composite fields.
form:
properties:
composite:
$type: compositeField
layout:
$type: horizontal
itemProvider:
$type: currentItemProvider
properties:
first:
$type: textField
second:
$type: textField
Declarative layout
With info.magnolia.ui.framework.layout.DeclarativeLayoutDefinition (declarativeLayout
),
you can create form entries in an arbitrary Vaadin component container
using the
Vaadin declarative syntax.
Use this layout for full customization.
form:
layout:
$type: declarativeLayout
template: /contacts/layouts/edit-contact.html
To render the layout, a template
property is required. Because the
Vaadin declarative syntax is used to design custom layouts, the
declarative template has to be an HTML document.
In the template, the tag of a component element can have one of the following prefixes:
-
vaadin-
: Vaadin core component. -
mgnl-
: Magnolia predefined or user-defined component. To define a mapping between a tag prefix and the Java package of the component, see the Component Prefix to Package Mapping section of Designing UIs Declaratively. The following Magnolia predefined components are available:-
<mgnl-separator/>
: horizontal line to separate content. -
<mgnl-group caption="">
: group header with acaption
attribute to separate content.
-
-
form-
: Magnolia property as defined in YAML.
You can always use Magnolia predefined or user-defined components and Magnolia properties with Vaadin core components.
<html>
<head>
<meta name="package-mapping"
content="custom:info.magnolia.contacts.layout"/>
</head>
<body>
<custom-vertical-layout spacing="false">
<vaadin-vertical-layout spacing="false" style-name="my-container">
<vaadin-label width-auto>Hello declarative layout</vaadin-label>
<mgnl-separator/>
<vaadin-label width-auto>${i18n.get("contacts.label")}</vaadin-label>
</vaadin-vertical-layout>
<mgnl-group caption='${i18n.get("contacts.personal")}'>
<vaadin-form-layout>
<form-salutation/>
<form-firstName/>
<form-lastName/>
</vaadin-form-layout>
</mgnl-group>
<mgnl-group caption="Details">
<vaadin-form-layout>
<form-email/>
<form-phone/>
</vaadin-form-layout>
</mgnl-group>
<mgnl-group caption="Address">
<vaadin-form-layout>
<form-streetAddress/>
<form-postalCode/>
<form-city/>
<form-country/>
</vaadin-form-layout>
</mgnl-group>
</custom-vertical-layout>
</body>
</html>
It is recommended that Magnolia properties be nested inside a
<vaadin-form-layout>
tag. If you insert a Magnolia property inside a
<vaadin-vertical-layout>
tag, the component will not be rendered as
nicely.
.my-container {
background-color: #93bbc4;
}
package info.magnolia.contacts.layout;
import com.vaadin.annotations.StyleSheet;
@StyleSheet("my-style.css")
public class VerticalLayout extends com.vaadin.ui.VerticalLayout {
}
If VerticalLayout.java
is stored in
src/main/java/info/magnolia/contacts/layout
, my-style.css
should be
added to src/main/resources/info/magnolia/contacts/layout
.
Action layout
With info.magnolia.ui.dialog.layout.DefaultEditorActionLayoutDefinition (defaultEditorActionLayout
),
you can define an action area in both dialogs and the detail subapps of
content apps. This is the default layout for footers and includes
predefined primary and secondary actions.
To learn about the layout properties, see
footerLayout
.