# Dynamic Filtering

# Dynamic Filter Definition

Dynamic Filter is a customization displayed on list pages, used for users to quickly add filtering conditions to the list.

Its display effect is shown in the following figure:

Dynamic Filter Display Effect

The definition of dynamic filters can be maintained through the menu System Configuration > Forms > Filters. The creation and editing form is as follows:

The relevant field descriptions are as follows:

Field	Description
Organization	Belonging organization, can only be organizations that allow customization
Name	Name, unique within the organization, cannot be modified after creation
Label	Interface display name
Icon	Small icon displayed before the name when shown on the interface
Display sequence	The order of display on the interface, smaller values are displayed first
Description	Help information displayed when the mouse is placed on the name on the interface
Object type	Associated Domain type
Enable for roles	Restrict which users can see this dynamic filter, set to ROLE_USER if you want it available to all users
Is default	Whether it's the default filter, the default filter is automatically applied by the system when users enter the list page
Conditions	Filter condition definition

The definition of Condition uses a JSON format to describe matching rules, using the following format:

// 下面的动态过滤条件的说明：
// 1. 状态字段等于 SUCCESS
// 2. type 是 FINDER, UPDATE 中的一个
// Below is the description of the dynamic filter conditions:
// 1. The status field is equal to SUCCESS
// 2. type is one of FINDER, UPDATE
{
  // key 是列名称： status 
  // key is the column name: status 
  "status": {  
    // 过滤的目标列
    // The target column to filter
    "columnKey": "status", 
    // 匹配规则：等于
    // Match rule: equal
    "matchMode": "=",      
    // 匹配的目标值： SUCCESS
    // Matching target value: SUCCESS
    "value": "SUCCESS",   
  },
  "type": { // key 是列名称: type
    // 过滤的目标列, 与上一行的 key 相同
    // The target column to filter, same as the key in the previous line
    "columnKey": "type",           
    // 过滤的匹配规则：isOneOf (是其中某一个)
    // Filter matching rule: isOneOf (is one of them)
    // 过滤的目标值: [FINDER, UPDATE]
    // Matching target value: [FINDER, UPDATE]
    "value": ["FINDER", "UPDATE"]  
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Detailed descriptions of related patterns, rules, etc. for matching are as follows.

# Available Matching Modes

The following lists the available matching modes:

Matching Mode	Description	Applicable Data Types
=	Equal to	All types except one-to-many, many-to-many associations
!=	Not equal to	All types except one-to-many, many-to-many associations
>	Greater than	Numbers
<	Less than	Numbers
>=	Greater than or equal to	Numbers
<=	Less than or equal to	Numbers
after	Date, after ...	Date
before	Date, before ...	Date
afterOrEqual	Date, equal to ... or after ...	Date
beforeOrEqual	Date, equal to ... or before ...	Date
isOneOf	Is one of	All types except one-to-many, many-to-many associations
isNotAnyOf	Is not any of the list	All types except one-to-many, many-to-many associations
endsWith	Ends with ...	Characters
startsWith	Starts with ...	Characters
contains	Contains ...	Characters
notContains	Does not contain ...	Characters
hasNoRelated	This field does not contain related data	One-to-many association
hasRelated	This field contains related data	One-to-many association
isNotEmpty	Is not empty	All types except one-to-many, many-to-many associations
isEmpty	Is empty	All types except one-to-many, many-to-many associations

# Matching Different Field Types

# Matching Associations

One-to-many associations support matching of hasRelated and hasNoRelated, indicating whether the associated many-end has associated objects.
One-to-one associations support matching of =, !=, isOneOf, isNotAnyOf, isNotEmpty, isEmpty types.

# Matching Enum Fields

The matching value of Enum fields uses the name defined in Enum for matching. For example, for the following Enum definition, use ONLY_LABEL_FIELD, EXCLUDE_ARRAY_COLUMNS, ALL_COLUMNS these three values for matching:

enum FetchType {
  ONLY_LABEL_FIELD("Fetch label field"),
  EXCLUDE_ARRAY_COLUMNS("Fetch columns not of type array"),
  ALL_COLUMNS("Fetch all columns");
}

1
2
3
4
5

Matching Other Types of Fields

For boolean fields, use true and false without quotes directly as matching values
For number type fields, use numbers without quotes directly as matching values
If the matching value is required to be an array, use [] to enclose the matching values
For date-time matching, please use the following format: yyyy-MM-dd HH:mm:ss (2021-08-23 07:57:49)
For date matching without time, please use the following format: yyyy-MM-dd

TIP

The format of the conditions field in Dynamic Filter is consistent with the format of search conditions in search requests sent from the page to the backend.

During development, you can first use the search function on the interface, set the correct search conditions, then monitor the request data body in the POST search request sent from the page to the backend, and use this request data as the conditions field value for the predefined Dynamic Filter.

# Dynamic Matching Conditions

In the matching conditions of Dynamic Filter, the following dynamic matching conditions can be used:

Placeholder	Matching Condition Description
`${currentUsername}`	Username of the currently logged-in user
`${currentOrganization}`	Name of the organization to which the current user belongs
`${currentHour}`	Time of the current hour with zero minutes
`${currentDay}`	Time of zero o'clock on the current date
`${currentWeek}`	Zero o'clock on Monday of the current week
`${currentMonth}`	Zero o'clock on the first day of the current month
`${currentQuarter}`	Zero o'clock on the first day of the current quarter
`${currentYear}`	Zero o'clock on January 1st of the current year
`${currentUserGroups}`	List of names of all user groups to which the current user belongs

TIP

The current user's user groups are a list. When formatting as a filter condition, it will be formatted as ['groups', 'group2'], so it needs to be matched as a list. Here's an example using the isOneOf rule for matching:

"{
  "conditions": {
    "directFavoriteGroups.name": {
      "value": "${currentUserGroups}",
      "columnKey": "directFavoriteGroups.name",
      "matchMode": "isOneOf"
    }
  }
}"

1
2
3
4
5
6
7
8
9
10

# User-Defined Dynamic Filters

Users can save current search conditions as dynamic filters. Once saved, they will appear in the dynamic filter list, allowing users to filter data with just one click.

To create a custom dynamic filter:

Set up the desired search conditions on the list page.
Click the "Create dynamic filter" button.
In the pop-up dialog, enter a name for the filter and an optional description.
If you want this filter to be applied automatically when entering the page, check the "Is Default" option.
Click "Save" to save the new dynamic filter.

Once saved, the new dynamic filter will appear in the filter list at the top of the page. Users can quickly apply it by clicking on the filter name.

This custom dynamic filter feature allows users to quickly access frequently used search conditions, improving work efficiency.

← 📃 Basic Forms 🎛️ Dynamic Fields →