4.5.2.1.6. 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 describing 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. For the fieldGroup component, you should specify a data source in datasource attribute. Entity attributes containing in the data source, which you need to display, should be specified in field elements.

fieldGroup elements:

  • 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 its 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.

    column may have the following attributes:

    • 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 – main component element. It describes one component field.

    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 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 related to a reference entity attribute. By default, the selection of a related entity is made through a selection 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 column, 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, allows 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 an entity attribute type, which is 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 an 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 located in the field.

    • For an entity attribute of the time type, you can specify the showSeconds attribute for the parameterization of the TimeField component located in the field.

fieldGroup attributes:

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

Methods of the FieldGroup interface:

  • addCustomField() is used together with the custom="true" attribute of field 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.

    generateField() 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.NAME);
            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 with the indication of an identifier of fieldGroup and a field identifier after a dot.

    For example, in the field to select 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 matching of entity attribute types and components created for them:

    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

All fieldGroup attributes:

border enable visible
caption height width
datasource id  
editable stylename  

All field attributes:

caption description linkScreen resolution
captionProperty editable linkScreenOpenType rows
cols enable maxLength showSeconds
custom id optionsDatasource visible
dateFormat link required width
datasource linkInvoke requiredMessage  

field elements:

validator

column attributes:

flex
width
Prev  Up  Next
  Home