3.5.2.1.19. Form

Form is intended for the joint display and editing of multiple entity attributes. It is a simple container similar to GridLayout, it can have any number of nested columns, the type of nested fields is defined declaratively in XML, the fields' captions are located to the left of the fields. The main difference from GridLayout is that Form enables binding all nested fields to one data container.

Form is used instead of FieldGroup by default in generated edit screens since platform version 7.0.

gui Form 1

XML-name of the component: form

Below is an example of defining a group of fields in an XML screen descriptor:

<data>
    <instance id="orderDc"
              class="com.company.sales.entity.Order"
              view="order-edit">
        <loader/>
    </instance>
</data>
<layout expand="editActions" spacing="true">
    <form id="form" dataContainer="orderDc">
        <dateField property="date"/>
        <textField property="amount"/>
        <pickerField property="customer"/>
    </form>
</layout>

In the example above, data context defines an orderDc data container which contains a single instance of the Order entity. The data container is specified in the dataContainer attribute of the form component. Nested elements refer to the entity attributes that need to be displayed in the component. They are typed automatically depending on the attribute data type.

Attributes of form:

  • childrenCaptionWidth – specifies fixed captions width for all nested columns and their child elements. Set -1 to use auto size.

  • captionPosition - defines the fields' caption position: TOP or LEFT.

Elements of form:

  • column – optional element that allows you to position fields in multiple columns. For this purpose, nested fields should be placed not immediately within the form, but within a column. For example:

    <form id="form" dataContainer="orderDc">
        <column width="250px">
            <dateField property="date"/>
            <textField property="amount"/>
        </column>
        <column width="400px">
            <pickerField property="customer"/>
            <textArea property="info"/>
        </column>
    </form>

    In this case, fields will be arranged in two columns; the first column will contain all fields with the width of 250px, the second one with the width of 400px.

    Attributes of column:

    • id – an optional column identifier, which allows you to refer to it in case of screen extension.

    • width – specifies the field width of a column. By default, fields have the width of 200px. In this attribute, the width can be specified both in pixels and in percentage of the total horizontal width of the column.

    • childrenCaptionWidth – specifies fixed captions width for nested fields. Set -1 to use auto size.

Methods of the Form interface:

  • add() - enables adding one or more fields to the Form at runtime. As a parameter it takes a Component instance, you can also define the position of the new field by adding column and row indexes.

    Data container is not assigned to the components added programmatically. In this case, use the setValueSource() method for data binding.

    For example:

    <data>
        <instance id="container"/>
    </data>
    <layout>
        <form id="form"/>
    </layout>
    @Inject
    private KeyValueContainer container;
    @Inject
    private Form form;
    
    @Subscribe
    protected void onInit(InitEvent event) {
        Field fooField = (Field) uiComponentsGenerator.generate(
                new ComponentGenerationContext(container.getEntityMetaClass(), "foo"));
        fooField.setCaption("Foo");
        fooField.setValueSource(new ContainerValueSource<>(container, "foo"));
        form.add(fooField);
    }