Form Fields

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:

• CMS Theme Settings
• Tailor Content Fields
• Backend Form Controller
• Backend Relation Controller

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:

# Field Properties

For each field you can specify these common properties, where applicable.

# 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 tabs and secondaryTabs, you can specify these properties.

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

    identifiers:
        User: userTab

    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 $record->avatar->name or $record->avatar['name'] respectively.

# 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 _map field.

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 trigger form field property and is a simple browser based solution that uses JavaScript. It allows you to change elements attributes such as visibility or value, based on another elements' state. Here is a sample definition:

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).

The trigger definition specifies these properties.

# 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 value[][].

trigger:
    action: show
    condition: value[csv][csv_custom]
    field: file_format

# Wildcard Value Conditions

You may check the value[] condition matches multiple possible values using a wildcard character (*), for example, foo* matches anything that starts with "foo", and *bar matches anything that ends with "bar".

trigger:
    action: show
    condition: value[*.mp4]
    field: file_name

# 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 ^ like: ^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[2]

# 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

Alternatively, the 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 preset option:

Following are the supported types: