DataLoadCoordinator

DataLoadCoordinator – это фасет, предназначенный для запуска загрузчиков данных и для декларативного связывания загрузчиков данных с контейнерами данных, визуальными компонентами и событиями экрана.

XML-имя компонента: dataLoadCoordinator.

Основы использования

Чтобы запустить все загрузчики данных в BeforeShowEvent экрана или AttachEvent фрагмента, просто добавьте DataLoadCoordinator с auto="true" в XML-дескриптор экрана:

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

Режимы работы

DataLoadCoordinator может работать в автоматическом, ручном или полуавтоматическом режиме.

Автоматический режим

В этом режиме DataLoadCoordinator полагается на имена параметров, имеющие специальные префиксы. Префикс указывает, какой компонент является источником значения параметра и событий его изменения.

По умолчанию используется префикс container_ для контейнеров данных и component_ для визуальных компонентов. Атрибуты componentPrefix и containerPrefix позволяют использовать другие префиксы.

При автоматической конфигурации, если у загрузчика нет параметров в основном тексте запроса (то есть в статическом запросе не включающем условия), то он срабатывает по событию BeforeShowEvent в Screen или по событию attachEvent в ScreenFragment.

Если в основном тексте запроса задать параметр без префикса container_ или component_, то автоматическая конфигурация проигнорирует этот загрузчик.

Для запуска такого загрузчика можно просто задать значения параметров и вызвать метод load() за объекте загрузчика программно.

Пример использования:

<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 Добавляет XML-схему для условий JPQL.
2 В запросе нет параметров, поэтому загрузчик citiesDl сработает на событие BeforeShowEvent.
3 Загрузчик citiesDl также сработает на изменение значения компонента nameField. Так как условие использует оператор like, значение будет автоматически завернуто в '(?i)% %' для того, чтобы обеспечить нечувствительный к регистру поиск.
4 Загрузчик customersDl сработает при смене выбранной сущности в контейнере citiesDc.

Ручной режим

В этом режиме вложенные элементы refresh определяют, когда должны сработать загрузчики.

Пример использования:

<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 Добавляет XML-схему для условий JPQL.
2 Загрузчик citiesDl сработает на событие InitEvent.
3 Загрузчик citiesDl также сработает на изменение значения компонента nameField. Атрибут likeClause приводит к заворачиванию значения в '(?i)% %' для того, чтобы обеспечить нечувствительный к регистру поиск.
4 Загрузчик customersDl сработает при смене выбранной сущности в контейнере citiesDc.

Полуавтоматический режим

Когда атрибут auto установлен в true и объявлены некоторые вручную сконфигурированные связи, DataLoadCoordinator автоматически сконфигурирует все загрузчики, для которых не указано ни одной связи вручную.

Пример использования:

<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="AfterShow"/> (2)
            </refresh>
        </dataLoadCoordinator>
    </facets>
    <layout>
    </layout>
</window>
1 Загрузчик customersDl сконфигурирован автоматически и сработает при смене выбранной сущности в контейнере brandsDc.
2 Загрузчик brandsDl сконфигурирован вручную и сработает на событие экрана AfterShowEvent.

Атрибуты

  • auto - определяет режим работы DataLoadCoordinator. Значение по умолчанию – false.

  • componentPrefix - определяет префикс для параметров, обозначающих визуальные компоненты, из которых DataLoadCoordinator будет принимать значения параметров в автоматическом режиме. Значение по умолчанию – component_.

  • containerPrefix - определяет префикс для параметров, обозначающих контейнеры данных из которых DataLoadCoordinator будет принимать значения параметров в автоматическом режиме. Значение по умолчанию – container_.

Элемент refresh

Элемент refresh позволяет определить условия, при которых должен сработать загрузчик данных.

Единственным атрибутом этого элемента является loader, определяющий id загрузчика.

Элемент refresh может содержать следующие вложенные элементы, определяющие условия срабатывания:

  1. onComponentValueChanged – загрузчик срабатывает при изменении значения визуального компонента. Этот элемент имеет следующие атрибуты:

    • component - задает id визуального компонента.

    • likeClause - если в условии запроса используется выражение like, можно задать один из трех возможных режимов поиска:

      • NONE - значение по умолчанию.

      • CASE_SENSITIVE - заглавные и строчные буквы обрабатываются как различные.

      • CASE_INSENSITIVE - заглавные и строчные буквы обрабатываются как эквивалентные.

    • param - задает имя параметра запроса.

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

  2. onContainerItemChanged - загрузчик срабатывает при изменении текущего элемента в контейнере данных. Этот элемент имеет следующие атрибуты:

    • container - задает id контейнера данных.

    • param - задает имя параметра запроса.

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

  3. onScreenEvent - загрузчик срабатывает по событию экрана. Этот элемент имеет следующие атрибуты:

    • type - определяет тип экранного события. Возможные значения:

    <dataLoadCoordinator>
    <refresh loader="citiesDl">
        <onScreenEvent type="BeforeShow"/>
    </refresh>
</dataLoadCoordinator>
    Триггеры onScreenEvent срабатывают после слушателей соответствующих событий, заданных в контроллере экрана аннотациями @Subscribe.

  4. onFragmentEvent - загрузчик срабатывает по событию фрагмента экрана. Этот элемент имеет следующий атрибут:

    • type - определяет тип события фрагмента. Возможные значения:

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

Все XML-атрибуты

Вы можете просматривать и редактировать применимые к фасету атрибуты с помощью панели инспектора Jmix UI в дизайнере экранов Studio.

auto - componentPrefix - containerPrefix - id

XML-элементы DataLoadCoordinator

refresh

XML-атрибуты Refresh

loader

XML-элементы Refresh

onComponentValueChanged - onContainerItemChanged - onScreenEvent - onFragmentEvent