Record Finder Field

Form Widget

Usage in Tailor

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.
modelScope	applies a model 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 model 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

← Nested Form FieldRelation Field →