What’s New

This section covers new features of Jmix framework and Studio 2.4, as well as some breaking changes to be aware of when upgrading from a previous version of the framework.

How To Upgrade

To create new projects with Jmix 2.4 or to upgrade an existing project, you need Studio 2.4 or later, so update your Jmix Studio plugin first.

The minimal supported IntelliJ IDEA version is now 2023.3.

See Upgrading Project section for how to upgrade your project using Studio. The automatic migration procedure makes the following changes in your project:

  • Updates the version of Jmix BOM which in turn defines versions of all dependencies.

  • Updates the version of Jmix Gradle plugin.

  • Updates the version of Gradle wrapper to 8.10.2 in gradle/wrapper/gradle-wrapper.properties.

  • If the project includes the REST API add-on, adds the jmix.resource-server.authenticated-url-patterns property, see details below.

  • Replaces calls to dateTimeParameter(), dateParameter() and timeParameter() methods of input dialog builder with calls to localDateTimeParameter(), localDateParameter() and localTimeParameter(). See details below.

  • Adds the Grid Export Actions add-on to the project if it includes the Data Tools add-on. See details below.

  • Sets the jmix.ui.component.default-trim-enabled application property to false. See details below.

See also the full list of breaking changes that can affect your project after the upgrade.

Updated Dependencies

The following major dependencies have been updated:

New Features and Improvements

New Add-ons

The following new add-ons are now available:

  • The Calendar add-on provides a UI component that allows you to show data-bound events in a calendar with various views (day, week, month, etc.) and edit them by dragging and resizing.

  • The PivotTable add-on provides a UI component that enables turning a data set into a summary table and manipulating it using 2D drag-and-drop UI.

  • The Kanban add-on provides a UI component that represents a Kanban board. It shows workflow at different stages of a project, using cards for tasks and columns for stages.

  • The UI Constraints add-on allows you to control the visibility and accessibility of UI components using declarative policies defined in resource roles.

  • The REST DataStore add-on allows you to access external entities from a remote Jmix application through the standard DataManager interface in the same way as local JPA entities.

Data Binding for HTML Components

The HTML components like div, span, h1…​h5 and others can now be bound to your data model entities declaratively in XML using the dataContainer and property attributes.

In many cases this will save you from writing code to set values in these components programmatically in view controllers.

Fragment Renderer

Renderers for virtualList, dataGrid and other components can now be defined by fragments.

The new fragmentRenderer XML element should specify the fragment Java class, for example:

<virtualList itemsContainer="usersDc">
    <fragmentRenderer class="com.company.onboarding.view.userfragment.UserFragment"/>
</virtualList>

An example of the fragment used as a renderer:

<fragment xmlns="http://jmix.io/schema/flowui/fragment">
    <data>
        <instance id="userDc" class="com.company.onboarding.entity.User">
            <loader id="userDl"/>
        </instance>
    </data>
    <content>
            <formLayout id="form" dataContainer="userDc">
                <textField id="usernameField" property="username" readOnly="true"/>
                <textField id="firstNameField" property="firstName"/>
                <textField id="lastNameField" property="lastName"/>
                <textField id="emailField" property="email"/>
            </formLayout>
        </hbox>
    </content>
</fragment>

The fragment renderer class should extend the FragmentRenderer base class with type parameters indicating the root component and rendered entity, for example:

@FragmentDescriptor("user-fragment.xml")
@RendererItemContainer("userDc")
public class UserFragment extends FragmentRenderer<FormLayout, User> {
}

The @RendererItemContainer annotation is used to specify the data container that accepts the rendered entity.

See #3699 for more information.

Asynchronous Tasks

The new UiAsyncTasks bean allows you to execute an operation in a separate thread using the security context of the current user, and then update the UI with the result of that operation.

In comparison to Background Tasks, this is a lightweight mechanism based on CompletableFuture.

Trimming in Text Fields

The textField and textArea components now have the trimEnabled attribute which controls whether the component trims spaces at the beginning and at the end of the entered string.

The jmix.ui.component.default-trim-enabled application property specifies the default value of this attribute for the whole application. In new projects, this property is true. The Studio migration procedure sets this property to false for existing projects to minimize changes in behavior.

Switching Theme Variants

The new ThemeUtils class contains methods for switching theme variants at runtime. This allows you to easily switch between light and dark themes in your application.

See an example in the Changing Theme Variants at Runtime section.

Immediate Validation of Required Fields

The new jmix.ui.component.immediate-required-validation-enabled application property allows you to disable validation of required fields on view opening.

Grid Export Options

When using the Grid Export Actions add-on, the set of export options can now be defined by a particular export action using its setAvailableExportModes() method and corresponding availableExportModes property in XML. The default set of options is defined by the jmix.gridexport.default-export-modes application property.

Using Browser Time Zone

If a time zone is not assigned to the user explicitly, it can be obtained from the web browser at login. This option is controlled by the isAutoTimeZone() method of the HasTimeZone interface implemented by the standard User entity scaffolded in projects.

In existing projects the behavior won’t change, because this method returns false by default. In new projects User will be scaffolded with isAutoTimeZone() returning true.

Advanced Endpoints Security Configuration

More options have been introduced for configuring endpoints security when using Authorization Server or OpenID Connect add-ons:

  • jmix.resource-server.authenticated-url-patterns and jmix.resource-server.anonymous-url-patterns properties

  • AuthenticatedUrlPatternsProvider and AnonymousUrlPatternsProvider

  • AuthenticatedRequestMatcherProvider and AnonymousRequestMatcherProvider

See Token Based Authentication for more information.

The old AuthorizedUrlsProvider is deprecated, but still works, as well as jmix.rest.authenticated-url-patterns and jmix.rest.anonymous-url-patterns properties. It is recommended to move the configuration to the new interfaces or properties.

Search Improvements

The new @ExtendedSearch annotation can be added to an index definition interface to provide functionality of "Starts with" search. It instructs the Search add-on to create additional "virtual" subfields for each "real" field to store prepared prefix terms.

The searchField component now allows users to open a Search settings window to set the search strategy, results size and, optionally, a set of entities to search only within these entities. If there are index definitions with @ExtendedSearch in the project, the list of strategies contains "Starts with".

allTermsAnyField and allTermsSingleField strategies have been deprecated.

REST API Improvements

Generic REST API now supports CRUD operations with DTO entities in the /entities endpoints. The search conditions provided to the entities/:entityName/search endpoint are converted to the Condition tree and passed to the DataManager. This allows you to request DTO entities that are in turn loaded from another REST API through the REST DataStore.

The JSON search conditions can now include objects in property values, for example:

{
  "conditions": [
    {
      "property": "field1",
      "operator": "=",
      "value": {
        "_entityName": "Customer",
        "id": "00000000-0000-0000-0000-000000000001",
        "firstName": "John",
        "lastName": "Doe"
      }
    }
  ]
}

Studio Component Inspector

The Jmix UI component inspector now groups the properties by categories: General, Data Binding, Size, Position, Look & Feel, Other. This new feature allows you to quickly locate the property you need without having to go through a long list.

Categories are displayed only in projects based on Jmix 2.4 and above.

Besides, the component inspector now provides better support for the icon property. You can click the "pencil" button in the value field to show a dialog with the list of available icons and select an icon from it.

Composite Project Template for Monorepo

We’ve added a new template for a composite project that is intended to be hosted in a monorepo. It provides a simple structure where all subprojects are located inside the root aggregate project:

composite-project/
    subproject1/
        src/
        build.gradle
        settings.gradle
    subproject2/
        src/
        build.gradle
        settings.gradle
    build.gradle
    settings.gradle
    README.md

This project layout is recommended if you are not going to store subprojects in separate repositories.

Breaking Changes

Build Problem With EnableJmixDataRepositories

When @EnableJmixDataRepositories is used on the main application class extending AppShellConfigurator, a clean build fails with the following message:

> Task :vaadinPrepareFrontend FAILED
Could not read com.vaadin.flow.theme.Theme annotation from class com.company.onboarding.OnboardingApplication.
java.lang.TypeNotPresentException: Type [unknown] not present

The problem is caused by vaadin/flow#19616 and will be fixed in a future patch.

To work around the problem, move the @EnableJmixDataRepositories annotation to a separate @Configuration class in the same package, for example:

package com.company.onboarding;

import io.jmix.core.repository.EnableJmixDataRepositories;
import org.springframework.context.annotation.Configuration;

@EnableJmixDataRepositories
@Configuration
public class OnboardingConfiguration {
}

Protecting Generic REST Endpoints

Due to improvements in endpoints security configuration (see above), the following application property must be set to secure the Generic REST API endpoints:

jmix.resource-server.authenticated-url-patterns = /rest/**

The Studio migration procedure adds it to application.properties automatically.

Generic REST Unauthorized Error

Previously, generic REST API returned HTTP 500 code if the request to a secured endpoint was performed without Authorization header. Now it correctly returns HTTP 401.

ListMenu Styles

listMenu component styles have been changed to fix the issue with focus ring:

  • Changed margin and padding for the ListMenu itself.

  • Increased margin-inline-start for list of sub menu.

  • Changed paddings for MenuBarItem.

If you have defined your own styles for this component, you may need to adjust them.

See #3589 for more information.

Input Dialog Date Parameters

The dateTimeParameter(), dateParameter() and timeParameter() methods of the input dialog builder have been fixed: now they create parameters of java.util.Date, java.sql.Date and java.sql.Time type respectively. Previously they wrongly created LocalDateTime, LocalDate and LocalTime parameters.

See #3499 for more information.

The Studio migration procedure automatically replaces calls to these methods with calls to localDateTimeParameter(), localDateParameter() and localTimeParameter() to keep compatibility with returning values.

Grid Export Actions Add-on Dependency

Previously, the Data Tools add-on contained transitive dependency to the Grid Export Actions add-on. This dependency has been removed, so now export actions can be used only when the Grid Export Actions add-on is included explicitly.

The Studio migration procedure automatically adds the Grid Export Actions add-on to the project if it includes the Data Tools add-on.

Changelog

  • Resolved issues in Jmix Framework:

  • Resolved issues in Jmix Studio: