menu-btn

Record Finder

Record Finder

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

# See Also

← Relation →

On This Page