dataLoadCoordinator

ДЕМО

Фасет dataLoadCoordinator предназначен для запуска загрузчиков данных и для декларативной привязки загрузчиков данных к контейнерам данных, визуальным компонентам и событиям жизненного цикла экрана.

Основное использование

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

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

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

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

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

В автоматическом режиме (auto="true"), dataLoadCoordinator запускает каждый загрузчик, для которого может предоставить значения параметров на событии BeforeShowEvent экрана. Фасет может автоматически сопоставлять параметры в запросе загрузчика со значениями, полученными из контейнеров или визуальных компонентов. Чтобы указать источник, добавьте соответствующий префикс к имени параметра: используйте container_ для значений, получаемых из контейнера, и component_ для значений, получаемых из визуального компонента. Например, параметр container_citiesDc получает своё значение из контейнера citiesDc.

Префиксы по умолчанию можно изменить с помощью атрибутов componentPrefix и containerPrefix

Если запрос содержит произвольный параметр без префикса — например, select e from User e where e.city = :city — фасет не сможет его сопоставить, и загрузчик не будет запущен автоматически. В этом случае необходимо самостоятельно установить значение параметра и вызвать userDl.load(). Добавление произвольных параметров внутри дополнительного условия не препятствует выполнению основного запроса загрузчика.

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

<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 Контейнер данных – содержит сущность City. Его значение будет использовано в параметре :container_citiesDc.
2 Запрос для сущности City – не содержит параметров и будет выполнен на событии BeforeShowEvent.
3 Дополнительное условие – добавляется к основному запросу, когда пользователь вводит значение в nameField.
4 Запрос для сущности Customer – перезагружает строки Customer каждый раз, когда меняется выбранное значение в контейнере citiesDc.
5 Фасет в автоматическом режиме – автоматически координирует выполнение загрузчиков, обеспечивая правильный порядок выполнения запросов.
6 Поле ввода – текстовый компонент nameField, значение которого привязано к параметру :component_nameField.

Ручной режим

В ручном режиме (auto = false) фасет больше не выполняет автоматических действий. Для осуществления загрузки необходимо будет указать событие экрана при наступлении которого фасет будет запускать загрузчик (например, InitEvent), и задать источник каждого параметра запроса — будь то визуальный компонент или контейнер данных. Эти параметры можно задать с помощью вложенных элементов <refresh>.

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

<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 Контейнер данных – содержит сущность City. Его значение будет использовано в параметре :city.
2 Запрос для сущности City – не содержит параметров и будет выполнен на событии InitEvent согласно ручной конфигурации.
3 Дополнительное условие – добавляется к основному запросу, когда пользователь вводит значение в nameField.
4 Запрос для сущности Customer – перезагружает строки Customer каждый раз, когда меняется выбранное значение в контейнере citiesDc.
5 Фасет в ручном режиме – загрузка контролируется правилами, определёнными в элементах <refresh>.
6 Элемент <refresh> – вызывает загрузчик citiesDl на событии InitEvent, либо когда содержимое компонента nameField передано в параметр name.
7 Элемент <refresh> – вызывает customersDl, при изменении выбранного экземпляра в citiesDc, передавая этот город как параметр city.
8 Поле ввода – текстовый компонент nameField чье значение привязано к параметру city через элемент <refresh>.

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

Фасет можно установить в полуавтоматический режим. В этом режиме координатор автоматически запускает загрузчики (с auto = "true"), но также учитывает любые добавленные вами ручные правила.

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

<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 Фасет в полуавтоматическом режиме – фасет будет автоматически запускать загрузчики, если для них не определены иные правила.
2 Элемент <refresh> – переопределяет автоматическое поведение, указывая, что загрузчик citiesDl должен запускаться в момент генерации события ReadyEvent.

Атрибуты

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

  • 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 - указывает имя параметра запроса.

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

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

    • param - указывает имя параметра запроса.

      1. onViewEvent - запуска загрузчика на событии жизненного цикла экрана. Он имеет следующий атрибут:

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

      • Init - для запуска на событии InitEvent.

      • BeforeShow - для запуска на событии BeforeShowEvent.

      • Ready - для запуска на событии ReadyEvent.

См. также

Следующие онлайн-примеры демонстрируют dataLoadCoordinator в действии: