Page History
Forms define fields and similar components as well as their layout. At the moment, form definition is only used in the detail subapps of content apps.
Info |
---|
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. |
Table of Contents |
---|
Example form definition
Code Block | ||
---|---|---|
| ||
form: properties: - name: salutation class: info.magnolia.ui.field.TextFieldDefinition - name: firstName class: info.magnolia.ui.field.TextFieldDefinition required: true - name: lastName class: info.magnolia.ui.field.TextFieldDefinition required: true - name: email $type: textField required: true validators: email: class: info.magnolia.ui.framework.databinding.validator.EmailValidatorDefinition - name: phone $type: textField - name: streetAddress $type: textField required: true - name: postalCode $type: textField required: true - name: city $type: textField required: true - name: country $type: textField required: true |
The properties
list here is defined with the YAML list syntax.
Tip |
---|
When a property type is defined as a list in the corresponding Java class, you can use the YAML map syntax or list syntax. Map2BeanTransformer converts YAML in both cases correctly. See YAML: Defining a list property via YAML map or list syntax. |
Form properties
properties | required A list of editor property definition items (typically, a list of fields). | |||||||||
| required The name of the editor property definition item. Use alphanumeric characters without spaces. | |||||||||
| required (unless The type of the editor property definition item. The value must be a fully qualified class name and a subtype of If the definition class is annotated with | |||||||||
| You can use this as a shortcut for
To use the | |||||||||
| optional Help text displayed when the user clicks the help icon. The value can be literal or a key of a message bundle. Not applicable to a static field. | |||||||||
| optional, default is Enables i18n authoring support, which allows editors to write foreign-language or regionally targeted content. A two-letter language identifier (en, de, fr etc.) is displayed on controls where | |||||||||
| optional Field label displayed to editors. The value can be literal or a key of a message bundle. If you do not provide the property, Magnolia will fall back to a generated i18n key. If you do not want a label at all, define the property and set its value to a blank space such as | |||||||||
| optional Additional style information for an editor property definition item applied to the element when the form is rendered. The value can be a CSS class or a list of CSS classes separated by white spaces. | |||||||||
| optional, default is The value must be a fully qualified class name and a subtype of See Form definition - 6 UI for more information. |
Available field definition classes
Include Page | ||||
---|---|---|---|---|
|
Form layout
Plain layout
With the plain layout, it is not possible to configure anything. Use this layout class when there is no need for customization.
The fully qualified class name of the plain layout is info.magnolia.ui.framework.layout.PlainFormLayoutDefinition
.
Tabbed layout
With the tabbed layout, you can add or remove tabs and fields. It is not possible to change how any tabs and fields are rendered. Use this layout class when the need for customization is minimal.
The fully qualified class name of the tabbed layout is info.magnolia.ui.framework.layout.TabbedLayoutDefinition
. If the definition class is annotated with info.magnolia.ui.framework.layout.LayoutType
, you can use the $type
alias tabbedLayout
instead.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
layout: class: info.magnolia.ui.framework.layout.TabbedLayoutDefinition tabs: personal: fields: - name: salutation - name: firstName - name: lastName details: fields: - name: email - name: phone address: fields: - name: streetAddress - name: postalCode - name: city - name: country |
Declarative layout
With the declarative layout, you can create form entries in an arbitrary Vaadin component container using the Vaadin declarative syntax. Use this layout class for full customization.
The fully qualified class name of the declarative layout is info.magnolia.ui.framework.layout.DeclarativeLayoutDefinition
. If the definition class is annotated with info.magnolia.ui.framework.layout.LayoutType
, you can use the $type
alias declarativeLayout
instead.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
layout: class: info.magnolia.ui.framework.layout.DeclarativeLayoutDefinition 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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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> |
Info |
---|
It is recommended that Magnolia properties be nested inside a |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
.my-container { background-color: #93bbc4; } |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
package info.magnolia.contacts.layout; import com.vaadin.annotations.StyleSheet; @StyleSheet("my-style.css") public class VerticalLayout extends com.vaadin.ui.VerticalLayout { } |
Info |
---|
If |