Record Finder Field
Form Widget
recordfinder
- renders a field with details of a related record. Expanding the field displays a popup list to search large amounts of records. Supported by singular relationships only.
user:
label: User
type: recordfinder
list: ~/plugins/rainlab/user/models/user/columns.yaml
The following field properties are supported and commonly used.
Property | Description |
---|---|
label | a name when displaying the form field to the user. |
default | specifies a default string value, optional. |
comment | places a descriptive comment below the field. |
keyFrom | the name of column to use in the relation used for key. Default: id . |
nameFrom | the column name to use in the relation used for displaying the name. Default: name . |
descriptionFrom | the column name to use in the relation used for displaying a description. Default: description . |
title | text to display in the title section of the popup. |
list | a configuration array or reference to a list column definition file. |
filter | a reference to a filter scopes definition file, see backend list filters. |
showSetup | displays a setup button to configure the list columns and records per page. Default: false |
structure | enables a read-only structured list for selecting records, see the sorting records article. Set to false to disable, otherwise enabled when the model uses a tree interface. |
defaultSort | sets a default sorting column and direction when user preference is not defined. Supports a string or an array with keys column and direction . The direction can be asc for ascending (default) or desc for descending order. |
recordsPerPage | records to display per page, use 0 for no pages. Default: 10 |
conditions | specifies a raw where query statement to apply to the list model query. |
scope | applies a query scope method to the related form model, can be a model method name or a static PHP class method (Class::method ). The first argument will contain the model that the widget will be attaching its value to, i.e. the parent model. |
searchMode | defines the search strategy to either contain all words, any word or exact phrase. Supported options: all, any, exact. Default: all . |
searchScope | specifies a query scope method defined in the related form model to apply to the search query, the first argument will contain the search term. |
useRelation | flag for using the name of the field as a relation name to interact with directly on the parent model. Default: true . Disable to return just the selected model's ID |
modelClass | class of the model to use for listing records when useRelation is false |
popupSize | change the size of the finder popup used, either: giant , huge , large , small , tiny or adaptive . Default: huge |
inlineOptions | displays the field with buttons alongside the selected record, disable this mode if horizontal space is limited. Default: true . |
You may limit the number of records per page using the recordsPerPage
property.
user:
label: User
type: recordfinder
recordsPerPage: 10
Use the title
property to change the title of the management form.
user:
label: User
type: recordfinder
title: Find A User
When a record is selected, the display attributes can be chosen from model attributes using the nameFrom
and descriptionFrom
properties.
user:
label: User
type: recordfinder
nameFrom: name
descriptionFrom: email
If a model structure is detected, then the list will display as a structure. This can be disabled or enabled explicitly with the structure property.
user:
label: User
type: recordfinder
structure: false
# Usage in Tailor
When the recordfinder
field is used as a content field in Tailor, it requires the modelClass
property to be specified to define and locate the model relation.
products:
label: Products
type: recordfinder
modelClass: Acme\Test\Models\Product
list: $/october/test/models/product/columns.yaml
When the maxItems
is set to 1, the relation is defined as a belongsTo
relation. Otherwise, the relation is defined as belongsToMany
.
products:
label: Products
type: recordfinder
modelClass: Acme\Test\Models\Tag
maxItems: 1
The inverse
property can be set to the relation name on the related model. This will change the relation definition to hasOne
, hasMany
or belongsToMany
based on the maxItems
setting and relation type of the related model.
tags:
label: Tags
type: recordfinder
modelClass: Acme\Test\Models\Tag
inverse: tags