# 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:

Dynamic Filter Creation and Editing

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:

  1. Set up the desired search conditions on the list page.
  2. Click the "Create dynamic filter" button.
  3. In the pop-up dialog, enter a name for the filter and an optional description.
  4. If you want this filter to be applied automatically when entering the page, check the "Is Default" option.
  5. 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.

Last Updated: 9/29/2024, 2:33:14 AM