dataLoadCoordinator

dataLoadCoordinator facet is designed for triggering data loaders and for declarative linking of data loaders to data containers, visual components, and view lifecycle events.

Basic Usage

To trigger all data loaders on the view’s BeforeShowEvent, just add dataLoadCoordinator with auto="true" to the view XML descriptor:

<facets>
    <dataLoadCoordinator auto="true"/>
</facets>

Working Modes

You can configure dataLoadCoordinator to work in the automatic, manual or semi-automatic mode.

Automatic Mode

In this mode, dataLoadCoordinator relies on parameter names with particular prefixes. The prefix denotes a component that provides the parameter value and sends value change events.

By default, the parameter prefix is container_ for data containers and component_ for visual components. The componentPrefix and containerPrefix attributes allow you to use different prefixes.

A loader is triggered on BeforeShowEvent if it has no parameters without recognized prefixes in its query text. It means that if the query contains an arbitrary parameter, for example select e from User e where e.department = :department, the loader will not be triggered automatically on view opening. You have to set the parameter value and invoke userDl.load() manually.

Parameters in query conditions do not prevent the loader to be triggered on BeforeShowEvent.

Manual Mode

In this mode, the nested refresh elements define when the data loaders must be triggered.

Semi-automatic Mode

When the auto attribute is set to true, and there are some manually configured triggers, DataLoadCoordinator will automatically configure all loaders having no manual configuration.

Attributes

You can view and edit facet attributes in Jmix Studio using the Jmix UI inspector panel.

  • auto - defines DataLoadCoordinator working mode. The default value is false.

  • componentPrefix - defines a prefix for parameters which refer to visual components from which DataLoadCoordinator will take parameter values in automatic mode. The default value is component_.

  • containerPrefix - defines a prefix for parameters which refer to data containers from which DataLoadCoordinator will take parameter values in automatic mode. The default value is container_.

Refresh Element

The refresh element allows you to define conditions for when a data loader must be refreshed.

The only attribute of this element is loader that defines the loader’s id.

The refresh element can have the following nested elements defining the triggering conditions:

  1. onComponentValueChanged - to trigger the loader when the value of a visual component is changed. It has the following attributes:

    • component - specifies the id of the visual component.

    • likeClause - if you use the like expression in query condition, you can define one of three possible search modes:

      • NONE - the default value.

      • CASE_SENSITIVE - case-sensitive search.

      • CASE_INSENSITIVE - case-insensitive search.

    • param - specifies the query parameter name.

  2. onContainerItemChanged - to trigger the loader when the current item in a data container is changed. It has the following attributes:

    • container - specifies the id of the data container.

    • param - specifies the query parameter name.

  3. onViewEvent - to trigger the loader on a view lifecycle event. It has the following attribute:

    • type - defines the type of the view event. Possible values:

      • Init - to trigger on InitEvent.

      • BeforeShow - to trigger on BeforeShowEvent.

      • Ready - to trigger on ReadyEvent.