DataLoadCoordinator

DataLoadCoordinator facet 支持触发数据加载,以及声明式的将数据加载器和数据容器、可视化组件、界面事件进行连接。

组件的 XML 名称:dataLoadCoordinator

基本用法

如需在界面的 BeforeShowEvent 或 fragment 的 AttachEvent 事件触发所有的数据加载器,只需在界面的 XML 描述中添加 DataLoadCoordinator,其属性 auto="true"

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

工作模式

可以配置 DataLoadCoordinator 在自动、手动或半自动模式下工作。

自动模式

此模式中,DataLoadCoordinator 依赖使用特定前缀的参数名称。前缀表示提供参数和事件的组件。如果加载器的查询语句中没有参数(尽管在查询条件中可能有参数),则该加载器会在 界面 的`BeforeShowEvent` 或 界面 fragmentAttachEvent 中自动刷新。

默认情况下,数据容器的参数前缀是 container_,可视化组件的参数前缀是 component_。通过 componentPrefixcontainerPrefix 属性可以使用不同的前缀。

示例:

<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 添加支持 JPQL 条件的 schema。
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 添加支持 JPQL 条件的 schema。
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 - 在界面事件中触发加载器。有下列属性:

    <dataLoadCoordinator>
        <refresh loader="citiesDl">
            <onScreenEvent type="BeforeShow"/>
        </refresh>
    </dataLoadCoordinator>
  4. onFragmentEvent - 在 fragment 事件中触发加载器。有下列属性:

    • type - 定义界面 fragment 事件的类型,可能值:

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

XML 属性

可以在 Studio 界面设计器中的 Component Inspector 面板查看和编辑 facet 支持的属性。

DataLoadCoordinator XML 元素

Refresh XML 属性