checkboxGroup

checkboxGroup allows users to select multiple values from a list using checkboxes.

XML Element

checkboxGroup

Java Class

JmixCheckboxGroup

Basics

LIVE DEMO

The following example populates two checkboxGroup components from an enumeration and displays the items vertically and horizontally.

<checkboxGroup id="verticalCheckboxGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<checkboxGroup id="horizontalCheckboxGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

Data-aware checkboxGroup

You can bind a component to an attribute of an entity held in a data container.

To bind checkBoxGroup to an entity attribute:

  1. Specify the name of the data container as the dataContainer attribute value.

  2. Specify the name of the entity attribute as the property attribute value.

<data>
    <instance class="com.company.onboarding.entity.User" id="userDc">
        <fetchPlan extends="_base">
            <property name="hobbies" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection class="com.company.onboarding.entity.Hobby" id="hobbiesDc">
        <fetchPlan extends="_base"/>
        <loader id="hobbiesDl">
            <query>
                <![CDATA[select e from Hobby e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <checkboxGroup dataContainer="userDc"
                   property="hobbies"
                   itemsContainer="hobbiesDc"
                   id="checkboxGroup"/>
</layout>

In this case, checkBoxGroup will display instance names of the Hobby entity, and its getTypedValue() method will return the Collection of selected entity instances.

Custom Items

LIVE DEMO

To set the list of checkBoxGroup items, use the following methods:

Items List

The setItems() method allows you to specify component items programmatically.

@ViewComponent
protected JmixCheckboxGroup<Integer> checkboxGroupWithList;
    checkboxGroupWithList.setItems(getItemsList());
protected List<Integer> getItemsList() {
    return List.of(2, 4, 5, 7);
}

Items Map

ComponentUtils.setItemsMap() allows you to specify a string label for each item value explicitly.

@ViewComponent
protected JmixCheckboxGroup<Integer> checkboxGroupWithMap;
    ComponentUtils.setItemsMap(checkboxGroupWithMap, getItemsMap());
protected Map<Integer, String> getItemsMap() {
    Map<Integer, String> itemsMap = new LinkedHashMap<>();
    itemsMap.put(2, "Two");
    itemsMap.put(4, "Four");
    itemsMap.put(5, "Five");
    itemsMap.put(7, "Seven");
    return itemsMap;
}

Enumeration Items

LIVE DEMO

You can use either a declarative or programmatic approach to set the values of an enum as checkBoxGroup items.

The following example demonstrates the declarative approach.

<checkboxGroup id="verticalCheckboxGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<checkboxGroup id="horizontalCheckboxGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

The example below uses the programmatic approach.

@ViewComponent
protected JmixCheckboxGroup<CustomerGrade> checkboxGroupWithEnum;
    checkboxGroupWithEnum.setItems(CustomerGrade.class);

Orientation

LIVE DEMO

Use the themeNames attribute to explicitly control the layout of items:

<checkboxGroup id="verticalCheckboxGroup"
               label="Vertical"
               themeNames="vertical"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>
<checkboxGroup id="horizontalCheckboxGroup"
               label="Horizontal"
               themeNames="horizontal"
               itemsEnum="io.jmix.uisamples.entity.CustomerGrade"/>

Custom Item Presentation

It is possible to customize the render of elements. You can use the setRenderer() method or the @Supply annotation for it.

@Autowired
private UiComponents uiComponents;
@Autowired
private FileStorage fileStorage;

@Supply(to = "userCheckboxGroup", subject = "renderer")
private ComponentRenderer<HorizontalLayout, User> userCheckboxGroupRenderer() {
    return new ComponentRenderer<>(user -> {
        FileRef fileRef = user.getPicture();
        HorizontalLayout row = uiComponents.create(HorizontalLayout.class);
        row.setAlignItems(FlexComponent.Alignment.END);
        if (fileRef != null) {
            Image image = uiComponents.create(Image.class);
            image.setWidth("30px");
            image.setHeight("30px");
            image.setClassName("user-picture");
            InputStreamDownloadHandler handler =
                    DownloadHandler.fromInputStream(event ->
                            new DownloadResponse(
                                    fileStorage.openStream(fileRef),
                                    fileRef.getFileName(),
                                    fileRef.getContentType(),
                                    -1
                            ));
            image.setSrc(handler);
            row.add(image);
        }
        row.add(new Span(user.getFirstName() + ", " + user.getLastName()));
        return row;
    });
}

Alternatively, you can render items using a nested fragmentRenderer element. Refer to the Fragment Renderer section for more information.

Theme Variants

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

vertical

Displays items vertically.

Lumo

horizontal

Displays items horizontally.

Aura

helper-above-field

Renders the helper text above the field, below the label.

Aura, Lumo

Attributes

The following attributes are specific to checkboxGroup:

Name Description Default

itemsContainer

Sets the items container.

—

itemsEnum

Sets the items enum.

—

The following shared attributes are supported by checkboxGroup:

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - dataContainer - enabled - errorMessage - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - themeNames - visible - width

Handlers

The following handlers are specific to checkboxGroup:

Name Description

itemEnabledProvider

Determines whether each item is enabled.

itemLabelGenerator

Provides the text shown for each item.

renderer

Provides the component used to render each item. See Custom Item Presentation.

validator

Validates the component value.

The following shared handlers are supported by checkboxGroup:

AttachEvent - ClientValidatedEvent - ComponentValueChangeEvent - DetachEvent - TypedValueChangeEvent - statusChangeHandler

Elements

A checkboxGroup can include fragmentRenderer and tooltip as its nested elements.

See Also