>[info] 从1.0.6开始,支持自定义扩展表单项 | 版本 | 新增功能 | | --- | --- | | 1.0.7 | 支持调用公共资源 | | 1.1.0 | 修改静态资源位置,如果是从旧版升级到1.1.0,则请参考[升级指导](升级指导.md),将对于的资源移动到public目录 | >[danger] ### 注意,以下教程仅适用于1.1.0版本以前的,如果框架版本为1.1.0以上,则自定义表单项的静态资源不能放在`extend\form`下,需要放在`\public\extend\form`。具体请参考[升级指导](升级指导.md) 虽然目前ZBuilder提供了超过30种表单项,但还是不足以满足用户的需求。为此,我们对表单构建器进行了功能扩展,让开发者可以自己定义表单项。 由于刚支持该功能,可能有些地方还不够人性化或者满足需求,所以在使用中若有什么更好的建议,欢迎到[论坛](http://bbs.dolphinphp.com/)发帖。 下面介绍如何扩展表单项,这里以扩展“颜色选择器”来作为演示。虽然ZBuilder本身已经有“颜色选择器”,但我们这次用自定义扩展的方式实现相同的功能。 ### 1.建立表单项目录 首先,我们在目录:`extend\form`下新建一个目录,名字就`test`。这个目录名称就是我们要扩展的表单项类型名称。 >[danger] 注意,目录名为全小写,并且不要和已存在的表单项类型冲突。 ![](https://box.kancloud.cn/c07d9d35f46648d547c2ddbaa5836005_177x73.png) ### 2.放入颜色选择器需要的文件(可选) 这一步是可选的,如果你创建的表单项无需依赖任何js或css,可以跳过这一步。因为颜色选择器需要依赖一些js和css文件,所以要把相关的文件放在该目录下。 ![](https://box.kancloud.cn/725e3d0d79a8e8eced208af1080622b3_261x87.png) ### 3.建立入口文件 接着,我们在`test`目录下创建名称为`Builder.php`的入口文件,这个文件名是固定的,必须为`Builder.php`。 然后我们需要在该入口文件中,创一个`item`方法,这个方法是用于在调用ZBuilder时供使用者调用的方法。 ~~~ <?php namespace form\test; class Builder { /** * 取色器 * @param string $name 表单项名 * @param string $title 标题 * @param string $tips 提示 * @param string $default 默认值 * @param string $mode 模式:默认为rgba(含透明度),也可以是rgb * @param string $extra_attr 额外属性 * @param string $extra_class 额外css类名 * @author 蔡伟明 <314013107@qq.com> * @return mixed */ public function item($name = '', $title = '', $tips = '', $default = '', $mode = 'rgba', $extra_attr = '', $extra_class = '') { return [ 'name' => $name, 'title' => $title, 'tips' => $tips, 'value' => $default, 'mode' => $mode, 'extra_class' => $extra_class, 'extra_attr' => $extra_attr, ]; } } ~~~ >[info] 命名空间固定为`form\表单项名` `item`方法的参数是自定义的,你的表单项需要用到什么参数,就写什么参数,根据实际情况来写。它需要返回一个数组,这个数组就是你在模板中需要用到的数据。如果需要在这里么进行一些判断或者处理,都是可以的,只要最终反回一个数组即可。 >[danger] 需要注意的是,返回的数据中,必须包含name,而且不得包含键为`type`的数组元素,系统会自动添加上对应的`type`,比如上面的代码,实际上输出到页面时,会自动添加上`type => 'test'`。 ### 4.定义需要加载的js和css文件(可选) 这一步也是可以选的,如果你的表单项并不依赖任何js或css文件,可以忽略这一步。 ~~~ <?php namespace form\test; class Builder { /** * 取色器 * @param string $name 表单项名 * @param string $title 标题 * @param string $tips 提示 * @param string $default 默认值 * @param string $mode 模式:默认为rgba(含透明度),也可以是rgb * @param string $extra_attr 额外属性 * @param string $extra_class 额外css类名 * @author 蔡伟明 <314013107@qq.com> * @return mixed */ public function item($name = '', $title = '', $tips = '', $default = '', $mode = 'rgba', $extra_attr = '', $extra_class = '') { return [ 'name' => $name, 'title' => $title, 'tips' => $tips, 'value' => $default, 'mode' => $mode, 'extra_class' => $extra_class, 'extra_attr' => $extra_attr, ]; } /** * @var array 需要加载的js */ public $js = [ 'bootstrap-colorpicker/bootstrap-colorpicker.min.js', 'test.js' // 默认加载当前表单项目录下的test.js ]; /** * @var array 需要加载的css */ public $css = [ 'bootstrap-colorpicker/css/bootstrap-colorpicker.css' ]; } ~~~ 在这里,我们加入了两个js文件,一个是颜色选择器的js文件,一个是用来创建颜色选择器的js文件。另外加入了一个css样式文件。 >[info] ### 如果是1.0.7版本以上,则可以使用模板变量替换来调用公共资源 ~~~ public $js = [ '__LIBS__/bootstrap-colorpicker/bootstrap-colorpicker.min.js', 'test.js' ]; ~~~ 表示引用`/public/static/libs/bootstrap-colorpicker/bootstrap-colorpicker.min.js`,更多资源路径请参考[变量参考](变量参考.md) `test.js`内容如下: ~~~ $(document).ready(function () { jQuery('.js-colorpicker').each(function(){ var $colorpicker = jQuery(this); var $colorpickerMode = $colorpicker.data('colorpicker-mode') ? $colorpicker.data('colorpicker-mode') : 'hex'; var $colorpickerinline = $colorpicker.data('colorpicker-inline') ? true : false; $colorpicker.colorpicker({ 'format': $colorpickerMode, 'inline': $colorpickerinline }); }); }); ~~~ ### 5.创建表单项模板文件 入口文件写好后,我们需要创建一个模板文件,用来输出内容。因为我们扩展的表单项类型为`test`,所以模板文件名必须为`test.html`。 代码如下: ~~~ <div class="form-group col-xs-12 {$extra_class|default=''}" id="form_group_{$name}"> <label class="col-xs-12" for="{$name}">{$title|htmlspecialchars}</label> <div class="col-sm-12"> <div class="js-colorpicker input-group" data-colorpicker-mode="{$mode == '' ? 'rgba' : $mode}"> <input class="form-control" type="text" id="{$name}" name="{$name}" value="{$value|default=''}" placeholder="请从右边选择颜色" {$extra_attr|default=''}> <span class="input-group-addon"><i style="background-color: rgb(92, 144, 210);"></i></span> </div> {notempty name="tips"} <div class="help-block">{$tips}</div> {/notempty} </div> </div> ~~~ ### 6.调用表单项方法 自此,所有准备工作已经完成,接下来就是使用我们自定义的表单项了,完整的表单项目录是这样的。 ![](https://box.kancloud.cn/5aac1913a39e994121e74e22c6812820_290x148.png) 因为我们定义的表单项类型为`test`,所以在ZBuilder中可以直接使用`->addTest()`来创建表单项,add接上类型名称首字母大写。 ~~~ return ZBuilder::make('form') ->addTest('color', '取色器') ->fetch(); ~~~ ![](https://box.kancloud.cn/6de61520c8f84b55cc5f2c09f8b6323a_1566x211.png) 也可以用->addFormItem()方法 ~~~ return ZBuilder::make('form') ->addFormItem('test', 'color', '取色器') ->fetch(); ~~~ 或者->addFormItems()方法 ~~~ return ZBuilder::make('form') ->addFormItems([ ['text', 'username', '用户名'], ['test', 'color', '取色器'] ]) ->fetch(); ~~~ ![](https://box.kancloud.cn/151f139ef6f806d14dfbdf63dca0cb01_1567x266.png) 当然,也支持布局,但需要在模板中添加一段代码 `col-md-{$_layout|default='12'}` `test.html`最终是这样的 ~~~ <div class="form-group col-md-{$_layout|default='12'} col-xs-12 {$extra_class|default=''}" id="form_group_{$name}"> <label class="col-xs-12" for="{$name}">{$title|htmlspecialchars}</label> <div class="col-sm-12"> <div class="js-colorpicker input-group" data-colorpicker-mode="{$mode == '' ? 'rgba' : $mode}"> <input class="form-control" type="text" id="{$name}" name="{$name}" value="{$value|default=''}" placeholder="请从右边选择颜色" {$extra_attr|default=''}> <span class="input-group-addon"><i style="background-color: rgb(92, 144, 210);"></i></span> </div> {notempty name="tips"} <div class="help-block">{$tips|clear_js}</div> {/notempty} </div> </div> ~~~ 然后我们就可以使用布局参数了 ~~~ return ZBuilder::make('form') ->addText('username', '用户名') ->addTest('color', '取色器') ->layout(['color' => 6]) ->fetch(); ~~~ ![](https://box.kancloud.cn/f83acaf61ed919ec984223a5f915de9c_1569x212.png) 当然,也可以这样。 ~~~ return ZBuilder::make('form') ->addText('username', '用户名') ->addFormItem('test:6', 'color', '取色器') ->fetch(); ~~~ 或者这样 ~~~ return ZBuilder::make('form') ->addFormItems([ ['text', 'username', '用户名'], ['test:6', 'color', '取色器'] ]) ->fetch(); ~~~ 也可以放在表单分组中。 ~~~ return ZBuilder::make('form') ->addText('username', '用户名') ->addGroup([ '分组1' => [ ['test', 'color', '取色器'] ], '分组2' => [ ['text', 'nickname', '昵称'] ] ]) ->fetch(); ~~~ ![](https://box.kancloud.cn/a8fb12a1037741adbf97191bf902bd1d_1583x358.png) >[danger] ### 注意,如果框架版本为1.1.0以上,则自定义表单项的静态资源不能放在`extend\form`下,需要放在`\public\extend\form`。具体请参考[升级指导](升级指导.md)