Backend Forms

#Introduction

The Form behavior is a controller behavior used for easily adding form functionality to a backend page. The behavior provides three pages called Create, Update and Preview. The Preview page is a read-only version of the Update page. When you use the form behavior you don't need to define the create, update and preview actions in the controller - the behavior does it for you. However you should provide the corresponding view files.

The Form behavior depends on form field definitions and a model class. In order to use the Form behavior you should add the \Backend\Behaviors\FormController::class definition to the $implement property of the controller class.

namespace Acme\Blog\Controllers;

class Categories extends \Backend\Classes\Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\FormController::class,
    ];
}

NOTE: Very often the form and list behavior are used together in a same controller.

#Configuring the form behavior

The form behaviour will load its configuration in the YAML format from a config_form.yaml file located in the controller's views directory (plugins/myauthor/myplugin/controllers/mycontroller/config_form.yaml) by default.

This can be changed by overriding the $formConfig property on your controller to reference a different filename or a full configuration array:

public $formConfig = 'my_custom_form_config.yaml';

Below is an example of a typical form behavior configuration file:

# ===================================
#  Form Behavior Config
# ===================================

name: Blog Category
form: $/acme/blog/models/post/fields.yaml
modelClass: Acme\Blog\Post

create:
    title: New Blog Post

update:
    title: Edit Blog Post

preview:
    title: View Blog Post

The following fields are required in the form configuration file:

The configuration options listed below are optional. Define them if you want the form behavior to support the Create, Update or Preview pages.

#Create page

To support the Create page add the following configuration to the YAML file:

create:
    title: New Blog Post
    redirect: acme/blog/posts/update/:id
    redirectClose: acme/blog/posts
    flashSave: Post has been created!

The following configuration options are supported for the Create page:

#Update page

To support the Update page add the following configuration to the YAML file:

update:
    title: Edit Blog Post
    redirect: acme/blog/posts
    flashSave: Post updated successfully!
    flashDelete: Post has been deleted.

The following configuration options are supported for the Update page:

#Preview page

To support the Preview page add the following configuration to the YAML file:

preview:
    title: View Blog Post

The following configuration options are supported for the Preview page:

#Defining form fields

Form fields are defined with the YAML file. The form fields configuration is used by the form behavior for creating the form controls and binding them to the model fields. The file is placed to a subdirectory of the models directory of a plugin. The subdirectory name matches the model class name written in lowercase. The file name doesn't matter, but fields.yaml and form_fields.yaml are common names. Example form fields file location:

plugins/
`-- acme/
    `-- blog/
        `-- models/               # Plugin models directory
            |-- post/             # Model configuration directory
            |   `-- fields.yaml   # Model form fields config file
            `-- Post.php          # model class

Fields can be placed in three areas, the outside area, primary tabs or secondary tabs. The next example shows the typical contents of a form fields definition file.

# ===================================
#  Form Field Definitions
# ===================================

fields:
    blog_title:
        label: Blog Title
        description: The title for this blog

    published_at:
        label: Published date
        description: When this blog post was published
        type: datepicker

    [...]

tabs:
    fields:
        [...]

secondaryTabs:
    fields:
        [...]

Fields from related models can be rendered with the Relation Widget or the Relation Manager. The exception is a OneToOne or morphOne related field, which must be defined as relation[field] and then can be specified as any other field of the model:

    user_name:
        label: User Name
        description: The name of the user
    avatar[name]:
        label: Avatar
        description: will be saved in the Avatar table
    published_at:
        label: Published date
        description: When this blog post was published
        type: datepicker

    [...]

#Tab options

For each tab definition, namely tabs and secondaryTabs, you can specify these options:

NOTE: It is not recommended to use lazy loading on tabs with fields that are affected by triggers.

tabs:
    stretch: true
    defaultTab: User
    cssClass: text-blue
    lazy:
        - Groups
    paneCssClass:
        0: first-tab
        1: second-tab
    icons:
        User: icon-user
        Groups: icon-group

    fields:
        username:
            type: text
            label: Username
            tab: User

        groups:
            type: relation
            label: Groups
            tab: Groups

#Field options

For each field you can specify these options (where applicable):

#Available field types

There are various native field types that can be used for the type setting. For more advanced form fields, a form widget can be used instead.

#Balloon Selector

balloon-selector - renders a list, where only one item can be selected at a time.

gender:
    label: Gender
    type: balloon-selector
    default: female
    options:
        female: Female
        male: Male

See Defining field options for the different methods to specify the options.

#Checkbox

checkbox - renders a single checkbox.

show_content:
    label: Display content
    type: checkbox
    default: true

#Checkbox List

checkboxlist - renders a list of checkboxes.

permissions:
    label: Permissions
    type: checkboxlist
    # set to true to explicitly enable the "Select All", "Select None" options
    # on lists that have <=10 items (>10 automatically enables it)
    quickselect: true
    default: open_account
    options:
        open_account: Open account
        close_account: Close account
        modify_account: Modify account

See Defining field options for the different methods to specify the options.

Checkbox lists support secondary descriptions, found in the radio field type. Options can be displayed inline with each other instead of in separate rows by specifying cssClass: 'inline-options' on the checkboxlist field config.

#Dropdown

dropdown - renders a dropdown with specified options.

status_type:
    type: dropdown
    label: Blog Post Status
    options:
        - draft
        - published
        - archived

See Defining field options for the different methods to specify the options.

#Add icon to dropdown options

In order to add an icon or an image for every option which will be rendered in the dropdown field the options have to be provided as a multidimensional array with the following format 'key' => ['label-text', 'icon-class'], in php or key: [label-text, icon-class] in yaml.

status_type:
    type: dropdown
    label: Blog Post Status
    options:
        published: [Published, icon-check-circle]
        unpublished: [Unpublished, icon-minus-circle]
        draft: [Draft, icon-clock-o]

To define the behavior when there is no selection, you may specify an emptyOption value to include an empty option that can be reselected.

status:
    label: Blog Post Status
    type: dropdown
    emptyOption: -- no status --

Alternatively you may use the placeholder option to use a "one-way" empty option that cannot be reselected.

status:
    label: Blog Post Status
    type: dropdown
    placeholder: -- select a status --

By default the dropdown has a searching feature, allowing quick selection of a value. This can be disabled by setting the showSearch option to false.

status:
    label: Blog Post Status
    type: dropdown
    showSearch: false

Dropdowns can also allow users to provide a new value. This can be activated by setting the allowCustom option to true.

status:
    label: Blog Post Status
    type: dropdown
    allowCustom: true

The allowCustom option can be useful to provide a preset list of options without preventing the user from adding a new or custom value.

When using the get*Options method for defining options, you would be able to take into consideration any custom options present in the data:

status:
    label: Blog Post Status
    type: dropdown
    allowCustom: true

public function getStatusOptions($value, $formData)
{
    // Prefill the dropdown with the already used statuses: [['status' => 'draft'], ['status' => 'published']]
    $statuses = self::distinct('status')->get();

    // Insert the actual form's model value to avoid it to vanish
    // on eventual AJAX call that would refresh the field partial like dependsOn
    if ($this->status) {

        // The actual form's status could be a custom like ['status' => 'need review']
        $statuses->add(['status' => $this->status]);
    }

    // Return a list of statuses: [['status' => 'draft'], ['status' => 'published'], ['status' => 'need review']]
    return $statuses->pluck('status', 'status');
}

#Email

email - renders a single line text box with the type of email, triggering an email-specialised keyboard in mobile browsers.

user_email:
    label: Email Address
    type: email

If you would like to validate this field on save to ensure that it is a properly-formatted email address, please use the $rules property on your model, like so:

/**
 * @var array Validation rules
 */
public $rules = [
    'user_email' => 'email',
];

For more information on model validation, please visit the documentation page.

#Hint

hint - identical to a partial field but renders inside a hint container that can be hidden by the user.

content:
    type: hint
    path: content_field

#Number

number - renders a single line text box that takes numbers only.

your_age:
    label: Your Age
    type: number
    step: 1  # defaults to 'any'
    min: 1   # defaults to not present
    max: 100 # defaults to not present

If you would like to validate this field server-side on save to ensure that it is numeric, please use the $rules property on your model, like so:

/**
 * @var array Validation rules
 */
public $rules = [
    'your_age' => 'numeric',
];

For more information on model validation, please visit the documentation page.

#Partial

partial - renders a backend partial. If path option is not set the field name is used as the partial name when attempting to locate the partial. The following variables are available to the partial being rendered:

• $formWidget: The instance of the Backend\Widgets\Form class that this field belongs to
• $formModel or $model: The instance of the Model attached to this form.
• $formField or $field: The instance of Backend\Classes\FormField for this field.
• $formValue or $value: The value of this field instance.

content:
    type: partial
    path: $/acme/blog/models/comments/_content_field.htm

NOTE: If your partial field is meant only for display and will not be providing a value to the server to be stored then it is best practice to prefix the field name with an underscore (_) to prevent the FormController` behavior from attempting to process it

#Password

password - renders a single line password field. See also sensitive, for sensitive data that should be able to be revealed on request.

user_password:
    label: Password
    type: password

#Radio List

radio - renders a list of radio options, where only one item can be selected at a time.

security_level:
    label: Access Level
    type: radio
    default: guests
    options:
        all: All
        registered: Registered only
        guests: Guests only

Radio lists can also support a secondary description.

security_level:
    label: Access Level
    type: radio
    options:
        all: [All, Guests and customers will be able to access this page.]
        registered: [Registered only, Only logged in member will be able to access this page.]
        guests: [Guests only, Only guest users will be able to access this page.]

See Defining field options for the different methods to specify the options.

For radio lists the method could return either the simple array: key => value or an array of arrays for providing the descriptions: key => [label, description]. Options can be displayed inline with each other instead of in separate rows by specifying cssClass: 'inline-options' on the radio field config.

#Range

range - renders a slider that takes numbers only.

your_age:
    label: Progress
    type: range
    step: 1  # defaults to 1
    min: 0   # defaults to 0
    max: 100 # defaults to 100

#Section

section - renders a section heading and subheading. The label and comment values are optional and contain the content for the heading and subheading.

user_details_section:
    label: User details
    type: section
    comment: This section contains details about the user.

#Switch

switch - renders a switchbox.

show_content:
    label: Display content
    type: switch
    comment: Flick this switch to display content
    on: myauthor.myplugin::lang.models.mymodel.show_content.on
    off: myauthor.myplugin::lang.models.mymodel.show_content.off

#Text

text - renders a single line text box. This is the default type used if none is specified.

blog_title:
    label: Blog Title
    type: text

#Textarea

textarea - renders a multiline text box. A size can also be specified with possible values: tiny, small, large, huge, giant.

blog_contents:
    label: Contents
    type: textarea
    size: large

#Widget

widget - renders a custom form widget, the type field can refer directly to the class name of the widget or the registered alias name.

blog_content:
    type: Backend\FormWidgets\RichEditor
    size: huge

#Form widgets

There are various form widgets included as standard, although it is common for plugins to provide their own custom form widgets. You can read more on the Form Widgets article.

#Code editor

codeeditor - renders a plaintext editor for formatted code or markup. Note the options may be inherited by the code editor preferences defined for the Administrator in the backend.

css_content:
    type: codeeditor
    size: huge
    language: html

#Color picker

colorpicker - renders controls to select a color value.

color:
    label: Background
    type: colorpicker

There are two ways to provide the available colors for the colorpicker. The first method defines the availableColors directly as a list of color codes in the YAML file:

color:
    label: Background
    type: colorpicker
    availableColors: ['#000000', '#111111', '#222222']

The second method uses a specific method declared in the model class. This method should return an array of colors in the same format as in the example above. The first argument of this method is the field name, the second is the currect value of the field, and the third is the current data object for the entire form.

color:
    label: Background
    type: colorpicker
    availableColors: myColorList

Supplying the available colors in the model class:

public function myColorList($fieldName, $value, $formData)
{
    return ['#000000', '#111111', '#222222']
}

If the availableColors field in not defined in the YAML file, the colorpicker uses a set of 20 default colors. You can also define a custom set of default colors to be used in all color pickers that do not have the availableColors field specified. This can be managed in the Customize backend area of the Settings.

#Data table

datatable - renders an editable table of records, formatted as a grid. Cell content can be editable directly in the grid, allowing for the management of several rows and columns of information.

NOTE: In order to use this with a model, the field should be defined as a jsonable attribute, or as another attribute that can handle storing arrayed data.

data:
    type: datatable
    adding: true
    btnAddRowLabel: Add Row Above
    btnAddRowBelowLabel: Add Row Below
    btnDeleteRowLabel: Delete Row
    columns: []
    default: []
    deleting: true
    dynamicHeight: true
    fieldName: null
    height: false
    keyFrom: id
    recordsPerPage: false
    searching: false
    toolbar: []

Table configuration

The following lists the configuration values of the data table widget itself.

Column configuration

The data table widget allows for the specification of columns as an array via the columns configuration variable. Each column should use the field name as a key, and the following configuration variables to set up the field.

Example:

columns:
    id:
        type: string
        title: ID
        validation:
            integer:
                message: Please enter a number
    name:
        type: string
        title: Name
    enabled:
        type: checkbox
        title: Enabled
    virtual:
        type: checkbox
        title: Virtual

default:
    - { id: 1, name: "first record", enabled: 0, virtual: 1 }
    - { id: 2, name: "second record", enabled: 1, virtual: 0 }
    - { id: 3, name: "third record", enabled: 0, virtual: 0 }

Column validation

Column cells can be validated against the below types of validation. Validation should be specified as an array, with the type of validation used as a key, and an optional message specified as the message attrbute for that validation.

#Date picker

datepicker - renders a text field used for selecting date and times.

published_at:
    label: Published
    type: datepicker
    mode: date

#File upload

fileupload - renders a file uploader for images or regular files.

avatar:
    label: Avatar
    type: fileupload
    mode: image
    imageHeight: 260
    imageWidth: 260
    thumbOptions:
        mode: crop
        offset:
            - 0
            - 0
        quality: 90
        sharpen: 0
        interlace: false
        extension: auto

NOTE: Unlike the Media Finder FormWidget, the File Upload FormWidget uses database file attachments; so the field name must match a valid attachOne or attachMany relationship on the Model associated with the Form. IMPORTANT: Having a database column with the name used by this field type (i.e. a database column with the name of an existing attachOne or attachMany relationship) will cause this FormWidget to break. Use database columns with the Media Finder FormWidget and file attachment relationships with the File Upload FormWidget.

By default, the File Upload FormWidget only allows a limited set of file extensions. You can extend this list by adding a fileDefinitions config in config/cms.php file.
See Allowed file types for more information.

#Icon Picker

iconpicker - renders an icon picker that is by default powered by the Font Awesome icons included by WinterCMS.

icon:
    label: 'Icon'
    type: 'iconpicker'
    default: 'far icon-address-book'
    libraries: ~/modules/backend/formwidgets/iconpicker/meta/libraries.yaml

Alternatively, you may populate the libraries property with a user defined array of libraries (in the below example far) with specific icons.

icon:
    label: 'Icon'
    type: 'iconpicker'
    default: 'far icon-address-book'
    libraries:
        -
            id: 'far'
            title: "Font Awesome Regular"
            prefix: "far icon-"
            listicon: "far icon-circle"
            icons:
                - "far icon-address-book"
                - "far icon-address-card"

NOTE: If no default is provided, the input will remain empty, while the icon picker, once loaded, will focus on the first available icon.

#Markdown editor

markdown - renders a basic editor for markdown formatted text.

md_content:
    type: markdown
    size: huge
    mode: split

#Media finder

mediafinder - renders a field for selecting an item from the media manager library. Expanding the field displays the media manager to locate a file. The resulting selection is a string as the relative path to the file.

background_image:
    label: Background image
    type: mediafinder
    mode: image

NOTE: Unlike the File Upload FormWidget, the Media Finder FormWidget stores its data as a string representing the path to the image selected within the Media Library.

#Nested Form

nestedform - renders a nested form as the contents of this field and returns the form data as an array.

NOTE: In order to use this with a model, the field should be defined as a jsonable attribute, or as another attribute that can handle storing arrayed data.

content:
    type: nestedform
    usePanelStyles: false
    form:
        fields:
            added_at:
                label: Date added
                type: datepicker
            details:
                label: Details
                type: textarea
            title:
                label: This the title
                type: text
        tabs:
            fields:
                meta_title:
                    lable: Meta Title
                    tab: SEO
                color:
                    label: Color
                    type: colorpicker
                    tab: Design
        secondaryTabs:
            fields:
                is_active:
                    label: Active
                    type: checkbox
                logo:
                    label: Logo
                    type: mediafinder
                    mode: image

A nested form provides a way of collating reusable fields and making them available in multiple forms. A nested form supports the same syntax as a normal form, including tabs and secondary tabs, and outside fields. The given field name for the nested form will contain the entire structure and values of your nested form as a JSON array. It's even possible to use nested forms inside a nested form.

#Record finder

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/winter/user/models/user/columns.yaml
    recordsPerPage: 10
    title: Find Record
    prompt: Click the Find button to find a user
    keyFrom: id
    nameFrom: name
    descriptionFrom: email
    conditions: email = "bob@example.com"
    scope: whereActive
    searchMode: all
    searchScope: searchUsers
    useRelation: false
    modelClass: Winter\User\Models\User

#Relation

relation - renders either a dropdown or checkbox list according to the field relation type. Singular relationships display a dropdown, multiple relationships display a checkbox list. The label used for displaying each relation is sourced by the nameFrom or select definition.

categories:
    label: Categories
    type: relation
    nameFrom: title

Alternatively, you may populate the label using a custom select statement. Any valid SQL statement works here.

user:
    label: User
    type: relation
    select: concat(first_name, ' ', last_name)

You can also provide a model scope to use to filter the results with the scope property.

#Relation Manager

relationmanager - Renders the relation controller for this relation. This is the equivalent of using a partial field that renders the output of the relationRender() method from the controller.

records:
    label: Records
    type: relationmanager

#Repeater

repeater - renders a repeating set of form fields defined within.

extra_information:
    type: repeater
    titleFrom: title_when_collapsed
    form:
        fields:
            added_at:
                label: Date added
                type: datepicker
            details:
                label: Details
                type: textarea
            title_when_collapsed:
                label: This field is the title when collapsed
                type: text

The repeater field supports a group mode which allows a custom set of fields to be chosen for each iteration.

content:
    type: repeater
    prompt: Add content block
    groups: $/acme/blog/config/repeater_fields.yaml

This is an example of a group configuration file, which would be located in /plugins/acme/blog/config/repeater_fields.yaml. Alternatively these definitions could be specified inline with the repeater.

textarea:
    name: Textarea
    description: Basic text field
    icon: icon-file-text-o
    fields:
        text_area:
            label: Text Content
            type: textarea
            size: large

quote:
    name: Quote
    description: Quote item
    icon: icon-quote-right
    fields:
        quote_position:
            span: auto
            label: Quote Position
            type: radio
            options:
                left: Left
                center: Center
                right: Right
        quote_content:
            span: auto
            label: Details
            type: textarea

Each group must specify a unique key and the definition supports the following options.

NOTE: The group key is stored along with the saved data as the _group attribute.

Repeater style

The style attribute of the repeater widget controls the behaviour of repeater items. There are three different types of styles available for developers:

• default: Shows all the repeater items as expanded on page load. This is the default current behavior, and will be used if style is not defined in the repeater widget's configuration.
• collapsed: Shows all the repeater items as collapsed (minimised) on page load. The user can collapse or expand items as they wish.
• accordion: Shows only the first repeater item as expanded on load, with all others collapsed. When another item is exanded, any other expanded item is collapsed, effectively making it so that only one item is expanded at a time.

#Rich editor / WYSIWYG

richeditor - renders a visual editor for rich formatted text, also known as a WYSIWYG editor.

html_content:
    type: richeditor
    toolbarButtons: bold|italic
    size: huge

The available toolbar buttons are:

fullscreen, bold, italic, underline, strikeThrough, subscript, superscript, fontFamily, fontSize, |, color, emoticons, inlineStyle, paragraphStyle, |, paragraphFormat, align, formatOL, formatUL, outdent, indent, quote, insertHR, -, insertLink, insertImage, insertVideo, insertAudio, insertFile, insertTable, undo, redo, clearFormatting, selectAll, html

NOTE: | will insert a vertical separator line in the toolbar and - a horizontal one.

#Sensitive

sensitive - renders a revealable password field that can be used for sensitive information such as API keys or secrets, configuration values, etc. A sensitive field can be toggled visible and hidden at the user's request.

A sensitive field that contains a previously entered value will have the value replaced with a placeholder value on load, preventing the value from being guessed by length or copied. Upon revealing the value, the original value is retrieved by AJAX and populated into the field.

api_secret:
    type: sensitive
    allowCopy: false
    hideOnTabChange: true

#Tag list

taglist - renders a field for inputting a list of tags.

tags:
    type: taglist
    separator: space

See Defining field options for the different methods to specify the options.

tags:
    type: taglist
    options:
        - Red
        - Blue
        - Orange

You may use the mode called relation where the field name is a many-to-many relationship. This will automatically source and assign tags via the relationship. If custom tags are supported, they will be created before assignment.

tags:
    type: taglist
    mode: relation

#Defining field options

For fields and widgets that allow multiple options, we provide a multitude of ways of defining the available options that can be used depending on your needs.

The following fields and widgets allow the setting of options:

• Balloon Selector
• Checkbox List
• Dropdown
• Radio List
• Tag list

#Value-only options

You can define a simple list of values as an array directly in the form configuration. This will use each value as both the option's value and label.

status_type:
    label: Blog Post Status
    type: dropdown
    default: published
    options:
        - draft
        - published
        - archived

#Key-value options

If you wish to specify both the option's value and label separately, you can use a key-value object for the options definition. The key represents the option's value, and the value represents the option's label.

status_type:
    label: Blog Post Status
    type: dropdown
    default: published
    options:
        draft: Draft
        published: Published
        archived: Archived

#Language definition

If you intend to use multiple language, you can specify a language key string for options. This will allow you to define the options in your language file and change the label depending on the language used on the site. This follows the same rules as the key-value options.

status_type:
    label: Blog Post Status
    type: dropdown
    default: published
    options: author.plugin::lang.status_types

Supplying the options in a language file:

// lang.php
return [
    'status_types' => [
        'draft' => 'Draft',
        'published' => 'Published',
        'archived' => 'Archived',
    ],
];

#Model-derived options

Winter also has the capability of deriving the available options directly from the model that the form is connected to. This allows you to provide options through an AJAX call, and provides flexibility with making options available depending on the entire context of the form - for example, limiting options based on other attributes in the model.

If you do not specify an options configuration for a field or widget that requires options, this is the default way of retrieving the available options.

status_type:
    label: Blog Post Status
    type: dropdown

By default, the AJAX call will look for a method in your model that begins with get, followed by the field name in PascalCase, ending with Options. For example, the above field name being status_type would look for a method called getStatusTypeOptions. The callback accepts two parameters, the first being the value of the current field, and the second being an array of the current form data.

public function getStatusTypeOptions($value, $formData)
{
    return ['all' => 'All', ...];
}

Optionally, you may also provide a "catch-all" method in your model called getDropdownOptions, which will be used if the AJAX call is unable to find an applicable field method demonstrated above. This callback accepts three parameters: the field name as it is in the config (ie. status_type), the value of the field and the array of the current form data.

public function getDropdownOptions($fieldName, $value, $formData)
{
    if ($fieldName == 'status') {
        return ['all' => 'All', ...];
    }
    else {
        return ['' => '-- none --'];
    }
}

You can also override this behaviour by specifying a string for options. This will direct the AJAX call to look for a specific method in your model:

status:
    label: Blog Post Status
    type: dropdown
    options: listStatuses

Supplying the dropdown options to the model class:

public function listStatuses($fieldName, $value, $formData)
{
    return ['published' => 'Published', ...];
}

#AJAX-derived options

If you would like to retrieve the available options via AJAX but would like to provide the options from a specific class, you can also provide a "callback" function either as a string or as an array to a specific static function, using the same syntax that PHP accepts for callable methods.

status:
    label: Blog Post Status
    type: dropdown
    options: \MyAuthor\MyPlugin\Classes\FormHelper::staticMethodOptions

public static function staticMethodOptions($formWidget, $formField)
{
    return ['published' => 'Published', ...];
}

status:
    label: Blog Post Status
    type: dropdown
    options: [\MyAuthor\MyPlugin\Classes\FormHelper, staticMethodOptions]

Supplying the dropdown options to the model class:

public static function staticMethodOptions($formWidget, $formField)
{
    return ['published' => 'Published', ...];
}

#Form views

For each page your form supports Create, Update and Preview you should provide a view file with the corresponding name - create.htm, update.htm and preview.htm.

The form behavior adds two methods to the controller class: formRender and formRenderPreview. These methods render the form controls configured with the YAML file described above.

#Create view

The create.htm view represents the Create page that allows users to create new records. A typical Create page contains breadcrumbs, the form itself, and the form buttons. The data-request attribute should refer to the onSave AJAX handler provided by the form behavior. Below is a contents of the typical create.htm form.

<?= Form::open(['class'=>'layout']) ?>

    <div class="layout-row">
        <?= $this->formRender() ?>
    </div>

    <div class="form-buttons">
        <div class="loading-indicator-container">
            <button
                type="button"
                data-request="onSave"
                data-request-data="close:true"
                data-hotkey="ctrl+enter, cmd+enter"
                data-load-indicator="Creating Category..."
                class="btn btn-default">
                Create and Close
            </button>
            <span class="btn-text">
                or <a href="<?= Backend::url('acme/blog/categories') ?>">Cancel</a>
            </span>
        </div>
    </div>

<?= Form::close() ?>

#Update view

The update.htm view represents the Update page that allows users to update or delete existing records. A typical Update page contains breadcrumbs, the form itself, and the form buttons. The Update page is very similar to the Create page, but usually has the Delete button. The data-request attribute should refer to the onSave AJAX handler provided by the form behavior. Below is a contents of the typical update.htm form.

<?= Form::open(['class'=>'layout']) ?>

    <div class="layout-row">
        <?= $this->formRender() ?>
    </div>

    <div class="form-buttons">
        <div class="loading-indicator-container">
            <button
                type="button"
                data-request="onSave"
                data-request-data="close:true"
                data-hotkey="ctrl+enter, cmd+enter"
                data-load-indicator="Saving Category..."
                class="btn btn-default">
                Save and Close
            </button>
            <button
                type="button"
                class="wn-icon-trash-o btn-icon danger pull-right"
                data-request="onDelete"
                data-load-indicator="Deleting Category..."
                data-request-confirm="Do you really want to delete this category?">
            </button>
            <span class="btn-text">
                or <a href="<?= Backend::url('acme/blog/categories') ?>">Cancel</a>
            </span>
        </div>
    </div>

<?= Form::close() ?>

#Preview view

The preview.htm view represents the Preview page that allows users to preview existing records in the read-only mode. A typical Preview page contains breadcrumbs and the form itself. Below is a contents of the typical preview.htm form.

<div class="form-preview">
    <?= $this->formRenderPreview() ?>
</div>

#Applying conditions to fields

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. There are a few ways you can do this, either by using the trigger API or field dependencies. The input preset converter is primarily used to converting field values. These options are described in more detail below.

#Input preset converter

The input preset converter is defined with the preset form field option 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:

#Trigger events

Trigger events are defined with the trigger form field option 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 options:

#Field dependencies

Form fields can declare dependencies on other fields by defining the dependsOn form field option which provides a more robust server side solution for updating fields when their dependencies are modified. When the fields that are declared as dependencies change, the defining field will update using the AJAX framework. This provides an opportunity to interact with the field's properties using the filterFields methods or changing available options to be provided to the field. Examples below:

country:
    label: Country
    type: dropdown

state:
    label: State
    type: dropdown
    dependsOn: country

In the above example the state form field will refresh when the country field has a changed value. When this occurs, the current form data will be filled in the model so the dropdown options can use it.

public function getCountryOptions()
{
    return ['au' => 'Australia', 'ca' => 'Canada'];
}

public function getStateOptions()
{
    if ($this->country == 'au') {
        return ['act' => 'Capital Territory', 'qld' => 'Queensland', ...];
    }
    elseif ($this->country == 'ca') {
        return ['bc' => 'British Columbia', 'on' => 'Ontario', ...];
    }
}

This example is useful for manipulating the model values, but it does not have access to the form field definitions. You can filter the form fields by defining a filterFields method inside the model, described in the Filtering form fields section. An example is provided below:

dnsprovider:
    label: DNS Provider
    type: dropdown

registrar:
    label: Registrar
    type: dropdown

specificfields[for][provider1]:
    label: Provider 1 ID
    type: text
    hidden: true
    dependsOn:
        - dnsprovider
        - registrar

specificfields[for][provider2]:
    label: Provider 2 ID
    type: text
    hidden: true
    dependsOn:
        - dnsprovider
        - registrar

And the logic for the filterFields method would be as follows:

public function filterFields($fields, $context = null)
{
    $displayedVendors = strtolower($this->dnsprovider->name . $this->registrar->name);
    if (str_contains($displayedVendors, 'provider1')) {
        $fields->{'specificfields[for][provider1]'}->hidden = false;
    }
    if (str_contains($displayedVendors, 'provider2')) {
        $fields->{'specificfields[for][provider2]'}->hidden = false;
    }
}

In the above example, both the provider1 and provider2 fields will automatically refresh whenever either the dnsprovider or registrar fields are modified. When this occurs, the full form cycle will be processed, which means that any logic defined in filterFields methods would be run again, allowing you to filter which fields get displayed dynamically.

#Preventing a field from being submitted

Sometimes you may need to prevent a field from being submitted. In order to do that, just add an underscore (_) before the name of the field in the form configuration file. Form fields beginning with an underscore are purged automatically and no longer saved to the model.

address:
    label: Title
    type: text

_map:
    label: Point your address on the map
    type: mapviewer

#Extending form behavior

Sometimes you may wish to modify the default form behavior and there are several ways you can do this.

#Form Model Events

Several controller methods can called at various points during the lifecycle of the FormController to provide injection points for custom logic. See the API docs for a full reference of what they are. Generally speaking any method in the API docs prefixed with form can be overridden in your controller to change the default behaviour or act as an injection point for custom logic.

NOTE: It may be more desirable to use model events to implement your logic instead as those are always run when applicable if the model is being affected, no matter where the interaction with the model is occuring.

#Overriding controller action

You can use your own logic for the create, update or preview action method in the controller, then optionally call the Form behavior parent method.

public function update($recordId, $context = null)
{
    //
    // Do any custom code here
    //

    // Call the FormController behavior update() method
    return $this->asExtension('FormController')->update($recordId, $context);
}

#Overriding controller redirect

You can specify the URL to redirect to after the model is saved by overriding the formGetRedirectUrl method. This method returns the location to redirect to with relative URLs being treated as backend URLs.

public function formGetRedirectUrl($context = null, $model = null)
{
    return 'https://example.com';
}

#Extending model query

The lookup query for the form database model can be extended by overriding the formExtendQuery method inside the controller class. This example will ensure that soft deleted records can still be found and updated, by applying the withTrashed scope to the query:

public function formExtendQuery($query)
{
    $query->withTrashed();
}

#Extending form fields

You can extend the fields of another controller from outside by calling the extendFormFields static method on the controller class. This method can take three arguments, $form will represent the Form widget object, $model represents the model used by the form and $context is a string containing the form context. Take this controller for example:

class Categories extends \Backend\Classes\Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\FormController::class,
    ];
}

Using the extendFormFields method you can add extra fields to any form rendered by this controller. Since this has the potential to affect all forms used by this controller, it is a good idea to check the $model is of the correct type. Here is an example:

Categories::extendFormFields(function ($form, $model, $context)
{
    if (!$model instanceof MyModel) {
        return;
    }

    $form->addFields([
        'my_field' => [
            'label'   => 'My Field',
            'comment' => 'This is a custom field I have added.',
        ],
    ]);

});

You can also extend the form fields internally by overriding the formExtendFields method inside the controller class. This will only affect the form used by the FormController behavior.

class Categories extends \Backend\Classes\Controller
{
    [...]

    public function formExtendFields($form)
    {
        $form->addFields([...]);
    }
}

The following methods are available on the $form object.

Each method takes an array of fields similar to the form field configuration.

#Filtering form fields

You can filter the form field definitions by overriding the filterFields method inside the Model used. This allows you to manipulate visibility and other field properties based on the model data. The method takes two arguments $fields will represent an object of the fields already defined by the field configuration and $context represents the active form context.

public function filterFields($fields, $context = null)
{
    if ($this->source_type == 'http') {
        $fields->source_url->hidden = false;
        $fields->git_branch->hidden = true;
    }
    elseif ($this->source_type == 'git') {
        $fields->source_url->hidden = false;
        $fields->git_branch->hidden = false;
    }
    else {
        $fields->source_url->hidden = true;
        $fields->git_branch->hidden = true;
    }
}

The above example will set the hidden flag on certain fields by checking the value of the Model attribute source_type. This logic will be applied when the form first loads and also when updated by a defined field dependency.

#Validating form fields

To validate the fields of your form you can make use of the Validation trait in your model.