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

properties

required

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.

Layout types

$type class

declarativeLayout

info.magnolia.ui.framework.layout.DeclarativeLayoutDefinition

defaultEditorActionLayout

info.magnolia.ui.dialog.layout.DefaultEditorActionLayoutDefinition

form

info.magnolia.ui.framework.layout.FormLayoutDefinition

horizontal

info.magnolia.ui.framework.layout.HorizontalLayoutDefinition

stacked

info.magnolia.ui.framework.layout.StackedLayoutProducer

tabbedForm

info.magnolia.ui.editor.TabWithFieldsFormDefinition

tabbedLayout

info.magnolia.ui.framework.layout.TabbedLayoutDefinition

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.

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

Example definition
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 tabbedForm and must be reconfigured. Both myLightModule.myDialog.myTextField[.label] and fields.myTextField[.label] are generated for the following Magnolia 6 UI definitions:

myLightModule/dialogs/myDialog.yaml
form:
  properties:
    myTextField:
      $type: textField
myLightModule/dialogs/myDialog.yaml
form:
  $type: tabbedForm
  tabs:
    tabMain:
      fields:
        myTextField:
          $type: textField

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.

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

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

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

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.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules