Learn about the different form field types.
Form Fields, Form UI and Form Widgets are field definitions used by forms, such as a text input. These are commonly referred to by the following areas:
All form fields are identified as their individual type property.
fields: myfield: type: textarea # ...
Form Fields contain generic and simple fields. Form UI is for user interface elements that can be included in forms to help with the layout design. Form Widgets will often introduce more complex functionality, it is common for plugins to provide their own custom form widgets. Tailor Fields are fields that are only available inside tailor blueprints.
# Available Fields
The following form fields are available:
Mixin Entries Text Number Password Email Textarea Dropdown Radio List Balloon Selector Checkbox Checkbox List Switch Code Editor Color Picker Data Table Date Picker File Upload Markdown Editor Media Finder Nested Form Record Finder Relation Repeater Rich Editor Sensitive Tag List Boxes Section Hint Ruler Partial
# Field Properties
For each field you can specify these common properties, where applicable.
|label||a name when displaying the form field to the user.|
|type||defines how this field should be rendered. Default: |
|span||aligns the form field to one side. Options: |
|spanClass||used with the span |
|size||specifies a field size for fields that use it, for example, the textarea field. Options: |
|placeholder||if the field supports a placeholder value.|
|comment||places a descriptive comment below the field.|
|commentAbove||places a comment above the field.|
|commentHtml||allow HTML markup inside the comment. Options: |
|default||specify the default value for the field. For |
|defaultFrom||takes the default value from the value of another field.|
|tab||assigns the field to a tab.|
|cssClass||assigns a CSS class to the field container.|
|readOnly||prevents the field from being modified. Options: |
|disabled||prevents the field from being modified and excludes it from the saved data. Options: |
|hidden||hides the field from the view and excludes it from the saved data. Options: |
|stretch||specifies if this field stretches to fit the parent height.|
|context||specifies what context should be used when displaying the field. Context can also be passed by using an |
|dependsOn||an array of other field names this field depends on, when the other fields are modified, this field will update.|
|changeHandler||the name of an AJAX handler to call when the field value is changed, optional.|
|trigger||specify conditions for this field using trigger events.|
|preset||allows the field value to be initially set by the value of another field, converted using the input preset converter.|
|required||places a red asterisk next to the field label to indicate it is required. Be sure to use the validation trait on the model as this is not enforced by the form controller.|
|attributes||specify custom HTML attributes to add to the form field element.|
|containerAttributes||specify custom HTML attributes to add to the form field container.|
|order||a numerical weight when determining the display order, default value increments at 100 points per field.|
|permissions||the permissions that the current backend user must have in order for the field to be used. Supports either a string for a single permission or an array of permissions of which only one is needed to grant access.|
# Tab Properties
An example of specifying field definitions in tabs.
tabs: fields: username: type: text label: Username tab: User groups: type: relation label: Groups tab: Groups
For each tab definition, namely
secondaryTabs, you can specify these properties.
|stretch||specifies if this tab stretches to fit the parent height.|
|defaultTab||the default tab to assign fields to. Default: Misc.|
|activeTab||selected tab when the form first loads, name or index. Default: |
|icons||assign icons to tabs using tab names as the key.|
|lazy||array of tabs to be loaded dynamically when clicked. Useful for tabs that contain large amounts of content.|
|linkable||determines if the tabs can be linked using URL fragments. Default: |
|cssClass||assigns a CSS class to the tab container.|
|paneCssClass||assigns a CSS class to an individual tab pane. Value is an array, key is tab index or label, value is the CSS class. It can also be specified as a string, in which case the value will be applied to all tabs.|
An example applying properties to tabs.
tabs: stretch: true defaultTab: User cssClass: text-blue lazy: - Groups paneCssClass: 1: first-tab 2: second-tab icons: User: icon-user Groups: icon-group fields: # [...]
# Custom Field Types
There are various native field types that can be used for the type setting. It is also possible to render a field directly by specifying the PHP class name of a form field widget.
blog_content: type: Backend\FormWidgets\RichEditor size: huge
# Nested Field Selection
avatar[name]: label: Avatar comment: will be saved in the Avatar table
The above example would fetch and save the value in PHP equivalent of
# Field Facades
Sometimes you may need to display a field while preventing it from being submitted. A field can be defined as a facade by adding an underscore (_) before the name of the field. These fields are purged automatically and no longer saved to the model, such as with the following
address: label: Title type: text _map: label: Point your address on the map type: mapviewer
# Field Conditions
Sometimes you may want to manipulate the value or appearance of a form field under certain conditions, for example, you may want to hide an input if a checkbox is ticked or preset the value of another field.
# Trigger Events
Trigger Events are defined with the
is_delayed: label: Send later comment: Place a tick in this box if you want to send this message at a later time. type: checkbox send_at: label: Send date type: datepicker cssClass: field-indent trigger: action: show field: is_delayed condition: checked
In the above example the
send_at form field will only be shown if the
is_delayed field is checked. In other words, the field will show (action) if the other form input (field) is checked (condition).
trigger definition specifies these properties.
|action||defines the action applied to this field when the condition is met. Supported values: |
|field||reference to the other field name that triggers the action. Example: |
|condition||determines the condition the specified field should satisfy for the condition to be considered |
# Multiple Actions
You may combine multiple actions by separating them with a pipe
| symbol. The following will both display and empty the input when the trigger condition is met.
trigger: action: show|empty condition: checked field: name
# Multiple Value Conditions
When using the
value condition, you may look for multiple values by passing extra values after the first one, which takes the format
trigger: action: show condition: value[csv][csv_custom] field: file_format
# Multiple Field Values
Some fields, such as Checkbox List and Tag List, will store their values as an array. When referencing these fields, the field name should use an array suffix (
) to look at all possible values. For example, if a
colors field name supports multiple values, the field name
colors should be used as a reference.
trigger: action: show condition: value[red][green] field: colors
# Referencing Parent Fields
Normally the field name refers to a field in the same level form. For example, if this field is in a repeater widget, only fields in that same repeater widget will be checked. However, if the field name is preceded by a caret symbol
^parent_field, it will refer to a repeater widget or form one level higher than the field itself.
In the example below, the
colors field will be shown when the
type field is set to Complex.
fields: type: label: Type type: dropdown options: 1: Simple 2: Complex content: label: Content type: nestedform form: fields: colors: label: Colors type: colorpicker trigger: action: show field: ^type condition: value
Additionally, if more than one caret
^ is used, it will refer that many levels higher:
# Input Preset Converter
The input preset converter is defined with the
preset form field property and allows you to convert text entered into an element to a URL, slug or file name value in another input element.
In this example we will automatically fill out the
url field value when a user enters text in the
title field. If the text Hello world is typed in for the Title, the URL will follow suit with the converted value of /hello-world. This behavior will only occur when the destination field (
url) is empty and untouched.
title: label: Title url: label: URL preset: field: title type: url
preset value can also be a string that refers to the field only, the
type option will then default to slug.
slug: label: Slug preset: title
The following options are available for the
|field||defines the other field name to source the value from.|
|type||specifies the conversion type. See below for supported values.|
|prefixInput||optional, prefixes the converted value with the value found in the supplied input element using a CSS selector.|
Following are the supported types:
|exact||copies the exact value|
|slug||formats the copied value as a slug|
|url||same as slug but prefixed with a /|
|camel||formats the copied value with camelCase|
|file||formats the copied value as a file name with whitespace replaced with dashes|