表单字段的管理
<h1>表单字段的管理</h1>
<h2>扩展自定义组件</h2>
<p>在开始扩展表单组件之前需要先了解<a href="js.md#init">动态监听元素生成 (init)</a>功能，表单组件的<code>JS</code>代码建议都使用<code>Dcat.init</code>方法监听并初始化，否则可能无法兼容<code>Form::hasMany</code>以及<code>Form::array</code>等动态生成字段的表单类型。</p>
<h3>集成富文本编辑器wangEditor</h3>
<p><a href="http://www.wangeditor.com/">wangEditor</a>是一个优秀的国产的轻量级富文本编辑器，如果<code>dcat-admin</code>自带的基于<code>ckeditor</code>的编辑器组件使用上有问题，可以通过下面的步骤可以集成它，并覆盖掉默认的<code>editor</code>：</p>
<p>> 为了方便演示，示例中直接使用CDN链接。实际开发中需要先下载前端库文件<a href="https://github.com/wangfupeng1988/wangEditor/releases">wangEditor</a>到服务器，解压到目录<code>public/vendor/wangEditor-4.7.1</code>。</p>
<p>新建组件类<code>app/Admin/Extensions/Form/WangEditor.php</code>。</p>
<pre><code class="language-php">&lt;?php
namespace App\Admin\Extensions\Form;
use Dcat\Admin\Form\Field;
class WangEditor extends Field
{
protected $view = 'admin.wang-editor';
}</code></pre>
<p>新建视图文件<code>resources/views/admin/wang-editor.blade.php</code>：</p>
<pre><code class="language-html">&lt;div class=&quot;{{$viewClass['form-group']}}&quot;&gt;
&lt;label class=&quot;{{$viewClass['label']}} control-label&quot;&gt;{{$label}}&lt;/label&gt;
&lt;div class=&quot;{{$viewClass['field']}}&quot;&gt;
@include('admin::form.error')
&lt;div {!! $attributes !!} style=&quot;width: 100%; height: 100%;&quot;&gt;
&lt;p&gt;{!! $value !!}&lt;/p&gt;
&lt;/div&gt;
&lt;input type=&quot;hidden&quot; name=&quot;{{$name}}&quot; value=&quot;{{ old($column, $value) }}&quot; /&gt;
@include('admin::form.help-block')
&lt;/div&gt;
&lt;/div&gt;
&lt;!-- script标签加上 &quot;init&quot; 属性后会自动使用 Dcat.init() 方法动态监听元素生成 --&gt;
&lt;script require=&quot;@wang-editor&quot; init=&quot;{!! $selector !!}&quot;&gt;
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=&quot;hidden&quot;]').val(html);
}
editor.create()
&lt;/script&gt;</code></pre>
<p>然后注册进<code>dcat-admin</code>，在<code>app/Admin/bootstrap.php</code>中添加以下代码：</p>
<pre><code class="language-php">&lt;?php
use App\Admin\Extensions\Form\WangEditor;
use Dcat\Admin\Form;
// 注册前端组件别名
Admin::asset()-&gt;alias('@wang-editor', [
// 为了方便演示效果，这里直接加载CDN链接，实际开发中可以下载到服务器加载
'js' =&gt; ['https://cdn.jsdelivr.net/npm/wangeditor@4.7.1/dist/wangEditor.min.js'],
]);
Form::extend('editor', WangEditor::class);</code></pre>
<p>调用:</p>
<pre><code class="language-php">$form-&gt;editor('body');</code></pre>
<h3>集成富文本编辑器ckeditor</h3>
<p>先下载<a href="http://ckeditor.com/download">ckeditor</a> 并解压到/public目录，比如放在<code>/public/packages/</code>目录下。</p>
<p>然后新建扩展文件<code>app/Admin/Extensions/Form/CKEditor.php</code>:</p>
<pre><code class="language-php">&lt;?php
namespace App\Admin\Extensions\Form;
use Dcat\Admin\Form\Field;
class CKEditor extends Field
{
protected $view = 'admin.ckeditor';
}</code></pre>
<p>新建view <code>resources/views/admin/ckeditor.blade.php</code>:</p>
<pre><code class="language-html">&lt;div class=&quot;{{$viewClass['form-group']}}&quot;&gt;
&lt;label class=&quot;{{$viewClass['label']}} control-label&quot;&gt;{{$label}}&lt;/label&gt;
&lt;div class=&quot;{{$viewClass['field']}}&quot;&gt;
@include('admin::form.error')
&lt;textarea name=&quot;{{ $name}}&quot; placeholder=&quot;{{ $placeholder }}&quot; {!! $attributes !!} &gt;{!! $value !!}&lt;/textarea&gt;
@include('admin::form.help-block')
&lt;/div&gt;
&lt;/div&gt;
&lt;script require=&quot;@ckeditor&quot; init=&quot;{!! $selector !!}&quot;&gt;
$this.ckeditor();
&lt;/script&gt;</code></pre>
<p>然后在<code>app/Admin/bootstrap.php</code>中引入扩展：</p>
<pre><code class="language-php">use App\Admin\Extensions\Form\CKEditor;
use Dcat\Admin\Form;
// 注册前端组件别名
Admin::asset()-&gt;alias('@ckeditor', [
'js' =&gt; [
'/packages/ckeditor/ckeditor.js',
'/packages/ckeditor/adapters/jquery.js',
],
]);
Form::extend('ckeditor', CKEditor::class);</code></pre>
<p>然后就能在form中使用了:</p>
<pre><code class="language-php">$form-&gt;ckeditor('content');</code></pre>
<h3>集成PHP editor</h3>
<p>通过下面的步骤来扩展一个基于<a href="http://codemirror.net/index.html">codemirror</a>的PHP代码编辑器，效果参考<a href="http://codemirror.net/mode/php/">PHP mode</a>。</p>
<p>先将<a href="http://codemirror.net/codemirror.zip">codemirror</a>库下载并解压到前端资源目录下，比如放在<code>public/packages/codemirror-5.20.2</code>目录下。</p>
<p>新建组件类<code>app/Admin/Extensions/Form/PHPEditor.php</code>:</p>
<pre><code class="language-php">&lt;?php
namespace App\Admin\Extensions\Form;
use Dcat\Admin\Form\Field;
class PHPEditor extends Field
{
protected $view = 'admin.php-editor';
}
</code></pre>
<p>> {tip} 类中的静态资源也同样可以从外部引入，参考<a href="https://github.com/jqhph/dcat-admin/blob/master/src/Form/Field/Editor.php">Editor.php</a></p>
<p>创建视图<code>resources/views/admin/php-editor.blade.php</code>:</p>
<pre><code class="language-html">&lt;div class=&quot;{{$viewClass['form-group']}}&quot;&gt;
&lt;label class=&quot;{{$viewClass['label']}} control-label&quot;&gt;{{$label}}&lt;/label&gt;
&lt;div class=&quot;{{$viewClass['field']}}&quot;&gt;
@include('admin::form.error')
&lt;textarea class=&quot;{{ $class }}&quot; {!! $attributes !!} &gt;{!! $value !!}&lt;/textarea&gt;
&lt;input type=&quot;hidden&quot; name=&quot;{{$name}}&quot; value=&quot;{{ old($column, $value) }}&quot; /&gt;
@include('admin::form.help-block')
&lt;/div&gt;
&lt;/div&gt;
&lt;script require=&quot;@phpeditor&quot; init=&quot;{!! $selector !!}&quot;&gt;
var Editor = CodeMirror.fromTextArea(document.getElementById(id), {
lineNumbers: true,
mode: &quot;text/x-php&quot;,
extraKeys: {
&quot;Tab&quot;: function(cm){
cm.replaceSelection(&quot; &quot; , &quot;end&quot;);
}
}
});
Editor.on(&quot;change&quot;, function (Editor, changes) {
let val = Editor.getValue();
//console.log(val);
$this.parents('.form-field').find('input[type=&quot;hidden&quot;]').val(val);
});
&lt;/script&gt;</code></pre>
<p>最后找到文件<code>app/Admin/bootstrap.php</code>,如果文件不存在，请更新<code>dcat-admin</code>，然后新建该文件,添加下面代码：</p>
<pre><code>&lt;?php
use App\Admin\Extensions\Form\PHPEditor;
use Dcat\Admin\Form;
Admin::asset()-&gt;alias('@phpeditor', [
'js' =&gt; [
'/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' =&gt; '/packages/codemirror-5.20.2/lib/codemirror.css',
]);
Form::extend('php', PHPEditor::class);</code></pre>
<p>这样就能在<a href="model-form.md">model-form</a>中使用PHP编辑器了：</p>
<pre><code>$form-&gt;php('code');</code></pre>
<p>通过这种方式，可以添加任意你想要添加的<code>form</code>组件。</p>
<h2>常用方法</h2>
<p>表单组件是<code>Dcat Admin</code>中最为复杂的组件，下面列一些在扩展表单组件中可能需要用到的方法</p>
<h3>处理用户输入的表单值 (prepareInputValue)</h3>
<p>通过<code>prepareInputValue</code>方法可以处理用户输入的表单值，默认不做任何处理。此方法在<code>Form</code>表单的<code>saving</code>事件触发之后，表单字段的<code>saving</code>方法之前执行</p>
<p>> {tip} 这个功能类似<code>Laravel model</code>中的<strong>修改器</strong>。</p>
<pre><code class="language-php">class PHPEditor extends Field
{
...
// 把用户输入的表单值转化为 string 格式保存到数据库
protected function prepareInputValue($value)
{
return (string) $value;
}
}</code></pre>
<h3>处理待显示的字段值 (formatFieldData)</h3>
<p>通过<code>formatFieldData</code>方法可以处理处理待显示的字段值。此方法在表单字段的<code>customFormat</code>方法之前执行</p>
<p>> {tip} 这个功能类似<code>Laravel model</code>中的<strong>访问器</strong>。</p>
<pre><code class="language-php">class PHPEditor extends Field
{
...
// 把字段值转化为数组格式
// $data是当前表单的编辑数据，数据格式是 array
protected function formatFieldData($data)
{
// 获取到当前字段值
$value = parent::formatFieldData($data);
// 处理字段值
...
return $value;
}
}</code></pre>
<h3>获取元素CSS选择器 (getElementClassSelector)</h3>
<p>表单组件类实例化后会根据字段名称生成一个<code>css class</code>，然后传递到模板中，我们通常可以通过这个<code>class</code>获取到当前表单的元素对象</p>
<p>模板</p>
<pre><code class="language-html">&lt;div class=&quot;{{$viewClass['form-group']}}&quot;&gt;
&lt;div class=&quot;{{ $viewClass['label'] }} control-label&quot;&gt;
&lt;span&gt;{!! $label !!}&lt;/span&gt;
&lt;/div&gt;
&lt;div class=&quot;{{$viewClass['field']}}&quot;&gt;
@include('admin::form.error')
&lt;input type=&quot;hidden&quot; name=&quot;{{$name}}&quot;/&gt;
&lt;select style=&quot;width: 100%;&quot; name=&quot;{{$name}}&quot; {!! $attributes !!} &gt;
&lt;option value=&quot;&quot;&gt;&lt;/option&gt;
@foreach($options as $select =&gt; $option)
&lt;option value=&quot;{{$select}}&quot; {{ Dcat\Admin\Support\Helper::equal($select, $value) ?'selected':'' }}&gt;{{$option}}&lt;/option&gt;
@endforeach
&lt;/select&gt;
@include('admin::form.help-block')
&lt;/div&gt;
&lt;/div&gt;
&lt;script require=&quot;...&quot; init=&quot;{!! $selector !!}&quot;&gt;
// 这里的 $selector 即是当前字段的 css选择器
$this.select2($configs);
&lt;/script&gt;</code></pre>
<h3>JS代码</h3>
<p>为了让扩展的表单组件能够兼容<code>HasMany</code>、<code>array</code>以及<code>Table</code>表单，我们必须使用<a href="js.md#init">动态监听元素生成 (init)</a>功能</p>
<pre><code class="language-html">&lt;div class=&quot;{{$viewClass['form-group']}}&quot;&gt;
...
&lt;/div&gt;
&lt;script require=&quot;...&quot; init=&quot;{!! $selector !!}&quot;&gt;
$this.select2($configs);
&lt;/script&gt;</code></pre>