简介
wordpress表单模块，以短代码形式添加表单控件。有自定义的属性供设置。基于PHPMailer实现发送邮件功能。可将表单内容保存到数据库中。附件（文件、图片）可保存到服务器目录中，并且有较高的灵活性。非常适合入门级Wordpress开发者。
用于Wordpress站点的功能模块。功能有表单验证，验证码功能，防跨站请求伪造攻击，表单数据存储，保存在数据库中的数据及一些敏感信息经过SHA-256算法加密。
功能特点
- 可以将邮件保存在网站的数据库中。并可以导出邮件内容为xls文件。
- 增加了验证步骤，优化了验证逻辑，并通过添加陷阱的方式尽可能杜绝垃圾邮件。
- 支持google reCAPTCHA。
- 有一定自动化的步骤的同时增加了一些自定义的空间，适用于有一定wordpress开发经验的开发者。
- SMTP功能可开启或者关闭
- 可自定义自动回复邮件的内容。
- 可修改关键位置的文本。
- 日本邮编输入可自动显示地址信息。
- 可上传普通附件，并可以选择是否将附件保存到服务器。（注意，保存选项共同作用于附件和图片）
- 可以上传图片并按预定尺寸裁切，并可以选择是否将附件保存到服务器。（注意，保存选项共同作用于附件和图片）
- 支持中、日、英三种语言。提示文本处提供三种语言的缺省文本。
安装
该模块不是一个标准的插件，需要将模块文件放到指定位置进行引用。
- 下载源码
- 组件的位置有严格的要求，将源码中的contact-form目录放在主题根目录下的pack文件夹下。即：模块里opeform-ajax-common.php文件为例，它的位置为：wp-content/themes/主题文件夹/pack/contact-form/opeform-ajax-common.php。
- 将代码：
添加到主题的functions.php文件的任意位置以引用该功能。如果基于该模块二次开发，应酌情考虑引入位置。require 'pack/contact-form/index.php'; - 进入Wordpress后台，点击左导航“OPE Form Config”进入配置页面。
至此，基本配置步骤结束。
配置基本信息
进入后台，左导航选择OPE Form Config（配置）进入配置页面。下面是对照表及描述。
带有标记的项目，可在模版页面的配置中进行覆盖。
Primary settings（主要信息）
| Recipient administrator email | 管理员邮箱，用于接收网站提交的邮件。如添加多个邮箱请用半角逗号分开。 |
| Recipient administrator email CC | 管理员邮箱抄送邮箱，用于接收网站提交的邮件。如添加多个邮箱请用半角逗号分开。 |
| Email from address | 发件箱吗。不支持多个邮箱。 |
| Email from name | 发件人 |
| Auto reply | 自动回复。On为发送自动回复邮件，Off为不发送自动回复邮件。 |
| Sending Method | 发送方式。使用模块内置PHPMailer()方式或者Wordpress内置wp_mail()函数发送，主要区别在于两者PHPMailer()版本可能不一样。如果遇到发送错误，可尝试替换成你另一个。本模块内置的PHPMailer()相关类文件也可以自行从PHPMailer Github页面下载最新版替换。Wordpress的内置wp_mail()函数所引用的PHPMailer的版本要取决于当前Wordpress版本。 |
| Email Format | 邮件格式。HTML格式与文本（Plain text）格式。 |
| Fields check | 验证顺序。Later为提交时验证，Immediately为立即验证。 |
| Validate Code | 是否使用验证码。ON为开，OFF为禁用。 |
Data store（数据保存）
| Store mail in DB | 是否将表单提交的内容保存到数据库中。ON为保存，OFF为不保存。 |
| Post type name (admin menu) | 自定义文章类型。例：邮箱。注意：此自定义文章类型不是传统的custom post type。custom post type的资料依然保存在wp_posts和wp_postmeta表中。但是该模块的内容保存在{prefix}opeform_mailbox（用来保存邮件）和{prefix}opeform_mailbox_terms（用来保存邮件分类）表中。所以想要二次开发，检索数据库内容时需要自定义查询函数。 |
| Category name (admin menu) | 自定义文章类型分类菜单名称。例：邮箱分类。注意：此自定义文章分类不是传统的terms。terms的资料保存在wp_terms，term_taxonomy和wp_term_relationships表中。但是该模块的内容保存在{prefix}opeform_mailbox（用来保存邮件）和{prefix}opeform_mailbox_terms（用来保存邮件分类）表中。所以想要二次开发，检索数据库内容时需要自定义查询函数。 |
Text（文本设置）
| Admin eamil title/subject | 管理员收到的邮件标题。例：来自XXX的邮件。如果需要在标题中插入表单中填写的姓名和（或）邮箱，可使用{{from_name}}和（或）{{from_email}}。注意，仅支持{{from_name}}和（或）{{from_email}}，且，在模版中使用短代码时，短代码中设置了from_name和from_email为true。如下： |
| Auto reply eamil title/subject | 自动回复邮件标题。例：来自XXX的邮件，我们已经收到您提交的信息，感谢您对本公司的支持... |
| Auto reply email content top | 自动回复邮件主题内容顶部文本 |
| Auto reply email content bottom | 自动回复邮件的底部内容 |
| Text at the top of the confirm page | 表单确认页面顶部文字 |
| Thanks page text | 邮件发送成功页面提示文字 |
| Button "Next" | “下一步”按钮文字 |
| Button "Prev" | “上一步”按钮文字 |
| Button "Send" | 提交按钮文字 |
| Alert text of mandatory/required item | “必须”项目提示文字 |
| Alert text of mandatory/required item for “Other” field | “其它”项目需要填写具体内容时的提示文字 |
| Alert text when error occurred | 当发生错误时的提示文字 |
| Invalid format of email address | 邮件格式不正确 |
| Invalid format of phone number | 电话格式不正确 |
| Email does not match previously entered | 确认邮箱与输入的邮箱不匹配 |
| Validate Code not matched | 验证码不正确 |
| Content contains illegal character string | 内容包含不合规字符 |
| Send failed | 发送失败 |
| Authentication failed | 验证失败 |
| Button "Return" | “返回”按钮 |
| Button "File upload" | “上传”按钮 |
| File too large | 文件体积过大 |
| File type unsupported | 不支持的文件类型 |
| Select image and crop | 选择图片并裁切 |
| Button "Image crop" | “裁切图片”按钮 |
| Button "Cancel crop" | “放弃裁切”按钮 |
| Unsupported image file type | 不支持的图片格式 |
| Alert text of image too small | 图片尺寸过小的提示文字 |
| Alert text of image too large | 图片尺寸过大的提示文字 |
| Image upload text | “上传图片”文字 |
SMTP features（SMTP配置）
| SMTP support | SMTP支持 |
| host | 域名 |
| user name | 用户名 |
| password | 密码 |
| port | 端口 |
| secure type | 加密类型。端口465通常是SMTPS,端口587通常是startTLS。 |
Attechment（附件）
| File upload folder name | 上传文件夹名称。 注意:名称确定后，保存配置后，需要确认根目录有没有创建同名文件夹。因为权限问题，程序不一定能自动创建文件夹。 |
| Remove attachments when delete email | 删除邮件时删除相应的附件 |
| Save files to server | 将文件保存到服务器上 |
| Upload MAX size | 上传大小。注意：这里设置的大小无法大于服务器设置的大小 |
| Image crop width | 裁切图片的宽度（px） |
| Image crop height | 裁切图片的高度（px） |
| Source image width | 上传图片的最大宽度（px） |
| Source image height | 上传图片的最大高度（px） |
Ohter（其它）
| Automatic return | 发送成功后自动返回 |
| waiting time | 自动返回延迟时间 |
| Back to URL | 返回页面的URL。默认返回本页面。 |
| Session lifetime | Session有效期 |
| Timezone | 时区。参考文档：https://www.php.net/manual/en/timezones.php |
| Name Format | 用户名称格式 |
| Auto fill address via zipcode | 自动通过邮编填充地址（仅对日本邮编有效） |
| Include DEBUG info in admin email | 管理员邮箱是否包含DEBUG信息。如IP，来源，客户端信息等。 |
Google reCAPTCHA
| Google reCAPTCHA v3 | Google reCAPTCHA 第三版 |
| Badge Visibility | 徽标可见性。Show显示，Hide隐藏。徽标就是开启google reCAPTCHA后页面右下角显示的标志。 |
Test（测试）
| Recipient's email | 收件人邮箱。 |
创建模版
这部分内容是Wordpress创建模版页面的内容。简单创建模版有两种：
- 创建与页面别名一致的模版页，假设页面别名为contact。那么，page-contact.php就会自动成为该页面的模版。
- 创建一个不以page-开头的模版页面，例如contact.php。页面顶部填写注释：
这样，在创建页面时，可以在编辑器右边栏“模版”选项卡中找到该模版。<?php /* Template Name: Contact */ ?>
添加HTML基础结构
请严格遵守下面的结构。一个.item对应一个.control，一个.control里有一个控件短代码。
- 最外层块有ope-form这个class
- 每组控件在.item这个块里
- .title这个块不是必须的
- 控件在.control这个块里，通过短代码形式添加控件
- 肯定要有个提交按钮
<div class="ope-form">
<div class="item">
<div class="title">姓名</div>
<div class="control">
<?php echo do_shortcode('[opeform use="text"]'); ?>
</div>
</div>
<div class="item">
<div class="title"></div>
<div class="control">
<?php echo do_shortcode('[opeform use="submit"]'); ?>
</div>
</div>
</div>最外层的块还有data-form-category，data-confirm-page-text，data-thanks-page-text，data-return-redirect这四个自定义的属性。分别代表该表单所处分类，确认页面提示文字，发送成功页面文字，发送成功返回的URL。如果不设置，将被自动设置成默认值。示例如下：
<div class="ope-form"
data-form-category="简历箱"
data-confirm-page-text="请确认您输入的信息"
data-thanks-page-text="感谢您的支持"
data-return-redirect="https://localhost/mysite/">
...
</div>短代码介绍
文本控件
即生成后的html代码为：
<input type="text" ...
[opeform use="text" required="" from_name="true" class="" title="Name" name="user_name" length="40" placeholder=""]- use为用途。可选：text,tel,email,select,checkbox,radio,verification,textarea,submit,image（图片），file(附件)
- required是否是必选项。可选: true,false
- from_name是特殊选项，用于在邮件内容中显示发件人。如果设置成了from_name="true"，该字段内的内容会成为发件人。
- title为邮件及数据库中该字段的标题。
- name为该控件的名称用于数据传送，除了checkbox或者radio控件外，其它控件不可重复。
- length为输入长度，length="40"为例，可输入40个汉字或者40个英文字母。
- placeholder为占位文本
- class类，每个空间都可以设置。下面的说明中不再赘述。
邮箱控件
即生成后的html代码为：
<input type="email" ...
[opeform use="email" required="" title="" from_email="true" name="user_email" confirm="true" length="50" placeholder=""]- confirm="true"用来确认该字段内容是否跟上面的内容一样。只适用于邮箱的验证。
- from_email是特殊选项，用于在邮件内容中显示发件人邮箱。如果设置成了from_email="true"，该字段内的内容会成为发件人邮箱。也是自动回复邮件的收件人。
select控件
即生成后的html代码为：
<select name="xxx" ...
[opeform use="select" required="" title="" name="" option=""]- option需要设置。多个项目通过半角逗号分开。即便使用下面的动态数据，也需要设置为空（option=""）。
- dynamic-number-range="nowYear-16~nowYear-60"范围是：当前年份减16到当前年份减60
- dynamic-number-range="nowYear"范围是：从当年到公元0年。
- dynamic-number-range="1~200"范围是：1到200
- dynamic-number-range="nowYear~nowYear+30"范围是：当前年份到当前年份加30
如果需要不同的选项发送至不同的邮箱，那么在option值的每个项目后面加上对应的邮箱用竖线分割，多个邮箱用半角分号分开。比如：
[opeform use="select" option="项目1|a@domain.com;a2@domain.com;a3@domain.com,项目2|b@domain.com,项目3|c@domain.com"]checkbox复选框控件
即生成后的html代码为：
<input type="checkbox" ...
[opeform use="checkbox" required="" title="" name="" option="" quantity=""]- option选项，以半角逗号分开
- quantity为最多选择数量
如果需要不同的选项发送至不同的邮箱，那么在option值的每个项目后面加上对应的邮箱用竖线分割，多个邮箱用半角分号分开。比如：
[opeform use="checkbox" option="项目1|a@domain.com;a2@domain.com;a3@domain.com,项目2|b@domain.com,项目3|c@domain.com"]如果有其它项目，且需要填写具体项目，短代码示例如下：
[opeform use="checkbox" required="" quantity="2" title="性别" name="gender" option="男,女" hasother="其他,required,请填写其他项目"]这里有个特殊属性hasother，就是has（有）other（其它）。默认不显示需要填写“其它”具体项目的文本框。只有选择“其他”项时才会显示。
值有三部分组成，用半角逗号分开。
- 第一个为checkbox项目名称，以上面示例为例，选项有：男，女，其他
- 第二个为是否为必选项，如果不是必须，留空即可。
- 第三个为placeholder值。
如果既不是必须，也没有placeholder：hasother="其他,,"。半角逗号是要有的。
如果其它项目也需要发送至不同的邮箱，那么在hasother值的最后加上对应的邮箱用竖线分割，多个邮箱用半角分号分开。比如：
[opeform use="checkbox" option="男,女" hasother="其他,required,请填写其他项目|a@domain.com;a2@domain.com"]radio单选框控件
即生成后的html代码为：
<input type="radio" ...
[opeform use="radio" required="" title="" name="" option=""]- option选项，以半角逗号分开
如果需要不同的选项发送至不同的邮箱，那么在option值的每个项目后面加上对应的邮箱用竖线分割，多个邮箱用半角分号分开。比如：
[opeform use="radio" option="项目1|a@domain.com;a2@domain.com;a3@domain.com,项目2|b@domain.com,项目3|c@domain.com"]验证码
[opeform use="verification" notice=""]- notice为右侧提示文本，只要使用了use="verification"，它为必填项。不需要设置required=""
- 短代码中涉及到引号中包含引号的情况，请使用反斜杠来转义。如can’t，应该写成can\’t
提交按钮
[opeform use="submit"]上传并裁切图片
[opeform use="image" required="" crop="" title="" name=""]- crop为裁切属性。crop的值为裁切尺寸。如果不设置crop属性将以原尺寸上传。
- 假设裁切尺寸为300pxX400px，crop的值为300x400。
附件上传
[opeform use="file" required="" size="" title="" name="" accept=""]- accept为允许上传的文件类型。如：.pdf,.xls,.ppt,.pptx,.doc,.docx,.xlsx
- size为上传限制，需要填写单位。比如：2MB,100KB,0.5MB。该值无法大于全局配置的上传大小。
- 如果需要多个附件，需要创建多个class=”item”容器。且，短代码的属性name要不一样。name重复只能上传其中一个附件。
- 有时会遇到设定了.jpg扩展名，上传扩展名为jpg的图片却提示扩展名不对的错误。原因是.jpg图片的类型实际上是jpeg，所以要设定成accept=”.jpg,.jpeg”。
自定义样式
- 默认启用后，body元素会有class：has-ope-form和ope-form-step-1。进入确认页面后ope-form-step-1会变成ope-form-step-2。进入发送页面时ope-form-step-2会变成ope-form-step-3。基于这些class可以添加一些自定义的进度条什么的。
- 如果需要修改表单样式，请在主题的样式表中设置样式覆盖模块的样式。不要修改模块中的样式表。