Related Items Selector Block – searching and linking records¶
The related items selector lets the user search for records and link them to the record of the form through a relationship. It is the block for setting a relationship; the other related items blocks only show what is already linked.
This page is part of the form block reference.
1. At a glance¶
| Purpose | Search records of the related entity and link or unlink them |
| Typical use | The customer of a ticket, the assignees of a task, tags or languages of an article |
| Related | Related Items Grid Block, Queries |
The block is only offered in forms that belong to an entity.
2. Settings¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Relationship" | The relationship through which records are linked | Required |
| "Available Items Form" | Form of the related entity each suggestion is drawn with | Required. Without it the block shows nothing. |
| "Linked Items Form" | Form a linked record is drawn with | none – the text of "Linked Item Text" is shown |
| "Linked Item Text" | What a linked record reads as, evaluated against that record – for example its name | the record id, which nobody can read – set it unless a linked items form is set |
| "Query" | A query that narrows which records can be found. Offered once a relationship is chosen. | every record of the related entity |
| "Quick Filters" | A filter definition whose badges and sort options are offered above the suggestions. Only query filters are offered. | none |
| "Allow Multiple Records" | Several records can be linked. Has to match what the relationship allows. | off |
| "Variant" | Field: a bordered input like any other field. Ghost: linked records as pills with a remove button each, followed by a round add button that opens the search. | Field |
| "Max Suggestions" | Number of suggestions loaded per search | 30 |
| "Allow Load More" | Offers a "Load more..." entry when the limit was reached | off |
| "Permit Empty Search" | Also searches with an empty search term: suggestions appear as soon as the control is focused | off – nothing is searched while the field is empty |
| "Label", "Show label" | Caption and the condition under which it is shown | none, shown |
| "Placeholder" | Hint text in the empty search field | none |
| "Tooltip" | Text shown when the pointer rests on the block | none |
| "Max Items" | With "Allow Multiple Records": how many records can be linked at most. Once reached, the search field disappears until a record is removed. | no limit |
| "Linked Item Height" | Height of one linked entry as a CSS length | the entry's own height |
| "Disabled" | Condition under which nothing can be linked or unlinked | not disabled |
| "Focus On Open", "Skip In Tab Order" | Places the cursor into the search field when the form opens; lets the Tab key pass over it. See Cursor and tab key. | never, off |
In addition, the block has the settings every block has, including "Flush".
3. Behaviour¶
- Searching: the suggestions are loaded only when the user opens the control or types – never with the form. The search term is applied as a full-text search on top of the query: every word has to occur. The related entity therefore has to take part in full-text search (see Entities and fields).
- Empty search: without "Permit Empty Search", an empty search field shows nothing, and quick filters alone do not start a search. Switch it on where the set to choose from is small and users want to browse it; leave it off for entities with many records.
- Load more: fetches the next page for the same term and appends it.
- Query: expressions in the conditions of the query can read the record of the form; field references on the left side refer to the related entity.
- Linking and unlinking change the relationship of the record; they are stored when the record is saved.
- Without "Allow Multiple Records", the search field disappears while a record is linked; the user removes it first to choose another one.
4. Examples¶
Customer of a ticket. "Relationship" = "Ticket → Customer", "Available Items Form" = "Customer Suggestion" (name, city, customer number), "Linked Item Text" = the field "Name", "Query" = only active customers.
Tags of an article. "Relationship" = "Article → Tags", "Allow Multiple Records" on, "Variant" = Ghost, "Permit Empty Search" on (there are only 40 tags).