FieldGroup - CUBA Platform. Developer’s Manual

4.5.2.1.10. FieldGroup

FieldGroup is intended for the joint display and editing of multiple entity attributes.

XML-name of the component: fieldGroup

The component is implemented for Web Client and Desktop Client.

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

<dsContext>
    <datasource id="orderDs"
                class="com.sample.sales.entity.Order"
                view="orderWithCustomer">
    </datasource>
</dsContext>
<layout>
    <fieldGroup id="orderFieldGroup" datasource="orderDs" width="250px">
        <field id="date"/>
        <field id="customer"/>
        <field id="amount"/>
    </fieldGroup>

In the example above, dsContext defines an orderDs data source, which contains a single instance of the Order entity. The data source is specified in the datasource attribute of the fieldGroup component. field elements refer to the entity attributes that need to be displayed in the component.

Elements of fieldGroup:

column – optional element that allows you to position fields in multiple columns. For this purpose, field elements should be placed not immediately within fieldGroup, but within a column. For example:
```
<fieldGroup id="orderFieldGroup" datasource="orderDs" width="100%">
    <column width="250px">
        <field id="num"/>
        <field id="date"/>
        <field id="amount"/>
    </column>
    <column width="400px">
        <field id="customer"/>
        <field id="info"/>
    </column>
</fieldGroup>
```
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:
- 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.
- flex – a number, which indicates the degree of horizontal change in the overall size of the column relative to other columns as a result of changing the entire width of fieldGroup. For example, you can specify flex=1 for a column, and flex=3 for another one.
- id – an optional column identifier, which allows you to refer to it in case of screen extension.
field – the main component element. It defines one field of the component.

Attributes of field:
- id – required attribute; it should contain either an entity attribute name, which is displayed in the field, or an arbitrary unique identifier of a programmatically defined field. In the latter case, field should have the attribute custom="true" as well (see below).
- caption − allows you to specify a field caption. If not specified, an entity attribute localized name will be displayed.
- visible − allows you to hide the field together with the caption.
- datasource − allows you to specify a data source for the field, other than specified for the entire fieldGroup component. Thus, attributes of different entities can be displayed in a field group.
- optionsDatasource specifies a name of a data source, used to create a list of options. You can specify this attribute for a field connected to a reference entity attribute. By default, the selection of a related entity is made through a lookup screen. If optionsDatasource is specified, you can select the related entity from a drop-down list of options. Actually, specifying optionsDatasource will lead to the fact that LookupPickerField will be used in the field instead of PickerField.
- width − allows you to specify the field width excluding caption. By default, the field width will be 200px. The width can be specified both in pixels and in percentage of the total horizontal width of the column. To specify the width of all fields simultaneously, you can use the width attribute of the column element described above.
- custom – if set to true, it means that a field identifier does not refer to an entity attribute, and a component, which is in the field, will be set programmatically using addCustomField() method of FieldGroup (see below).
- link - if set to true, enables displaying a link to an entity editor instead of an entity picker field (supported for Web Client only). Such behaviour may be required when the user should be able to view the related entity, but should not change the relationship.
- linkScreen - contains the identifier of the screen that is opened by clicking the link, enabled in the link attribute.
- linkScreenOpenType - sets the screen opening mode (THIS_TAB, NEW_TAB or DIALOG).
- linkInvoke - contains the controller method to be invoked instead of opening the screen.
The following attributes of field can be applied depending on the type of the entity attribute displayed in the field:
- If you specify a value of the mask attribute for a text entity attribute, MaskedField with an appropriate mask will be used instead of TextField. In this case, you can also specify the valueMode attribute.
- If you specify a value of the rows attribute for a text entity attribute, TextArea with the appropriate number of rows will be used instead of TextField. In this case, you can also specify the cols attribute.
- For a text entity attribute, you can specify the maxLength attribute similarly to one described for TextField.
- For an entity attribute of the date or dateTime type, you can specify the dateFormat and resolution for the parameterization of the DateField component used in the field.
- For an entity attribute of the time type, you can specify the showSeconds attribute for the parameterization of the TimeField component used in the field.

Attributes of fieldGroup:

The border attribute can be set either to hidden or visible. Default is hidden. If set to visible, the fieldGroup component is highlighted with a border. In the web implementation of the component, displaying a border is done by adding the cuba-fieldgroup-border CSS class.

captionAlignment attribute defines the position of captions relative to the fields in within the FieldGroup. Two options are available: LEFT and TOP.

Methods of the FieldGroup interface:

addCustomField() is used together with the custom="true" attribute of the field element and it allows you to set your own field view. It takes two parameters: field identifier specified in the id attribute of field and the implementation of the FieldGroup.CustomFieldGenerator interface.

The generateField() method of the CustomFieldGenerator interface is invoked by FieldGroup. A data source and field identifier, for which this generator is registered, are passed into the method. The method should return a visual component (or container), which will be displayed in the field.

Example:

@Inject
protected FieldGroup fieldGroup;
@Inject
protected ComponentsFactory componentsFactory;

@Override
public void init(Map<String, Object> params) {
    fieldGroup.addCustomField("password", new FieldGroup.CustomFieldGenerator() {
        @Override
        public Component generateField(Datasource datasource, String propertyId) {
            PasswordField passwordField = componentsFactory.createComponent(PasswordField.class);
            passwordField.setDatasource(datasource, propertyId);
            return passwordField;
        }
    });
}

getFieldComponent() returns a visual component, which is located in a field with the specified identifier. This may be required for additional component parameterization, which is not available through XML attributes of field described above.

To obtain a reference to a field component in a screen controller, you can use injection instead of the explicit invocation of getFieldComponent(). To do this, use the @Named annotation and provide an identifier of fieldGroup and a field identifier after a dot.

For example, in a field selecting a related entity, you can add an action to open an instance and remove the field cleaning action as follows:

<fieldGroup id="orderFieldGroup" datasource="orderDs">
    <field id="date"/>
    <field id="customer"/>
    <field id="amount"/>
</fieldGroup>

@Named("orderFieldGroup.customer")
protected PickerField customerField;

@Override
public void init(Map<String, Object> params) {
    customerField.addOpenAction();
    customerField.removeAction(customerField.getAction(PickerField.ClearAction.NAME));
}

To use getFieldComponent() or to inject field components, you need to know which component type is located in the field. The table below shows the correspondence between entity attribute types and components created for them:

Entity attribute type Additional conditions Field component type

Entity attribute type	Additional conditions	Field component type
Related Entity	`optionsDatasource` is specified	LookupPickerField
	PickerField
Enumeration (`enum`)		LookupField
`string`	`mask` is specified	MaskedField
`rows` is specified	TextArea
	TextField
`boolean`		CheckBox
`date`, `dateTime`		DateField
`time`		TimeField
`int`, `long`, `double`, `decimal`		TextField

Related Entity

optionsDatasource is specified

LookupPickerField

PickerField

Enumeration (enum)

LookupField

string

mask is specified

MaskedField

rows is specified

TextArea

TextField