FieldGroup - CUBA Platform. Developer’s Manual

4.5.2.1.11. 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="order-with-customer">
    </datasource>
</dsContext>
<layout>
    <fieldGroup id="orderFieldGroup" datasource="orderDs" width="250px">
        <field property="date"/>
        <field property="customer"/>
        <field property="amount"/>
    </fieldGroup>
</layout>

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 property="num"/>
        <field property="date"/>
        <field property="amount"/>
    </column>
    <column width="400px">
        <field property="customer"/>
        <field property="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.

Custom fields can be included in the field element as inline XML definition:
```
<fieldGroup>
    <field id="demo">
        <lookupField id="demoField" datasource="userDs" property="group"/>
    </field>
</fieldGroup>
```
Attributes of field:
- id – required attribute, if property is not set; otherwise it takes the same value as property by default. The id attribute should contain an arbitrary unique identifier either of a field with the property attribute set, or a programmatically defined field. In the latter case, the field should have the attribute custom="true" as well (see below).
- property - required attribute, if id is not set; it should contain an entity attribute name, which is displayed in the field, for data binding.
- 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 setComponent() method of FieldGroup (see below).
- the generator attribute is used for declarative creation of custom fields: you can specify the name of the method that returns a custom component for this field:
  
  <fieldGroup datasource="productDs"> <column width="250px"> <field property="description" generator="generateDescriptionField"/> </column> </fieldGroup>
  
  public Component generateDescriptionField(Datasource datasource, String fieldId) { TextArea textArea = componentsFactory.createComponent(TextArea.class); textArea.setRows(5); textArea.setDatasource(datasource, fieldId); return textArea; }
- 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.

fieldFactoryBean: declarative fields defined in the XML-descriptor are created with the FieldGroupFieldFactory interface. In order to override this factory, use this attribute with the name of your custom FieldGroupFieldFactory implementation.

For the FieldGroup created programmatically, use the setFieldFactory() method.

Methods of the FieldGroup interface:

addField enables adding fields to the FieldGroup at runtime. As a parameter it takes a FieldConfig instance, you can also define the position of the new field by adding colIndex and rowIndex parameters.

bind() method applied to the field after setDatasource() triggers the creation of field components.

createField() is used to create a FieldGroup element implementing FieldConfig interface:
```
fieldGroup.addField(fieldGroup.createField("newField"));
```

getComponent() 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 getFieldNN("id").getComponentNN(). 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 property="date"/>
    <field property="customer"/>
    <field property="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 getComponent() 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`	`mask` is specified	MaskedField
	TextField
`UUID`		MaskedField with hex mask

Related Entity

optionsDatasource is specified

LookupPickerField

PickerField

Enumeration (enum)

LookupField

string

mask is specified

rows is specified

boolean

date, dateTime

time

int, long, double, decimal

mask is specified

MaskedField

TextField

UUID

MaskedField with hex mask

removeField() enables removing fields at runtime by id.

setComponent() method is used to set your own field view. Can be used together with the custom="true" attribute of the field element or with the field created programmatically by the createField() method (see above). The FieldConfig instance can be obtained with getField() or getFieldNN() method, then the setComponent() method is called:

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

@Override
public void init(Map<String, Object> params) {
        PasswordField passwordField = componentsFactory.createComponent(PasswordField.class);
        fieldGroup.getFieldNN("password").setComponent(passwordField);
}

Attributes of fieldGroup: align - border - caption - captionAlignment - datasource - editable - enable - fieldFactoryBean - id - height - stylename - visible - width
Attributes of column: flex - id - width
Attributes of field: caption - captionProperty - cols - custom - datasource - dateFormat - description - editable - enable - generator - id - link - linkInvoke - linkScreen - linkScreenOpenType - mask - maxLength - optionsDatasource - property - required - requiredMessage - resolution - rows - showSeconds - tabIndex - visible - width
Elements of field: column - field - validator
API: addField - bind - createField - getComponent - removeField - setComponent - setFieldFactory