DataLoadCoordinator

DataLoadCoordinator facet is designed for declarative linking of data loaders to data containers, visual components, and screen events.

Component’s XML-name: dataLoadCoordinator.

Attributes

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

  • componentPrefix - defines a special prefix for the component, on which DataLoadCoordinator will rely in automatic working mode. The default value is component_.

  • containerPrefix - defines a special prefix for the container, on which DataLoadCoordinator will rely in automatic working mode. The default value is container_.

Refresh Element

Refresh is a nested element that allows you to define the loader to which the current DataLoadCoordinator will be bound.

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

It has four subelements to define the trigger for a refresh:

1. onComponentValueChanged - has the following attributes:

  • component - specifies the id of the component to which the trigger will be bound.

  • 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 - uppercase and lowercase letters are treated as distinct.

    • CASE_INSENSITIVE - uppercase and lowercase letters are treated as equivalent.

  • param - defines the parameter name for the query.

<dataLoadCoordinator>
    <refresh loader="citiesDl">
        <onComponentValueChanged component="nameField"
                                 likeClause="CASE_SENSITIVE"
                                 param="name"/>
    </refresh>
</dataLoadCoordinator>

2. onContainerItemChanged - has the following attributes:

  • container - this attribute specifies the id of the container to which the trigger will be bound.

  • param - defines the parameter name for the query.

<dataLoadCoordinator>
    <refresh loader="citiesDl">
        <onContainerItemChanged container="citiesDc"
                                param="name"/>
    </refresh>
</dataLoadCoordinator>

3. onScreenEvent - has the following attribute:

<dataLoadCoordinator>
    <refresh loader="citiesDl">
        <onScreenEvent type="BeforeShow"/>
    </refresh>
</dataLoadCoordinator>

4. onFragmentEvent - has the following attribute:

<dataLoadCoordinator>
    <refresh loader="citiesDl">
        <onFragmentEvent type="Init"/>
    </refresh>
</dataLoadCoordinator>

Working Modes

You can configure DataLoadCoordinator to work in three modes:

  1. In automatic mode.

  2. In manual mode.

  3. In semi-automatic mode.

Automatic Mode

In this mode, DataLoadCoordinator relies on parameter names with particular prefixes. The prefix denotes a component that produces the parameter value and changes events. If the loader has no parameters in its query text, although it can have parameters in query conditions, it is refreshed on BeforeShowEvent in Screen or AttachEvent in ScreenFragment.

Usage example:

<window caption="msg://automaticModeScreen.caption"
        xmlns="http://jmix.io/schema/ui/window"
        xmlns:c="http://jmix.io/schema/ui/jpql-condition"> (1)
    <data readOnly="true">
        <collection id="citiesDc"
                    class="ui.ex1.entity.City">
            <fetchPlan extends="_base"/>
            <loader id="citiesDl">
                <query>
                    <![CDATA[select e from uiex1_City e]]> (2)
                    <condition>
                        <and>
                            <c:jpql>
                                <c:where>e.name like :component_nameField</c:where> (3)
                            </c:jpql>
                        </and>
                    </condition>
                </query>
            </loader>
        </collection>
        <collection id="customersDc"
                    class="ui.ex1.entity.Customer">
            <fetchPlan extends="_base"/>
            <loader id="customersDl" >
                <query>
                    <![CDATA[
                        select e from uiex1_Customer e
                            where e.city = :container_citiesDc
                    ]]> (4)
                </query>
            </loader>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="true"/>
    </facets>
    <layout>
        <textField id="nameField"/>
    </layout>
</window>
1 Add XML schema for jpql conditions.
2 There are no parameters in the query, so the brandsDl loader will be triggered on BeforeShowEvent.
3 The brandsDl loader will also be triggered on nameField component value change. As the condition uses the like clause, the value will be automatically wrapped in '(?i)% %' to provide the case-insensitive search.
4 The customersDl is triggered on the brandsDc data container item change.

Manual Mode

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

Usage example:

<window caption="msg://manualModeScreen.caption"
        xmlns="http://jmix.io/schema/ui/window"
        xmlns:c="http://jmix.io/schema/ui/jpql-condition"> (1)
    <data readOnly="true">
        <collection id="citiesDc"
                    class="ui.ex1.entity.City">
            <fetchPlan extends="_base"/>
            <loader id="citiesDl">
                <query>
                    <![CDATA[select e from uiex1_City e]]>
                    <condition>
                        <and>
                            <c:jpql>
                                <c:where>e.name like :name</c:where>
                            </c:jpql>
                        </and>
                    </condition>
                </query>
            </loader>
        </collection>
        <collection id="customersDc"
                    class="ui.ex1.entity.Customer">
            <fetchPlan extends="_base"/>
            <loader id="customersDl" >
                <query>
                    <![CDATA[
                        select e from uiex1_Customer e
                            where e.city = :city
                    ]]>
                </query>
            </loader>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator>
            <refresh loader="citiesDl">
                <onScreenEvent type="Init"/> (2)
                <onComponentValueChanged component="nameField"
                                         likeClause="CASE_INSENSITIVE"
                                         param="name"/> (3)
            </refresh>
            <refresh loader="customersDl">
                <onContainerItemChanged container="citiesDc"
                                        param="city"/> (4)
            </refresh>
        </dataLoadCoordinator>
    </facets>
    <layout>
        <textField id="nameField"/>
    </layout>
</window>
1 Add XML schema for JPQL conditions.
2 The citiesDl loader will be triggered on InitEvent.
3 The citiesDl loader will also be triggered on the nameField component value change. The likeClause attribute causes the value to be wrapped in '(?i)% %' to provide the case-insensitive search.
4 The customersDl will be triggered on the citiesDc data container item change.

Semi-automatic Mode

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

Usage example:

<window caption="msg://semiAutomaticModeScreen.caption"
        xmlns="http://jmix.io/schema/ui/window">
    <data readOnly="true">
        <collection id="brandsDc"
                    class="ui.ex1.entity.Brand">
            <fetchPlan extends="_base"/>
            <loader id="brandsDl">
                <query>
                    <![CDATA[select e from uiex1_Brand e]]>
                </query>
            </loader>
        </collection>
        <collection id="customersDc"
                    class="ui.ex1.entity.Customer">
            <fetchPlan extends="_base"/>
            <loader id="customersDl" >
                <query>
                    <![CDATA[
                        select e from uiex1_Customer e
                            where e.favouriteBrands = :container_brandsDc
                    ]]> (1)
                </query>
            </loader>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="true">
            <refresh loader="brandsDl">
                <onScreenEvent type="BeforeShow"/> (2)
            </refresh>
        </dataLoadCoordinator>
    </facets>
    <layout>
    </layout>
</window>
1 The customersDl is configured automatically and triggered on the brandsDc data container item change.
2 The brandsDl loader is configured manually and will be triggered on BeforeShowEvent.

All XML Attributes

You can view and edit attributes applicable to the facet using the Component Inspector panel of the Studio’s Screen Designer.

DataLoadCoordinator XML Elements

Refresh XML Attributes