formLayout

formLayout arranges form fields into responsive columns.

XML Element

formLayout

Java Class

JmixFormLayout

Basics

LIVE DEMO

The default responsive steps use one column below 40em and two columns at 40em or wider:

<formLayout>
    <textField label="TextField"/>
    <dateTimePicker label="DateTimePicker"/>
    <textArea label="TextArea"/>
    <checkbox label="Checkbox"/>
    <textArea label="TextArea with column span" colspan="2"/>
    <passwordField label="PasswordField"/>
    <emailField label="EmailField"/>
</formLayout>

Data-aware formLayout

LIVE DEMO

Set dataContainer on formLayout to bind its nested fields to the current item of an instance container. Each field uses property to select the entity attribute it displays.

<data>
    <collection id="customersDc"
                class="io.jmix.uisamples.entity.Customer"
                fetchPlan="_local">
        <loader id="customersLoader">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
    </collection>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"/>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <select id="customerSelect" label="Customer" itemsContainer="customersDc"
            helperText="Select a customer to display"/>
    <formLayout dataContainer="customerDc">
        <textField property="name"/>
        <textField property="lastName"/>
        <integerField property="age"/>
        <checkbox property="active"/>
        <select property="grade"/>
    </formLayout>
</layout>

Auto-Responsive Mode

LIVE DEMO

Set autoResponsive="true" to let formLayout determine the number of columns from the available width, configured column width, and spacing. Each formRow starts a new row. If its fields do not fit, they wrap to rows reserved for that formRow.

When auto-responsive mode is enabled, responsive steps are ignored. 
<formLayout id="formLayout" width="100%" classNames="form-layout" autoResponsive="true">
    <formRow>
        <formItem label="msg://firstName.label">
            <textField/>
        </formItem>
        <formItem label="msg://lastName.label">
            <textField/>
        </formItem>
        <formItem label="msg://rating.label">
            <comboBox id="ratingField"/>
        </formItem>
    </formRow>
    <formRow>
        <formItem label="msg://countryName.label">
            <textField/>
        </formItem>
        <formItem label="msg://birthDate.label">
            <datePicker/>
        </formItem>
        <formItem label="msg://email.label">
            <emailField/>
        </formItem>
    </formRow>
    <formRow>
        <formItem label="msg://status.label">
            <comboBox/>
        </formItem>
        <formItem label="msg://phoneNumber.label">
            <textField/>
        </formItem>
        <formItem label="msg://address.label">
            <textField/>
        </formItem>
    </formRow>
</formLayout>

For automatic distribution without explicit formRow elements, set autoRows="true". The minColumns, maxColumns, columnWidth, columnSpacing, rowSpacing, expandColumns, and expandFields attributes refine how the generated grid uses the available space.

Responsive Steps Mode

LIVE DEMO

Use nested responsiveStep elements to specify the column count and label position at different minimum widths. The applicable step controls the layout.

<formLayout>
    <responsiveSteps>
        <responsiveStep minWidth="0" columns="1" labelsPosition="TOP"/>
        <responsiveStep minWidth="30em" columns="1" labelsPosition="ASIDE"/>
        <responsiveStep minWidth="40em" columns="2" labelsPosition="TOP"/>
        <responsiveStep minWidth="50em" columns="2" labelsPosition="ASIDE"/>
        <responsiveStep minWidth="60em" columns="4" labelsPosition="TOP"/>
    </responsiveSteps>
    <formItem label="TextField">
        <textField/>
    </formItem>
    <formItem label="DateTimePicker">
        <dateTimePicker/>
    </formItem>
    <formItem label="TextArea">
        <textArea/>
    </formItem>
    <formItem label="Checkbox">
        <checkbox/>
    </formItem>
    <formItem label="TextArea with column span" colspan="2">
        <textArea/>
    </formItem>
    <formItem label="PasswordField">
        <passwordField/>
    </formItem>
    <formItem label="EmailField">
        <emailField/>
    </formItem>
</formLayout>

Attributes

Common attributes serve the same purpose for all components. The following attributes are specific to formLayout.

Name Description Default

autoResponsive

Enables the layout to automatically calculate and adjust the number of columns based on the available width of its container. See Auto-Responsive Mode.

false

autoRows

Configures whether the layout should automatically distribute fields across columns, filling each row sequentially before wrapping to the next line. This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

false

columnWidth

Defines the fixed width for all columns. Value must be a valid CSS length unit (for example, "100px", "10em"). This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

12em

columnSpacing

Defines the gap between columns using a CSS length.

—

expandColumns

When enabled, columns evenly distribute to fill any remaining horizontal space after the initial column calculation. This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

false

expandFields

When enabled, fields stretch to fill all available width within their containing column. This also applies to fields wrapped in formItem elements. This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

false

labelsAside

Specifies whether formItem elements within the layout should position their labels beside the associated fields instead of above them. This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

false (labels are positioned above fields)

labelSpacing

Defines the gap between a side-positioned label and its field using a CSS length, for example, 1em.

—

labelsPosition

Sets the label position for the default responsive steps and for nested responsiveStep elements that omit labelsPosition.

- ASIDE - labels are positioned to the side of the components.

- TOP - labels are positioned above the components.

TOP

labelWidth

Sets the width of side-positioned labels using a CSS length, for example, 8em.

—

maxColumns

Sets the maximum number of columns the layout can create. The actual number will not exceed this limit, even if there is sufficient space. This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

10

minColumns

Sets the minimum number of columns the layout will create, regardless of container width. This attribute works only when autoResponsive is enabled. See Auto-Responsive Mode.

1

rowSpacing

Defines the gap between rows using a CSS length.

—

Handlers

Name Description

AttachEvent

Fires when the layout is attached to the UI.

clickListener

Fires whenever the layout is clicked.

singleClickListener

Fires after a click is confirmed not to be part of a double-click.

doubleClickListener

Fires when the layout is double-clicked.

DetachEvent

Fires when the layout is detached from the UI.

Elements

A formLayout can contain fields directly or wrap them in formItem and formRow elements. The responsiveSteps element contains responsiveStep entries used by Responsive Steps Mode.

See Also