gridLayout

LIVE DEMO

The gridLayout component arranges child components in a responsive, two-dimensional grid system based on the CSS Grid Layout.

XML Element

gridLayout

Java Class

GridLayout

Attributes

id - alignSelf - classNames - columnMinWidth - css - enabled - gap - height - itemsContainer - itemsEnum - maxHeight - maxWidth - minHeight - minWidth - visible - width

Handlers

AttachEvent - itemLabelGenerator - renderer - DetachEvent

Elements

fragmentRenderer

Basics

You can populate gridLayout with components either declaratively in the XML descriptor or programmatically in a controller using the gridLayout.add() method.

Example of declarative addition:

<gridLayout id="gridLayout" width="100%">
    <textField placeholder="City" label="Where from?"/>
    <textField placeholder="City" label="Where to?"/>
    <datePicker label="Depart"/>
    <datePicker label="Return"/>
    <button text="Search tickets" height="AUTO"/>
</gridLayout>

Example of adding in a view controller:

@ViewComponent
private GridLayout<Object> gridLayout;

@Autowired
private UiComponents uiComponents;

@Subscribe
public void onInit(final InitEvent event) {
    Checkbox checkbox = uiComponents.create(Checkbox.class);
    checkbox.setLabel("I verify that all information is accurate");
    checkbox.setValue(false);
    gridLayout.add(checkbox);
}
grid layout basic

Data Binding

LIVE DEMO

Data binding refers to linking a visual component to a data container.

In the gridLayout component, this is achieved by setting the itemsContainer attribute to reference a data container.

<data>
    <collection id="usersDc" class="com.company.onboarding.entity.User"> (1)
        <loader id="usersDl" readOnly="true">
            <query>
                <![CDATA[select e from User e]]>
            </query>
        </loader>
        <fetchPlan extends="_base"/>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/> (2)
</facets>
<layout>
    <gridLayout width="100%"
                itemsContainer="usersDc"/> (3)
</layout>
1 Data container to hold a collection of all existing User instances.
2 Data load coordinator to automatically supply the component with instances to display from.
3 Specifying the container that holds the list of items to be displayed.

By default, the component displays the instance name of the entity.

grid layout items
You can override the default display by configuring a custom renderer.

The component also supports displaying enumeration values using the itemsEnum property.

<gridLayout itemsEnum="com.company.onboarding.entity.DayOfWeek"
            width="100%"/>

Rendering Items

LIVE DEMO

It is possible to customize the render of items. The renderer is applied to each item to create a component which represents the item.

You can use the setRenderer() method or the @Supply annotation for it.

Building on the previous example, we can generate a renderer to display each user.

@Supply(to = "gridLtUsers", subject = "renderer")
private ComponentRenderer<JmixCard, User> gridLtUsersRenderer() { (1)
    return new ComponentRenderer<>(this::createCard, this::initCard);
}

private JmixCard createCard() { (2)
    JmixCard card = uiComponents.create(JmixCard.class);
    card.setWidthFull();
    card.addThemeVariants(CardVariant.LUMO_OUTLINED, CardVariant.LUMO_ELEVATED);
    return card;
}

private void initCard(JmixCard card, User user) { (3)
    card.setHeaderPrefix(createAvatar(user));
    card.setTitle(user.getFirstName() + " " + user.getLastName());
}

private Image createAvatar(User user) { (4)
    Image image = uiComponents.create(Image.class);
    FileRef fileRef = user.getPicture();
    if (fileRef != null) {
        image.setWidth("50px");
        image.setHeight("50px");
        StreamResource streamResource = new StreamResource(
                fileRef.getFileName(),
                () -> fileStorage.openStream(fileRef));
        image.setSrc(streamResource);
    }
    return image;
}
1 Supplies a custom renderer to display each User as a Card.
2 Creates a base Card component with common styling.
3 Initializes card content with user-specific data. Called for each card instance with the corresponding User entity.
4 Creates an avatar image component from the user’s picture.
grid layout renderer

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

Attributes

Common attributes serve the same purpose for all components.

The following attributes are specific to gridLayout:

Name

Description

Default

columnMinWidth

Sets the minimum width for the grid columns in gridLayout. This ensures columns don’t become too narrow when the container resizes. This value represented as a CSS length value (for example, "50px", "10rem")

19rem

gap

Controls the spacing between grid cells (both row and column gaps). This creates visual separation between components. The value represented as a CSS length value (for example, "10px", "1rem")

var(--lumo-space-s)

Handlers

Common handlers are configured in the same way for all components.

The following handlers are specific to gridLayout.

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

Name

Description

itemLabelGenerator

Allows you to customize the labels displayed for each item. See Customizing Item Labels.

renderer

Sets the item renderer for gridLayout. The renderer is applied to each item to create a component which represents the item option. See Rendering Items.