The filter mission is to limit the set of records that will be displayed in the list (in any list: related list, open list, the dictionary). The filter is a set of conditions the record must meet to be on the list. Filters can be configured with the condition builder.
For example, we need to filter users living in Sevastopol. In SQL, we use the WHERE clause to filter records.
Filters components
Filters consist of the following components:
- Condition builder (and the breadcrumbs as its integral part);
- Search and sorting:
- Input field at the top of every column is used for searching;
- Click on the column title to sort the search results.
- Filter out/show matching (this item can be found in the context menu, to open it, right-click on the list cell).
All these components form the condition string, which is sent in the request as a GET parameter, and the filtered list of records will be returned and displayed.
The difference between condition builder on lists and regular condition builder is that breadcrumbs and sorting functionality added.
Breadcrumbs allow assessing the filter visually; also, they allow quick filter editing by navigation to the condition specified.
Sorting allows adding its conditions (ascending or descending) on one or more list fields.
How the filter works
To be more visual, let's take an example.
We need to find Alexander Egorov' closed tasks, sorted by priority.
For this, we will create such a filter on the task list (the task table):
After that. condition string can be found in the condition GET parameter:
list/task?condition=(((state=4^ORstate=5)^assigned_userLIKEAleksandr%20Egorov))^ORDERBYpriority
The condition string elements more closely:
| Element | Description |
|---|---|
| (state=4^ORstate=5) | State = 4 or State =5 (Closed Complete or Closed Incomplete) |
| subjectISNOTEMPTY | Subject is not empty |
| assigned_user.username=aleksandr_egorov | Username = Alexander Egorov |
| ^ORDERBYpriority | Records will be sorted by the priority fields in the ascending order. |
Dynamic Filters
Dynamic filters extend the filters by the JS scripts executing ability. This ability is available in the list condition builder and in the dynamic reference qualifier condition builder.
In Condition Builder, dynamic filters are available when selecting the reference field and the 'is dynamic' operator (system name is ISDYNAMIC). After this, the list of available dynamic filters will appear.
When executing the filter as a value of the condition using the 'is dynamic' operator, the value returned by the dynamic filter script will be used.
To create a new dynamic filter, please complete the following steps (a new record in the sys_filter_option_dynamic will be created):
- Navigate to the System Definition → Dynamic Filters;
- Click New, fill in the form and then click Save.
Dynamic filters form fields
| Field | Description |
|---|---|
| Title | The filter title. |
| Script | Enter the script that the dynamic filter runs. You can use all methods of server-side API classes here, After executing, the script should return the record ID or array of IDs. |
| Active | Select this checkbox to make the filter active. |
| Available for filter | Select this checkbox to make this filter available in the list filters. |
| Available for reference qualifier | Select this checkbox to make this filter available for a dynamic reference qualifier. |
| Order | Enter the number to define the order of filter processing. |
| Column type | The column type used in the filter. |
| Referenced table | Choose the table to apply this filter on. |
| Sys updated by | Information about who has updated the record. |
| Sys created by | Information about who has created the record. |
