表单字段扩展

扩展自定义组件

在开始扩展表单组件之前需要先了解动态监听元素生成 (init)功能，表单组件的JS代码建议都使用Dcat.init方法监听并初始化，否则可能无法兼容Form::hasMany以及Form::array等动态生成字段的表单类型。

集成富文本编辑器wangEditor

wangEditor是一个优秀的国产的轻量级富文本编辑器，如果dcat-admin自带的基于ckeditor的编辑器组件使用上有问题，可以通过下面的步骤可以集成它，并覆盖掉默认的editor：

为了方便演示，示例中直接使用CDN链接。实际开发中需要先下载前端库文件wangEditor到服务器，解压到目录public/vendor/wangEditor-4.7.1。

新建组件类app/Admin/Extensions/Form/WangEditor.php。

<?php

namespace App\Admin\Extensions\Form;

use Dcat\Admin\Form\Field;

class WangEditor extends Field
{
    protected $view = 'admin.wang-editor';
}

新建视图文件resources/views/admin/wang-editor.blade.php：

<div class="{{$viewClass['form-group']}}">

    <label class="{{$viewClass['label']}} control-label">{{$label}}</label>

    <div class="{{$viewClass['field']}}">

        @include('admin::form.error')

        <div {!! $attributes !!} style="width: 100%; height: 100%;">
            <p>{!! $value !!}</p>
        </div>

        <input type="hidden" name="{{$name}}" value="{{ old($column, $value) }}" />

        @include('admin::form.help-block')

    </div>
</div>

<!-- script标签加上 "init" 属性后会自动使用 Dcat.init() 方法动态监听元素生成 -->
<script require="@wang-editor" init="{!! $selector !!}">
    var E = window.wangEditor
    // id 变量是 Dcat.init() 自动生成的，是一个唯一的随机字符串
    var editor = new E('#' + id);
    editor.config.zIndex = 0
    editor.config.uploadImgShowBase64 = true
    editor.config.onchange = function (html) {
        $this.parents('.form-field').find('input[type="hidden"]').val(html);
    }
    editor.create()
</script>

然后注册进dcat-admin，在app/Admin/bootstrap.php中添加以下代码：

<?php

use App\Admin\Extensions\Form\WangEditor;
use Dcat\Admin\Form;

// 注册前端组件别名
Admin::asset()->alias('@wang-editor', [
    // 为了方便演示效果，这里直接加载CDN链接，实际开发中可以下载到服务器加载
    'js' => ['https://cdn.jsdelivr.net/npm/wangeditor@4.7.1/dist/wangEditor.min.js'],
]);

Form::extend('editor', WangEditor::class);

调用:

$form->editor('body');

集成富文本编辑器ckeditor

先下载ckeditor 并解压到/public目录，比如放在/public/packages/目录下。

然后新建扩展文件app/Admin/Extensions/Form/CKEditor.php:

<?php

namespace App\Admin\Extensions\Form;

use Dcat\Admin\Form\Field;

class CKEditor extends Field
{
    protected $view = 'admin.ckeditor';
}

新建view resources/views/admin/ckeditor.blade.php:

<div class="{{$viewClass['form-group']}}">

    <label class="{{$viewClass['label']}} control-label">{{$label}}</label>

    <div class="{{$viewClass['field']}}">

        @include('admin::form.error')

        <textarea name="{{ $name}}" placeholder="{{ $placeholder }}" {!! $attributes !!} >{!! $value !!}</textarea>

        @include('admin::form.help-block')

    </div>
</div>

<script require="@ckeditor" init="{!! $selector !!}">
    $this.ckeditor();
</script>

然后在app/Admin/bootstrap.php中引入扩展：

use App\Admin\Extensions\Form\CKEditor;
use Dcat\Admin\Form;

// 注册前端组件别名
Admin::asset()->alias('@ckeditor', [
    'js' => [
        '/packages/ckeditor/ckeditor.js',
        '/packages/ckeditor/adapters/jquery.js',
    ],
]);

Form::extend('ckeditor', CKEditor::class);

然后就能在form中使用了:

$form->ckeditor('content');

集成PHP editor

通过下面的步骤来扩展一个基于codemirror的PHP代码编辑器，效果参考PHP mode。

先将codemirror库下载并解压到前端资源目录下，比如放在public/packages/codemirror-5.20.2目录下。

新建组件类app/Admin/Extensions/PHPEditor.php:

<?php

namespace App\Admin\Extensions\Form;

use Dcat\Admin\Form\Field;

class PHPEditor extends Field
{
    protected $view = 'admin.php-editor';
}

{tip} 类中的静态资源也同样可以从外部引入，参考Editor.php

创建视图resources/views/admin/php-editor.blade.php:

<div class="{{$viewClass['form-group']}}">

    <label class="{{$viewClass['label']}} control-label">{{$label}}</label>

    <div class="{{$viewClass['field']}}">

        @include('admin::form.error')

        <textarea class="{{ $class }}"   {!! $attributes !!} >{!! $value !!}</textarea>

        <input type="hidden" name="{{$name}}" value="{{ old($column, $value) }}" />

        @include('admin::form.help-block')
    </div>
</div>

<script require="@phpeditor" init="{!! $selector !!}">
    var Editor = CodeMirror.fromTextArea(document.getElementById(id), {
        lineNumbers: true,
        mode: "text/x-php",
        extraKeys: {
            "Tab": function(cm){
                cm.replaceSelection("    " , "end");
            }
        }
    });
    Editor.on("change", function (Editor, changes) {
        let val = Editor.getValue();
        //console.log(val);
        $this.parents('.form-field').find('input[name="hidden"]').val(val);
    });
</script>

最后找到文件app/Admin/bootstrap.php,如果文件不存在，请更新dcat-admin，然后新建该文件,添加下面代码：

<?php

use App\Admin\Extensions\Form\PHPEditor;
use Dcat\Admin\Form;

Admin::asset()->alias('@phpeditor', [
    'js' => [
        '/packages/codemirror-5.20.2/lib/codemirror.js',
        '/packages/codemirror-5.20.2/addon/edit/matchbrackets.js',
        '/packages/codemirror-5.20.2/mode/htmlmixed/htmlmixed.js',
        '/packages/codemirror-5.20.2/mode/xml/xml.js',
        '/packages/codemirror-5.20.2/mode/javascript/javascript.js',
        '/packages/codemirror-5.20.2/mode/css/css.js',
        '/packages/codemirror-5.20.2/mode/clike/clike.js',
        '/packages/codemirror-5.20.2/mode/php/php.js',
    ],
    'css' => '/packages/codemirror-5.20.2/lib/codemirror.css',
]);

Form::extend('php', PHPEditor::class);

这样就能在model-form中使用PHP编辑器了：

$form->php('code');

通过这种方式，可以添加任意你想要添加的form组件。

常用方法

表单组件是Dcat Admin中最为复杂的组件，下面列一些在扩展表单组件中可能需要用到的方法

处理用户输入的表单值 (prepareInputValue)

通过prepareInputValue方法可以处理用户输入的表单值，默认不做任何处理。此方法在Form表单的saving事件触发之后，表单字段的saving方法之前执行

{tip} 这个功能类似Laravel model中的修改器。

class PHPEditor extends Field
{
    ...

    // 把用户输入的表单值转化为 string 格式保存到数据库
    protected function prepareInputValue($value)
    {
        return (string) $value;
    }
}

处理待显示的字段值 (formatFieldData)

通过formatFieldData方法可以处理处理待显示的字段值。此方法在表单字段的customFormat方法之前执行

{tip} 这个功能类似Laravel model中的访问器。

class PHPEditor extends Field
{
    ...

    // 把字段值转化为数组格式
    // $data是当前表单的编辑数据，数据格式是 array
    protected function formatFieldData($data)
    {
        // 获取到当前字段值
        $value = parent::formatFieldData($data);

        // 处理字段值
        ...

        return $value;
    }
}

获取元素CSS选择器 (getElementClassSelector)

表单组件类实例化后会根据字段名称生成一个css class，然后传递到模板中，我们通常可以通过这个class获取到当前表单的元素对象

模板

<div class="{{$viewClass['form-group']}}">

    <div class="{{ $viewClass['label'] }} control-label">
        <span>{!! $label !!}</span>
    </div>

    <div class="{{$viewClass['field']}}">

        @include('admin::form.error')

        <input type="hidden" name="{{$name}}"/>

        <select style="width: 100%;" name="{{$name}}" {!! $attributes !!} >
           <option value=""></option>
           @foreach($options as $select => $option)
               <option value="{{$select}}" {{ Dcat\Admin\Support\Helper::equal($select, $value) ?'selected':'' }}>{{$option}}</option>
           @endforeach
        </select>

        @include('admin::form.help-block')

    </div>
</div>


<script require="..." init="{!! $selector !!}">
    // 这里的 $selector 即是当前字段的 css选择器
    $this.select2($configs);
</script>

JS代码

为了让扩展的表单组件能够兼容HasMany、array以及Table表单，我们必须使用动态监听元素生成 (init)功能

<div class="{{$viewClass['form-group']}}">
    ...
</div>


<script require="..." init="{!! $selector !!}">
    $this.select2($configs);
</script>