WordPress 一直没有为开发者提供一个足够方便的表单生成类。而在Theme Development过程中,制作表单往往是一个必不可少的工作,为了提高开发效率,增加WordPress主题和插件的项目质量,我们基于 Nette Forms 表单库开发了一个 WordPress 表单生成库 —— Wenprise Forms。
Wenprise Forms 提供了流畅的 API,支持 Web 表单的生成、后端验证、前端验证、根据表单选项显示或者隐藏等操作,并和 WordPress 结合、支持随机数验证、颜色选择、可视化编辑器、Ajax 上传等高级功能。
Wenprise Form 的 Git 仓库地址为:https://github.com/iwillhappy1314/wenprise-forms 欢迎有兴趣的朋友参与开发,使用的时候遇到问题也可以到 Github 中提 Issue。
Wenprise Form 安装
Wenprise Forms 已经发布到 Packagist 中,如果您已经使用 Composer 管理你的主题或插件依赖,直接运行以下命令即可安装。
composer require wenprise/forms
如果你还没有使用 Composer,我们建议你使用 Composer 管理您的项目依赖。因为 Wenprise Form 库目前并未提供包含入口文件引入的方式,以后也不会支持。
Wenprise Form 快速使用指南
在需要显示表单的页面使用下面代码,即可添加一个 action 为 POST,包含一个名为 first_name 和一个提交按钮。表单提交成功后,直接在页面显示提交的表单内容。
use Wenprise\Forms\Form;
$form = new Form;
// 设置表单渲染方法,可以根据您使用的前端框架,设置自定义渲染方法
wprs_form( $form );
// 设置表单提交方法
$form->setMethod( 'POST' );
// 设置表单字段
$form->addText('first_name', esc_html__('First Name', 'wprs') );
$form->addSubmit( 'send', esc_html__('Save', 'wprs') );
// 验证表单并显示表单值
if ( $form->isSuccess() ) {
// 获取前端提交过来的表单值
$values = $form->getValues();
// 通过访问类属性的方式获取表单值
$first_name = $values->first_name;
echo $first_name;
}
echo $form;
Wenprise Form 表单方法
Wenprise Forms 中包含了多种很方便的表单方法,可以用来设置表单的各种属性,简单介绍如下。除了下面介绍的,还有一些高级表单方法,因为不常用到,在这里就不多介绍,有兴趣的朋友请参考源代码使用。
// 设置接收插件提交的 Url
$form->setAction('/submit.php')
// 设置表单提交方法
$form->setMethod( 'POST' );
$form->addText('first_name', esc_html__('First Name', 'wprs'))
->setRequired(false) // 设置必填项
->setValue() // 设置表单值
->setDefaultValue('') // 设置默认值
->setDisabled(true) // 设置禁用属性
->setOmitted() // 提交时忽略此项的值
->addRule() // 添加验证规则
->->setAttribute('data-cond', [name=street] == magic) // 设置根据其他字段输入显示的功能
->setHtmlType(); // 设置文本字段的 Html 类型,如 number
// 判断表单是否提交成功,每个表单均验证通过才为提交成功
$form->isSuccess();
// 获取表单提交的值,
// 获取到的值是一个对象,可以直接通过 $values->first_name 的方法访问表单项的值
$values = $form->getValues();
各表单类型使用方法
文本字段
$form->addText('age', esc_html__('Age:', 'wprs'));
文本段落
$form->addTextArea('note', esc_html__('Note:', 'wprs'));
Email 字段
$form->addEmail('email', esc_html__('Email:', 'wprs'));
整数字段
$form->addInteger('level', esc_html__('Level:', 'wprs'));
上传字段
$form->addUpload('thumbnail', esc_html__('Thumbnail:', 'wprs'));
多文件上传字段
$form->addMultiUpload('files', esc_html__('Files', 'wprs'));
Ajax 文件上传字段
$form->addAjaxUpload('files', esc_html__('Files', 'wprs'))
->setAttribute('data-url', home_url('wp-admin/admin-ajax.php?action=wprs_upload'));
表单上传字段需要后段支持,参考 Ajax 后段如下。
add_actions(['wp_ajax_wprs_upload', 'wp_ajax_nopriv_wprs_upload'], function ()
{
if ( ! is_user_logged_in()) {
return false;
}
require_once(ABSPATH . 'wp-admin/includes/image.php');
require_once(ABSPATH . 'wp-admin/includes/file.php');
require_once(ABSPATH . 'wp-admin/includes/media.php');
$attachment_id = media_handle_upload('file', 0);
$thumb_url = wp_get_attachment_thumb_url($attachment_id);
$origin_url = wp_get_attachment_url($attachment_id);
$thumb = get_post($attachment_id);
$file_data = [
'id' => $attachment_id,
'original' => $thumb->post_title,
'size' => $thumb->size,
'state' => 'SUCCESS',
'title' => $thumb->post_title,
'type' => $thumb->post_mime_type,
'thumb' => $thumb_url,
'url' => $origin_url,
];
wp_send_json($file_data, 200);
return false;
});
Hidden Fields
$form->addHidden('userid');
选择框字段
$form->addCheckbox('agree', esc_html__('I agree with terms', 'wprs'));
单选字段
$form->addRadioList('gender', esc_html__('Gender:', 'wprs'), [ 'm' => 'male', 'f' => 'female', ]);
多选字段
$form->addCheckboxList('colors', esc_html__('Colors:', 'wprs'), [ 'r' => 'red', 'g' => 'green', 'b' => 'blue', ]);
下拉选择字段
$form->addSelect('country', esc_html__('Country:', 'wprs'), $countries);
Chosen 下拉选择字段
utilization jQuery Chosen 插件实现,可以在最后一个数组中设置 Chosen 插件的参数。
$form->addChosen('chosen', esc_html__('Chosen', 'wprs'), ['aaaa', 'bbbb',], []);
下拉多选字段
$form->addMultiSelect('options', esc_html__('Pick many:', 'wprs'), $options);
Chosen 下拉多选字段
$form->addMultiChosen('chosen2', esc_html__('Multi chosen', 'wprs'), ['aaaa', 'bbbb'], []);
密码字段
$form->addPassword('password', esc_html__('Password:', 'wprs'));
按钮字段
$form->addButton('raise', esc_html__('Raise salary', 'wprs'));
WordPress 随机数字段
添加 WordPress 随机数验证,表单提交的时候会自动验证该字段,不用再另行验证。
$form->addCsrf('post-form', esc_html__('Nonce invalidate', 'wprs');
WordPress 可视化编辑器
使用 WordPress 内置的 wp_editor 函数 插件实现,可以通过最后一个数组修改插件的表现。
$form->addEditor('post_extra', esc_html__('Extra content', 'wprs'), []);
数字滑动区间选择
utilization Ion.RangeSlider 实现,可以在最后一个数组中设置该 jQuery 插件的表现。
$form->addEditor('price', esc_html__('Price', 'wprs'), []);
日期选择
$form->addDatePicker('date', esc_html__('Date', 'wprs'), []);
颜色选择
$form->addColorPicker('color', esc_html__('Color', 'wprs'), []);
提交字段
$form->addSubmit('submit', esc_html__('Register', 'wprs'));
图片提交字段
$form->addImage('submit', '/path/to/image');
签名字段
$form->addSignature('signature', esc_html__('Signature', 'wprs'));
签名生成的图片以 Base64 编码提交,在后端保存的时候,可以根据需要保存到数据库或保存为文件。
该库可以在开发 WordPress 自定义字段、自定义设置页面、自定义小工具时使用,非常的方便。我们已经在多个项目中使用,客户反映良好,有需要的朋友可以试试。当然,如果有问题或建议,也欢迎在评论中提出。