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 info.magnolia.ui.editor.FormDefinition.

If you work with the Magnolia 5 UI framework, see Form definition for Magnolia 5 UI instead.

Example form 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

The properties list here is defined with the YAML list syntax.

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).

See Field definition for more information.

layout

optional, default is info.magnolia.ui.framework.layout.FormLayoutDefinition

Defines the form layout. The value must be a subtype of info.magnolia.ui.framework.layout.LayoutDefinition.

See Layout types for more information.

Available field definition classes

$type	class
`checkBoxField`	`info.magnolia.ui.field.CheckBoxFieldDefinition`
`checkBoxGroupField`	`info.magnolia.ui.field.CheckBoxGroupFieldDefinition`
`codeField`	`info.magnolia.ui.field.CodeFieldDefinition`
`comboBoxField` `jsonComboBoxField`	`info.magnolia.ui.field.ComboBoxFieldDefinition` `info.magnolia.rest.ui.field.comboboxfield.JsonComboBoxFieldDefinition`
`compositeField` `jsonCompositeField`	`info.magnolia.ui.field.CompositeFieldDefinition` `info.magnolia.rest.ui.field.JsonCompositeFieldDefinition`
`dateField`	`info.magnolia.ui.field.DateFieldDefinition`
`hiddenField`	`info.magnolia.ui.field.HiddenFieldDefinition`
`linkField` `damLinkField` `pageLinkField` `jsonLinkField`	`info.magnolia.ui.field.LinkFieldDefinition` `info.magnolia.dam.app.field.DamLinkFieldDefinition` `info.magnolia.pages.app.field.PageLinkFieldDefinition` `info.magnolia.rest.ui.field.linkfield.JsonLinkFieldDefinition`
`listSelectField`	`info.magnolia.ui.field.ListSelectFieldDefinition`
`multiField` `jcrMultiValueField` `jcrMultiField` `jsonMultiField`	`info.magnolia.ui.field.MultiFieldDefinition` `info.magnolia.ui.field.JcrMultiValueFieldDefinition` `info.magnolia.ui.field.JcrMultiFieldDefinition` `info.magnolia.rest.ui.field.JsonMultiFieldDefinition`
`passwordField`	`info.magnolia.ui.field.PasswordFieldDefinition`
`radioButtonGroupField`	`info.magnolia.ui.field.RadioButtonGroupFieldDefinition`
`richTextField`	`info.magnolia.ui.field.RichTextFieldDefinition`
`sliderField`	`info.magnolia.ui.field.SliderFieldDefinition`
`staticField`	`info.magnolia.ui.field.StaticFieldViewDefinition`
`switchableField`	`info.magnolia.ui.field.SwitchableFieldDefinition`
`textField`	`info.magnolia.ui.field.TextFieldDefinition`
`tokenField`	`info.magnolia.ui.field.TokenFieldDefinition`
`twinColSelectField`	`info.magnolia.ui.field.TwinColSelectFieldDefinition`

Your Magnolia installation may contain more fields depending on the installed modules.

Layout types

$type	class
`declarativeLayout`	`info.magnolia.ui.framework.layout.DeclarativeLayoutDefinition`
`form` ( 6.2.1+)	`info.magnolia.ui.framework.layout.FormLayoutDefinition`
`horizontal` ( 6.2.1+)	`info.magnolia.ui.framework.layout.HorizontalLayoutDefinition`
`tabbedLayout`	`info.magnolia.ui.framework.layout.TabbedLayoutDefinition`

Default layout

With the default layout, it is not possible to configure anything. Use this layout when there is no need for customization.

From Magnolia 6.2.1, FormLayoutDefinition has replaced the deprecated PlainFormLayoutDefinition as the default layout.

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.

Example tabbed layout definition

layout:
  $type: tabbedLayout
  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

Horizontal layout

With the horizontal layout, you can order components horizontally. To disable spacing between components, set the spacing property to false.

HorizontalLayoutDefinition has been introduced since Magnolia 6.2.1.

Example horizontal layout definition

composite:
  $type: compositeField
  label: Name
  layout: horizontal
  fields:
    - name: salutation
      label: Salutation
      $type: select
      options:
        - name: Mr.
          value: Mr.
          label: Mr.
        - name: Mrs.
          value: Mrs.
          label: Mrs.
    - name: firstName
      $type: text
      label: First name
    - name: lastName
      $type: text
      label: Last name

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 for full customization.

Example declarative layout definition

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 a caption 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.

Example declarative template

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

src/main/resources/info/magnolia/contacts/layout/my-style.css

.my-container {
    background-color: #93bbc4;
}

src/main/java/info/magnolia/contacts/layout/VerticalLayout.java

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.

Page tree