后端表单

• 介绍
• 配置表单行为
  • 新建页面
  • 更新页面
  • 预览页面
• 定义表单字段
  • 标签选项
  • 字段选项
• 可用的字段类型
• 表单小部件
• 表单视图
  • 新建页面
  • 更新页面
  • 预览页面
• 将条件应用于字段
  • 输入预设转换器
  • 触发事件
  • 字段依赖性
  • 防止字段提交
• 扩展表单行为
  • 覆盖控制器action
  • 扩展表单模型查询
  • 扩展表单字段
  • 过滤表单字段
• 验证表单字段

介绍

表单行为 是一个控制器修饰符，用于轻松地将表单功能添加到后端页面。 该行为提供了三个名为Create，Update和Preview的页面。 “预览”页面是“更新”页面的只读版本。 当您使用表单行为时，您不需要在控制器中定义create，update和preview操作 - 行为就是为您完成的。 但是，您应该提供相应的视图文件。

表单行为取决于表单字段定义和模型类。 为了使用表单行为，您应该将它添加到控制器类的$implement属性中。 此外，应定义$formConfig类属性，其值应引用用于配置行为选项的YAML文件。

namespace Acme\Blog\Controllers;
class Categories extends \Backend\Classes\Controller
{
    public $implement = ['Backend.Behaviors.FormController'];
    public $formConfig = 'form_config.yaml';
}

注意: 表单和列表行为通常在同一个控制器中一起使用。

配置表单行为

$formConfig属性中引用的配置文件以YAML格式定义。 该文件应放入控制器的views目录。 以下是典型表单行为配置文件的示例：

# ===================================
#  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:

下面列出的配置选项是可选的。 如果希望表单行为支持Create, Update 或 Preview页面，请定义它们。

新建页面

要支持“新建”页面，请将以下配置添加到YAML文件中：

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

“创建”页面支持以下配置选项：

更新页面

要支持“更新”页面，请将以下配置添加到YAML文件中：

update:
    title:编辑文章
    redirect:acme/blog/posts
    flashSave:保存成功
    flashDelete:删除成功

“更新”页面支持以下配置选项：

预览页面

要支持“预览”页面，请将以下配置添加到YAML文件中：

preview:
    title:博客详情页

“预览”页面支持以下配置选项：

定义表单字段

表单字段使用YAML文件定义。 表单字段配置由表单行为用于创建表单控件并将它们绑定到模型字段。 该文件放在插件的models目录的子目录中。 子目录名称与以小写字母书写的模型类名称匹配。 文件名无关紧要，但fields.yaml和form_fields.yaml是常用名称。 示例表单字段文件位置：

plugins/
  acme/
    blog/
      models/        <=== Plugin models directory
        post/        <=== Model configuration directory
          fields.yaml    <=== Model form fields config file
        Post.php         <=== model class

字段可以放在三个区域，外部区域，主要标签或次要标签。 下一个示例显示了表单字段定义文件的典型内容。

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

可以使用Relation Widget或Relation Manager呈现相关模型中的字段。 例外是OneToOne或morphOne相关字段，必须定义为relation[field]，然后可以指定为模型的任何其他字段：

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

标签选项

对于每个选项卡定义，即tabs和secondaryTabs，您可以指定以下选项：

字段选项

对于每个字段，您可以指定这些选项(如果适用)：

可用的字段类型

有各种本机字段类型可用于类型设置。 对于更高级的表单字段，可以使用表单窗口小部件。

1. Text
2. Number
3. Password
4. Textarea
5. Dropdown
6. Radio List
7. Balloon Selector
8. Checkbox
9. Checkbox List
10. Switch
11. Section
12. Partial
13. Hint
14. Widget

Text

text - 呈现单行文本框。 如果未指定，则使用此默认类型。

blog_title:
    label: Blog Title
    type: text

Number

number - 呈现仅包含数字的单行文本框。

your_age:
    label: Your Age
    type: number

Password

password - 呈现单行密码字段。

user_password:
    label: Password
    type: password

Textarea

textarea - 呈现多行文本框。 尺寸也可以用可能的值指定： tiny, small, large, huge, giant.

blog_contents:
    label: Contents
    type: textarea
    size: large

Dropdown

dropdown - 使用指定选项呈现下拉列表。 有4种方法可以提供下拉选项。 第一个方法直接在YAML文件中定义options：

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

第二种方法使用模型类中声明的方法定义选项。 如果省略options元素，框架需要在模型中定义名为 getFieldNameOptions 的方法。 使用上面的示例，模型应该具有getStatusTypeOptions方法。 此方法的第一个参数是此字段的当前值，第二个参数是整个表单的当前数据对象。 此方法应返回key=>label格式的选项数组。

status_type:
    label: Blog Post Status
    type: dropdown

提供模型类中的下拉选项：

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

第三个全局方法getDropdownOptions也可以在模型中定义，这将用于模型的所有下拉字段类型。 此方法的第一个参数是字段名称，第二个参数是字段的当前值，第三个参数是整个表单的当前数据对象。 它应该以key=>label格式返回一个选项数组。

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

第四种方法使用模型类中声明的特定方法。 在下一个示例中，应该在模型类中定义listStatuses方法。 此方法接收与getDropdownOptions方法相同的所有参数，并应返回key=>label格式的选项数组。

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

将下拉选项提供给模型类：

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

要在没有选择时定义行为，可以指定emptyOption值以包含可以重新选择的空选项。

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

或者，您可以使用placeholder选项来使用无法重新选择的“单向”空选项。

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

默认情况下，下拉列表具有搜索功能，允许快速选择值。 可以通过将showSearch选项设置为false来禁用它。

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

Radio List

radio - 呈现单选按钮列表，其中一次只能选择一个项目。

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

单选按钮列表还可以支持次要描述。

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

无线电列表支持三种定义选项的方式，与下拉字段类型完全相同。 对于无线电列表，该方法可以返回简单数组：key=>value或用于提供描述的数组数组：key=>[label,description]

Balloon Selector

balloon-selector - 呈现一个列表，其中一次只能选择一个项目。

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

气球选择器支持三种定义选项的方式，与下拉字段类型完全相同。

Checkbox

checkbox - 呈现单个复选框。

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

Checkbox List

checkboxlist - 呈现复选框列表。

permissions:
    label: Permissions
    type: checkboxlist
    options:
        open_account: Open account
        close_account: Close account
        modify_account: Modify account

复选框列表支持三种定义选项的方法，与下拉字段类型完全相同，并且还支持单选字段类型中的辅助描述。

Switch

switch - 呈现一个开关按钮。

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

Section

section - 呈现节标题和子标题。 label和comment值是可选的，包含标题和子标题的内容。

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

Partial

partial - 呈现partial，path值可以引用部分视图文件，否则字段名称用作partial名称。 在partial内部，这些变量是可用的：$value是默认字段值，$model是用于字段的模型，$field是配置的类对象Backend\Classes\FormField。

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

Hint

hint - 与partial字段相同，但在一个可以被用户隐藏的提示容器内呈现。

content:
    type: hint
    path: content_field

Widget

widget - 呈现自定义表单窗口小部件，type字段可以直接引用窗口小部件的类名或注册的别名。

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

表单小部件

标准中包含各种表单小部件，但插件通常提供自己的自定义表单小部件。 您可以在Form Widgets文章上阅读更多内容。

1. Code editor
2. Color picker
3. Date picker
4. File upload
5. Record finder
6. Media finder
7. Relation
8. Repeater
9. Rich editor/WYSIWYG
10. Markdown editor
11. Tag list

Code editor

codeeditor - 为格式化代码或标记呈现纯文本编辑器。 请注意，可以通过在后端为管理员定义的代码编辑器首选项继承选项。

css_content:
    type: codeeditor
    size: huge
    language: html

Color picker

colorpicker - 渲染控件以选择十六进制颜色值。

color:
    label: Background
    type: colorpicker

Date picker

datepicker - 呈现用于选择日期和时间的文本字段。

published_at:
    label: Published
    type: datepicker
    mode: date

File upload

fileupload - 呈现图像或常规文件的文件上传器。 字段名称必须使用attachOne或attachMany关系。

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

Record finder

recordfinder - 呈现包含相关记录详细信息的字段。 展开字段会显示一个弹出列表以搜索大量记录。 仅受单一关系支持。

user:
    label: User
    type: recordfinder
    list: $/rainlab/user/models/user/columns.yaml
    prompt: Click the %s button to find a user
    nameFrom: name
    descriptionFrom: email

Media finder

mediafinder - 呈现用于从媒体管理器库中选择项目的字段。 展开字段会显示媒体管理器以查找文件。 结果选择是一个字符串作为文件的相对路径。

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

Relation

relation - 根据字段关系类型呈现下拉列表或复选框列表。 单数关系显示下拉列表，多个关系显示复选框列表。 用于显示每个关系的标签来自nameFrom或select定义。

categories:
    label: Categories
    type: relation
    nameFrom: title

或者，您可以使用自定义select语句填充标签。 任何有效的SQL语句都适用于此处

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

您还可以提供一个模型范围，用于使用scope属性过滤结果。

Repeater

repeater - 呈现一组重复的表单字段。

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

转发器字段支持组模式，该模式允许为每次迭代选择一组自定义字段。

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

这是组配置文件的示例，它位于 /plugins/acme/blog/config/repeater_fields.yaml中。 或者，这些定义可以与转发器一起指定。

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

每个组必须指定唯一键，并且该定义支持以下选项。

注意: 组密钥与保存的数据一起存储为_group属性。

富文本编辑器/WYSIWYG

richeditor - 为富格式文本呈现可视化编辑器，也称为WYSIWYG编辑器。

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

可用的工具栏按钮是：

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

注意: | 将在工具栏中插入一个垂直分隔线，并在-中插入一个水平分隔线。

Markdown编辑器

markdown - 为markdown格式化文本呈现基本编辑器。

md_content:
    type: markdown
    size: huge
    mode: split

标签列表

taglist - 呈现用于输入标签列表的字段。

tags:
    type: taglist
    separator: space

标签列表可以支持三种定义“选项”的方式，与下拉字段类型完全相同。

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

您可以使用名为relation的mode，其中字段名称是多对多关系。 这将通过关系自动获取和分配标签。 如果支持自定义标记，则会在分配之前创建它们。

tags:
    type: taglist
    mode: relation

表单视图

对于每个页面，您的表单支持 Create, Update 和 Preview ，您应该提供view file使用相应的名称 - create.htm, update.htm and preview.htm。

表单行为向控制器类添加了两个方法：formRender和formRenderPreview。 这些方法呈现使用上述YAML文件配置的表单控件。

新建页面

create.htm视图表示允许用户创建新记录的“创建”页面。 典型的“创建”页面包含面包屑，表单本身和表单按钮。 data-request 属性应该引用表单行为提供的onSave AJAX处理程序。 以下是典型的create.htm表单的内容。

<?= 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.htm视图表示允许用户更新或删除现有记录的“更新”页面。 典型的“更新”页面包含面包屑，表单本身和表单按钮。 “更新”页面与“创建”页面非常相似，但通常具有“删除”按钮。 data-request属性应该引用表单行为提供的onSave AJAX处理程序。 以下是典型update.htm表单的内容。

<?= 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="oc-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.htm 视图表示预览页面，允许用户以只读模式预览现有记录。 典型的预览页面包含面包屑和表单本身。 以下是典型的preview.htm表单的内容。

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

将条件应用于字段

有时您可能希望在某些条件下操纵表单字段的值或外观，例如，如果勾选了复选框，您可能希望隐藏输入。 通过使用触发器API或字段依赖性，有几种方法可以做到这一点。 输入预设转换器主要用于转换字段值。 下面更详细地描述这些选项。

输入预设转换器

输入预设转换器使用“预设”表单字段选项定义，并允许您将输入到元素中的文本转换为另一个输入元素中的URL，slug或文件名值。

在这个例子中，当用户在title字段中输入文本时，我们将自动填写url字段值。 如果为标题键入了文本Hello world，则URL将跟随/hello-world的转换值。 仅当目标字段(url)为空且未触及时才会发生此行为。

title:
    label: Title
url:
    label: URL
    preset:
        field: title
        type: url

或者，preset值也可以是仅引用字段的字符串，然后type选项将默认为slug。

slug:
    label: Slug
    preset: title

以下选项可用于“预设”选项：

以下是支持的类型：

触发事件

触发事件使用trigger 表单字段选项 定义，是一个使用JavaScript的基于浏览器的简单解决方案。 它允许您根据其他元素的状态更改元素属性，例如可见性或值。 这是一个示例定义：

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

在上面的例子中，只有在选中is_delayed字段时才会显示send_at表单字段。 换句话说，如果检查了另一个表单输入(字段)(条件)，该字段将显示(动作)。 trigger定义指定了以下选项：

字段依赖性

在定义dependsOn 表单字段选项时，表单字段可以依赖于其他字段，这提供了更强大的服务器端解决方案。 当定义的其他字段发生更改时，定义字段将使用AJAX框架进行更新。 这是一个示例定义：

country:
    label: Country
    type: dropdown
state:
    label: State
    type: dropdown
    dependsOn: country

在上面的例子中，state表单字段将在country字段具有更改的值时刷新。 发生这种情况时，当前表单数据将填入模型中，因此下拉选项可以使用它。

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', ...];
    }
}

此示例对于操作模型值很有用，但它无权访问表单字段定义。 您可以通过在模型中定义filterFields方法来过滤表单字段，如过滤表单字段 部分所述。

防止字段提交

有时您可能需要阻止提交字段。 为此，只需在表单配置文件中的字段名称前添加下划线(\ __)。 以下划线开头的表单字段将自动清除，不再保存到模型中。

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

扩展表单行为

有时您可能希望修改默认表单行为，有几种方法可以执行此操作。

覆盖控制器action

您可以将自己的逻辑用于控制器中的create，update或preview操作方法，然后可选地调用Form行为父方法。

public function update($recordId, $context = null)
{
    //
    //Do any custom code here
    //
    //Call the FormController behavior update() method
    return $this->asExtension('FormController')->update($recordId, $context);
}

扩展表单模型查询

可以通过覆盖控制器类中的formExtendQuery方法来扩展表单数据库模型的查询查询。 此示例将通过将withTrashed作用域应用于查询来确保仍可以找到并更新软删除的记录：

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

扩展表单字段

您可以通过在控制器类上调用extendFormFields静态方法从外部扩展另一个控制器的字段。 此方法可以采用三个参数，$form表示Form小部件对象，$model表示表单使用的模型，$context是包含表单上下文的字符串。 以此控制器为例：

class Categories extends \Backend\Classes\Controller
{
    public $implement = ['Backend.Behaviors.FormController'];
    public $formConfig = 'form_config.yaml';
}

使用extendFormFields方法，您可以向此控制器呈现的任何表单添加额外的字段。 由于这可能会影响此控制器使用的所有表单，因此最好检查$model的类型是否正确。 这是一个例子：

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.',
        ],
    ]);
});

您还可以通过覆盖控制器类中的formExtendFields方法在内部扩展表单字段。 这只会影响FormController行为使用的形式。

class Categories extends \Backend\Classes\Controller
{
    [...]
    public function formExtendFields($form)
    {
        $form->addFields([...]);
    }
}

$form对象提供以下方法。

每个方法都采用类似于表单字段配置的字段数组。

过滤表单字段

您可以通过覆盖所用模型中的filterFields方法来过滤表单字段定义。 这允许您根据模型数据操纵可见性和其他字段属性。 该方法有两个参数$fields表示已经由field configuration定义的字段的对象，$context表示活动表单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;
    }
}

上面的例子将通过检查Model属性source_type的值在某些字段上设置hidden标志。 当表单首次加载时以及通过定义的字段依赖性更新时，将应用此逻辑。

验证表单字段

要验证表单的字段，您可以在模型中使用验证特征。