dataLoadCoordinator

LIVE DEMO

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 at 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 automatic mode (auto="true"), dataLoadCoordinator triggers every loader it can provide parameter values for on BeforeShowEvent. The facet can automatically match parameters in the loader query to values that come from containers or visual components. To indicate the source, prepend the appropriate prefix to the parameter name: use container_ for values taken from a container and component_ for values taken from a visual component. For example, a parameter named container_citiesDc takes its value from the citiesDc container.

You can change the default prefixes with the componentPrefix and containerPrefix attributes.

If a query contains an arbitrary parameter without a prefix — e.g., select e from User e where e.city = :city — the facet won’t be able to match it, so the loader won’t be triggered automatically. In that case you must set the parameter value yourself and call userDl.load(). Adding arbitrary parameters within a query condition does not prevent the loader’s main query from running.

Usage example:

<view xmlns="http://jmix.io/schema/flowui/view"
      title="msg://automaticModeView.title">
    <data>
        <collection id="citiesDc" class="com.company.onboarding.entity.City"> (1)
            <loader id="citiesDl" readOnly="true">
                <query>
                    <![CDATA[select e from City e]]> (2)
                    <condition>
                        <and>
                            <jpql>
                                <where>e.name like:component_nameField</where> (3)
                            </jpql>
                        </and>
                    </condition>
                </query>
            </loader>
            <fetchPlan extends="_base"/>
        </collection>
        <collection id="customersDc"
                    class="com.company.onboarding.entity.Customer">
            <loader id="customersDl" readOnly="true">
                <query>
                    <![CDATA[
                    select e from Customer e
                    where e.city = :container_citiesDc]]> (4)
                </query>
            </loader>
            <fetchPlan extends="_base"/>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="true"/> (5)
    </facets>
    <layout>
        <textField id="nameField"/> (6)
    </layout>
</view>
1 Data container – holds the City entity. Its value is used as the :container_citiesDc parameter.
2 City query – includes no parameters and will execute on BeforeShowEvent.
3 Query condition – is appended to the city query when the user enters a value in nameField.
4 Customer query – reloads Customer rows each time the selected value in the citiesDc container changes.
5 Facet set to automatic mode – automatically coordinates loader execution, ensuring queries are run in the correct order.
6 Input field – the nameField text component whose value is bound to the :component_nameField in the city query.

Manual Mode

In manual mode (auto = false) the facet no longer performs any automatic actions. You must specify the exact view event that triggers the loader (for instance,InitEvent) and specify the origin of every query parameter, whether it’s a component value or a container value. These details are provided through <refresh> elements placed within the facet declaration.

Usage example:

<view xmlns="http://jmix.io/schema/flowui/view"
      title="msg://manualModeView.title">
    <data>
        <collection id="citiesDc" class="com.company.onboarding.entity.City"> (1)
            <loader id="citiesDl" readOnly="true">
                <query>
                    <![CDATA[select e from City e]]> (2)
                    <condition>
                        <and>
                            <jpql>
                                <where>e.name like:name</where> (3)
                            </jpql>
                        </and>
                    </condition>
                </query>
            </loader>
            <fetchPlan extends="_base"/>
        </collection>
        <collection id="customersDc"
                    class="com.company.onboarding.entity.Customer">
            <loader id="customersDl" readOnly="true">
                <query>
                    <![CDATA[
                    select e from Customer e
                    where e.city = :city]]> (4)
                </query>
            </loader>
            <fetchPlan extends="_base"/>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="false"> (5)
            <refresh loader="citiesDl">
                <onViewEvent type="Init"/>
                <onComponentValueChanged component="nameField"
                                         likeClause="CASE_INSENSITIVE"
                                         param="name"/> (6)
            </refresh>
            <refresh loader="customersDl">
                <onContainerItemChanged container="citiesDc"
                                        param="city"/> (7)
            </refresh>
        </dataLoadCoordinator>
    </facets>
    <layout>
        <textField id="nameField"/> (8)
    </layout>
</view>
1 Data container – holds the City entity. Its value is used as the city parameter in the customer query.
2 City query – includes no parameters and will execute on InitEvent as per manual configuration.
3 Query condition – is appended to the query when the user enters a value in nameField.
4 Customer query – reloads Customer instances each time the selected value in the citiesDc container changes.
5 Manual facet mode – loading is controlled by the rules defined in the <refresh> elements.
6 City loader refresh condition – triggers a refresh of citiesDl on InitEvent and when the content of the nameField component passing its input as the name parameter.
7 Customer loader refresh condition – triggers a refresh of customersDl when the selected item in citiesDc container changes, passing that city as the city parameter.
8 Input field – the nameField text component whose value is bound to the City query via a <refresh> element.

Semi-automatic Mode

The facet can be set to semiautomatic mode. In this mode the coordinator triggers loaders automatically (with auto = "true"), but also respects any manual rules you add.

Usage example:

<view xmlns="http://jmix.io/schema/flowui/view"
      title="msg://semiautomaticModeView.title">
    <data>
        <collection id="citiesDc" class="com.company.onboarding.entity.City">
            <loader id="citiesDl" readOnly="true">
                <query>
                    <![CDATA[select e from City e]]>
                </query>
            </loader>
            <fetchPlan extends="_base"/>
        </collection>
        <collection id="customersDc"
                    class="com.company.onboarding.entity.Customer">
            <loader id="customersDl" readOnly="true">
                <query>
                    <![CDATA[
                    select e from Customer e
                    where e.city = :container_citiesDc]]>
                </query>
            </loader>
            <fetchPlan extends="_base"/>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="true"> (1)
            <refresh loader="citiesDl">
                <onViewEvent type="Ready"/> (2)
            </refresh>
        </dataLoadCoordinator>
    </facets>
    <layout>

        // ...

    </layout>
</view>
1 Facet set to semiautomatic mode – the facet will automatically trigger loaders unless overridden by manual rules.
2 City loader refresh condition – specifies that the citiesDl loader should be triggered when the view fires ReadyEvent.

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.

See Also

Explore the following online examples to see dataLoadCoordinator in action: