Filters – quick filters and sort options above a listing¶
A filter offers users named quick filters ("Open", "Assigned to me", "Overdue") as badges above a grid or list, and a dropdown of sort options next to them. The administrator decides which quick filters and sort options exist; the user switches them on and off. This chapter describes the two kinds of filters, their settings and where they can be used.
It is intended for administrators who design grids, lists and forms.
1. Filters at a glance¶
A filter belongs to one entity and is only offered to grids, lists and blocks of that entity. It is never shown on its own – a grid, a list, a form block or the global search refers to it.
| Part | Shown as | User action |
|---|---|---|
| Quick filter | A badge above the listing, with label and optional icon | Click to switch it on or off. An active badge is filled. |
| Reset | A small cross after the badges ("Show everything") | Switches all quick filters off |
| Sort options | A dropdown with a sort icon next to the badges. The first entry is "Default order". | Pick an order |
| Record counts | A number on each badge (optional) | – |
A filter is not a query¶
A query decides which records a listing contains. A filter narrows that set further, at the user's choice, and can be switched off again.
- "This grid shows open incidents" → a condition of the query.
- "The user should be able to limit the grid to the open ones" → a quick filter.
Summary¶
- There are two kinds of filters: query filters and expression filters. The kind follows from where the listing gets its records, and it cannot be changed later (section 2).
- Quick filters are combined with And when several are active.
- A sort option sorts by one field.
- The user's selection is not remembered: when the page is loaded again, the listing starts with the quick filters that are active by default.
2. Query filter or expression filter¶
| Query filter | Expression filter | |
|---|---|---|
| Condition of a quick filter | Query clauses – the same conditions as in a query | An expression that returns yes/no for each record |
| Evaluated | By the database, as part of the query of the listing | By nexxcite, for every record that is already loaded |
| Use it on | Grids, lists, the related items selector, the global search of an entity | Related items grids, lists and timelines in forms |
The two kinds are not interchangeable:
- A query filter cannot see the records of a related items block completely. These records come from the relationship, and records added in the form are not saved yet – a query would not find them.
- An expression filter cannot become part of a query. On a grid that pages through a query, every record would have to be loaded first, which would end paging and the total record count.
The rule behind this applies throughout nexxcite: query conditions are evaluated by the database, expressions after the records have been loaded.
Where a filter is selected, only filters of the fitting kind and entity are offered. A filter of the wrong kind that is referenced anyway is rejected at runtime and its badges are not shown.
3. Creating a filter¶
Filters are managed under Admin Studio → Design → Filters, grouped by entity.
- Select the entity group.
- Add a filter with "Query Filter" or "Expression Filter". The kind is chosen here and cannot be changed afterwards.
- The "Filter Editor" opens. A note below the header names the kind and where it can be used.
- Add quick filters and sort options and save.
Permissions¶
| Permission | Allows |
|---|---|
| "Open Filter Manager" | Opening Admin Studio → Design → Filters |
| "Add Filter" | Creating filters |
| "Edit Filter" | Changing filters |
| "Delete Filter" | Deleting filters |
By default, these permissions are part of "System Developer".
4. Settings¶
General¶
| Setting | Meaning | Default |
|---|---|---|
| "Combine filters" | When on, the user can activate several badges at once; their conditions are combined with And. When off, picking a badge replaces the active one. | off |
| "Allow no filter" | When on, the user can switch every badge off and see the unfiltered listing. When off, one badge is always active – a click on the only active badge does nothing. | on |
| "Show counts" | Shows on every badge how many records it would leave (section 6) | off |
Quick filters¶
Every quick filter is a card in the list "Quick filters". Collapsed, it shows a preview of the badge and a short description of its condition. "Add quick filter" adds one; the cards can be moved and removed.
| Setting | Meaning | Default |
|---|---|---|
| "Label" | The text of the badge. Usually a fixed text; an expression is possible, for example for translated texts. | – |
| "Icon" | Optional icon in front of the label – an icon of an icon font or an uploaded image | – |
| "Active by default" | The listing opens with this quick filter already active | off |
| "Condition" | Query filter: query clauses, edited like a query. Expression filter: an expression that returns yes/no. | – |
A badge needs a label, an icon or both. A quick filter without a condition does nothing when it is switched on.
Sort options¶
| Setting | Meaning | Default |
|---|---|---|
| "Label" | The text of the entry in the sort dropdown | – |
| "Field" | The field the records are sorted by – a field of the filter's entity | – |
| "Direction" | "Ascending" or "Descending" | "Ascending" |
| "Default" | The entry the dropdown starts on. Only the first entry marked this way counts. | off |
Without sort options, the dropdown is not shown. A filter needs at least one quick filter or one sort option, otherwise nothing is shown above the listing.
5. Behaviour¶
Which badges are active¶
When the listing is opened:
- Every quick filter marked "Active by default" is active.
- Without "Combine filters", only the first of them stays active.
- Without "Allow no filter" and without any default, the first quick filter is activated.
Applying the selection¶
- Query filter: The conditions of the active quick filters are added to the query of the listing with And. The query itself keeps its own conditions; the filter only narrows the result. Paging and the total record count stay correct.
- Expression filter: The condition is evaluated for every record of the block. Records for which it does not return yes are hidden. Unsaved records of the form are included.
- Sort option: The selected option replaces the order of the listing. "Default order" returns to the order the listing had without a sort option.
The label and icon expressions are evaluated once when the listing is shown – in a form, for the record of the form – not for every listed record.
6. Record counts¶
| Kind | Behaviour |
|---|---|
| Query filter | Only with "Show counts". Each badge costs one count query, repeated whenever the selection changes. Worth it on a listing users scan; expensive on large tables. |
| Expression filter | Only with "Show counts" as well. The records are loaded anyway, so counting costs practically nothing. |
Each badge is counted on its own against the unfiltered listing, not combined with the other active badges. The number on a badge therefore does not change when another badge is clicked.
7. Where filters are used¶
| Place | Setting | Kind |
|---|---|---|
| Grid | "Filter" | Query filter |
| List | "Filter" – often the only way to reorder a list, as it has no column headers | Query filter |
| Related items grid (form block) | "Quick Filters" | Expression filter |
| Related items list (form block) | "Quick Filters" | Expression filter |
| Related items timeline (form block) | "Quick Filters" – badges only | Expression filter |
| Related items selector (form block) | "Quick Filters" – this block searches the database | Query filter |
| Entity | "Global Search Quick Filters" – above the global search results of the entity | Query filter |
A grid that is shown inside a related items block does not use its own filter there – the block brings its own expression filter.
Quick filters and block filters¶
Related items blocks also have a setting "Filter" with an expression. That one is always active and invisible to the user: it decides which related records belong in the block at all. The quick filters of a filter definition narrow what is left over. Do not use the block filter for something the user should control, and do not use a quick filter for something the user should not see.
8. Examples¶
Tickets grid (query filter on "Ticket"):
| Quick filter | Condition | Active by default |
|---|---|---|
| "Open" | "Status" NotEquals Closed |
on |
| "Assigned to me" | "Assigned to" Equals system function CurrentUserRecId |
off |
| "Created this week" | Date part clause "Created on" "Within the last X days", number 7 |
off |
Settings: "Combine filters" on, "Allow no filter" on. Sort options "Newest first" ("Created on", Descending, Default) and "Priority" ("Priority", Ascending).
Tasks in a project form (expression filter on "Task"): quick filter "Not done" with the condition
"Status" NotEquals Done; quick filter "Mine" with the condition "Assigned to" Equals system
function CurrentUserRecId.
9. Limitations¶
- A sort option sorts by exactly one field of the filter's entity. Sorting by several fields ("priority, then date") and by fields of related records is not possible.
- The selection of the user is not remembered across page loads.
- The kind of a filter cannot be changed. To switch, create a new filter.
10. Frequently asked questions¶
Why are the badges of my filter not shown? Usually the filter has the wrong kind for the place – an expression filter on a grid or a query filter on a related items grid – or it belongs to another entity. Only fitting filters are offered for selection; check filters that were assigned in another way.
Can a quick filter refer to the current user?
Yes. Use the system function CurrentUserRecId (or another expression) on the right side of a clause
or in the condition expression.
Do quick filters bypass the permissions of the user? No. A query filter only adds conditions to a query that already contains the read limits of the user. An expression filter only hides records the block has already loaded.