表单字段的管理

扩展自定义组件

{tip} 扩展自定义Form组件后IDE默认是不会自动补全的，这时候可以通过php artisan admin:ide-helper生成IDE提示文件。

集成富文本编辑器wangEditor

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

先下载前端库文件wangEditor，解压到目录public/vendor/wangEditor-3.0.9。

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

  2. <?php
  4. namespace App\Admin\Extensions;
  6. use Dcat\Admin\Form\Field;
  8. class WangEditor extends Field
  9. {
  10.     protected $view = 'admin.wang-editor';
  12.     protected static $css = [
  13.         '/vendor/wangEditor-3.0.9/release/wangEditor.min.css',
  14.     ];
  16.     protected static $js = [
  17.         '/vendor/wangEditor-3.0.9/release/wangEditor.min.js',
  18.     ];
  20.     public function render()
  21.     {
  22.         $name = $this->formatName($this->column);
  24.         $this->script = <<<EOT
  25. // 注意这里的ID一定要通过 replaceNestedFormIndex 函数转换，否则将无法兼容 hasMany 表单
  26. var E = window.wangEditor
  27. var editor = new E(replaceNestedFormIndex('#{$this->id}'));
  28. editor.customConfig.zIndex = 0
  29. editor.customConfig.uploadImgShowBase64 = true
  30. editor.customConfig.onchange = function (html) {
  31.     $('input[name=$name]').val(html);
  32. }
  33. editor.create()
  35. EOT;
  36.         return parent::render();
  37.     }
  38. }

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

  1. <div class="{{$viewClass['form-group']}} {!! !$errors->has($label) ? '' : 'has-error' !!}">
  3.     <label for="{{$id}}" class="{{$viewClass['label']}} control-label">{{$label}}</label>
  5.     <div class="{{$viewClass['field']}}">
  7.         @include('admin::form.error')
  9.         <div id="{{$id}}" style="width: 100%; height: 100%;">
  10.             <p>{!! old($column, $value) !!}</p>
  11.         </div>
  13.         <input type="hidden" name="{{$name}}" value="{{ old($column, $value) }}" />
  15.         @include('admin::form.help-block')
  17.     </div>
  18. </div>

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

  2. <?php
  4. use App\Admin\Extensions\WangEditor;
  5. use Dcat\Admin\Form;
  7. Form::extend('editor', WangEditor::class);

调用:

  2. $form->editor('body');

集成富文本编辑器ckeditor

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

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

  1. <?php
  3. namespace App\Admin\Extensions\Form;
  5. use Dcat\Admin\Form\Field;
  7. class CKEditor extends Field
  8. {
  9.     public static $js = [
  10.         '/packages/ckeditor/ckeditor.js',
  11.         '/packages/ckeditor/adapters/jquery.js',
  12.     ];
  14.     protected $view = 'admin.ckeditor';
  16.     public function render()
  17.     {
  18.         $this->script = "$('{$this->getElementClassSelector()}').ckeditor();";
  20.         return parent::render();
  21.     }
  22. }

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

  1. <div class="{{$viewClass['form-group']}} {!! !$errors->has($label) ? '' : 'has-error' !!}">
  3.     <label for="{{$id}}" class="{{$viewClass['label']}} control-label">{{$label}}</label>
  5.     <div class="{{$viewClass['field']}}">
  7.         @include('admin::form.error')
  9.         <textarea class="form-control {{ $class }}" name="{{$name}}" placeholder="{{ $placeholder }}" {!! $attributes !!} >{{ old($column, $value) }}</textarea>
  11.         @include('admin::form.help-block')
  13.     </div>
  14. </div>

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

  1. use App\Admin\Extensions\Form\CKEditor;
  2. use Dcat\Admin\Form;
  4. Form::extend('ckeditor', CKEditor::class);

然后就能在form中使用了:

  1. $form->ckeditor('content');

集成PHP editor

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

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

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

  1. <?php
  3. namespace App\Admin\Extensions;
  5. use Dcat\Admin\Form\Field;
  7. class PHPEditor extends Field
  8. {
  9.     protected $view = 'admin.php-editor';
  11.     protected static $css = [
  12.         '/packages/codemirror-5.20.2/lib/codemirror.css',
  13.     ];
  15.     protected static $js = [
  16.         '/packages/codemirror-5.20.2/lib/codemirror.js',
  17.         '/packages/codemirror-5.20.2/addon/edit/matchbrackets.js',
  18.         '/packages/codemirror-5.20.2/mode/htmlmixed/htmlmixed.js',
  19.         '/packages/codemirror-5.20.2/mode/xml/xml.js',
  20.         '/packages/codemirror-5.20.2/mode/javascript/javascript.js',
  21.         '/packages/codemirror-5.20.2/mode/css/css.js',
  22.         '/packages/codemirror-5.20.2/mode/clike/clike.js',
  23.         '/packages/codemirror-5.20.2/mode/php/php.js',
  24.     ];
  26.     public function render()
  27.     {
  28.         $this->script = <<<EOT
  29. // 注意这里的ID一定要通过 replaceNestedFormIndex 函数转换，否则将无法兼容 hasMany 表单
  30. CodeMirror.fromTextArea(document.getElementById(replaceNestedFormIndex("{$this->id}")), {
  31.     lineNumbers: true,
  32.     mode: "text/x-php",
  33.     extraKeys: {
  34.         "Tab": function(cm){
  35.             cm.replaceSelection("    " , "end");
  36.         }
  37.      }
  38. });
  40. EOT;
  41.         return parent::render();
  43.     }
  44. }

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

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

  2. <div class="{{$viewClass['form-group']}} {!! !$errors->has($label) ? '' : 'has-error' !!}">
  4.     <label for="{{$id}}" class="{{$viewClass['label']}} control-label">{{$label}}</label>
  6.     <div class="{{$viewClass['field']}}">
  8.         @include('admin::form.error')
  10.         <textarea class="form-control" id="{{$id}}" name="{{$name}}" placeholder="{{ trans('admin::lang.input') }} {{$label}}" {!! $attributes !!} >{{ old($column, $value) }}</textarea>
  12.         @include('admin::form.help-block')
  13.     </div>
  14. </div>

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

  1. <?php
  3. use App\Admin\Extensions\PHPEditor;
  4. use Dcat\Admin\Form;
  6. Form::extend('php', PHPEditor::class);

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

  2. $form->php('code');

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

常用方法

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

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

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

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

  1. class PHPEditor extends Field
  2. {
  3.     ...
  5.     // 把用户输入的表单值转化为 string 格式保存到数据库
  6.     protected function prepareInputValue($value)
  7.     {
  8.         return (string) $value;
  9.     }
  10. }

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

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

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

  1. class PHPEditor extends Field
  2. {
  3.     ...
  5.     // 把字段值转化为数组格式
  6.     // $data是当前表单的编辑数据，数据格式是 array
  7.     protected function formatFieldData($data)
  8.     {
  9.         return (array) parent::formatFieldData($data);
  10.     }
  11. }

获取元素CSS选择器 (getElementClassSelector)

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

模板

  1. <div class="{{$viewClass['form-group']}} {!! !$errors->has($errorKey) ? '' : 'has-error' !!}">
  3.     <div for="{{ $id }}" class="{{ $viewClass['label'] }} control-label">
  4.         <span>{!! $label !!}</span>
  5.     </div>
  8.     <div class="{{$viewClass['field']}}">
  10.         @include('admin::form.error')
  12.         <input type="hidden" name="{{$name}}"/>
  14.         <!-- $class 即是根据字段名称生成的class -->
  15.         <select class="form-control {{$class}}" style="width: 100%;" name="{{$name}}" {!! $attributes !!} >
  16.            <option value=""></option>
  17.            @foreach($options as $select => $option)
  18.                <option value="{{$select}}" {{ Dcat\Admin\Support\Helper::equal($select, old($column, $value)) ?'selected':'' }}>{{$option}}</option>
  19.            @endforeach
  20.         </select>
  22.         @include('admin::form.help-block')
  24.     </div>
  25. </div>

使用

  1. class Select extends Field
  2. {
  3.     ...
  5.     /**
  6.      * {@inheritdoc}
  7.      */
  8.     public function render()
  9.     {
  10.         ...
  12.         if (empty($this->script)) {
  13.             // 通过 getElementClassSelector 方法可以获取到表单中 select 标签的css选择器
  14.             $this->script = "$(\"{$this->getElementClassSelector()}\").select2($configs);";
  15.         }
  17.         ...
  19.         return parent::render();
  20.     }
  21. }

ID属性

表单组件类实例化后会生成一个唯一的随机字符串并保存到id属性中，然后传递到模板中，我们通常可以通过这个id获取到当前表单组件的关键元素

模板

  1. <div class="{{$viewClass['form-group']}} {!! !$errors->has($label) ? '' : 'has-error' !!}">
  3.     <label for="{{$id}}" class="{{$viewClass['label']}} control-label">{{$label}}</label>
  5.     <div class="{{$viewClass['field']}}">
  7.         @include('admin::form.error')
  9.         <!-- $id -->
  10.         <textarea class="form-control" id="{{$id}}" name="{{$name}}" placeholder="{{ trans('admin::lang.input') }} {{$label}}" {!! $attributes !!} >{{ old($column, $value) }}</textarea>
  12.         @include('admin::form.help-block')
  13.     </div>
  14. </div>

使用$id属性

  1. class PHPEditor extends Field
  2. {
  3.     ...
  5.     public function render()
  6.     {
  7.         // 通过 $this->id 定位元素
  8.         $this->script = <<<JS
  9. // 注意这里的ID一定要通过 replaceNestedFormIndex 函数转换，否则将无法兼容 hasMany 表单
  10. CodeMirror.fromTextArea(document.getElementById(replaceNestedFormIndex("{$this->id}")), {
  11.     lineNumbers: true,
  12.     mode: "text/x-php",
  13.     extraKeys: {
  14.         "Tab": function(cm){
  15.             cm.replaceSelection("    " , "end");
  16.         }
  17.      }
  18. });
  20. JS;
  21.         return parent::render();
  23.     }
  24. }

JS代码

为了让扩展的表单组件能够兼容HasMany以及Table表单，我们必须把JS代码保存在$script属性中

  1. class Select extends Field
  2. {
  3.     ...
  5.     /**
  6.      * {@inheritdoc}
  7.      */
  8.     public function render()
  9.     {
  10.         ...
  12.         $this->script = "$(\"{$this->getElementClassSelector()}\").select2($configs);";
  14.         ...
  16.         return parent::render();
  17.     }
  18. }

并且如果你是通过id属性去定位元素，则必须使用replaceNestedFormIndex函数对原始id进行转换，否则将无法兼容HasMany以及Table表单

  1. class PHPEditor extends Field
  2. {
  3.     ...
  5.     public function render()
  6.     {
  7.         // 通过 $this->id 定位元素
  8.         $this->script = <<<JS
  9. // 注意这里的ID一定要通过 replaceNestedFormIndex 函数转换，否则将无法兼容 hasMany 表单
  10. CodeMirror.fromTextArea(document.getElementById(replaceNestedFormIndex("{$this->id}")), {
  11.     lineNumbers: true,
  12.     mode: "text/x-php",
  13.     extraKeys: {
  14.         "Tab": function(cm){
  15.             cm.replaceSelection("    " , "end");
  16.         }
  17.      }
  18. });
  19. JS;
  20.         return parent::render();
  22.     }
  23. }