简介

Wordpress表单模块，以短代码形式添加表单控件。有自定义的属性供设置。通过wp_mail()函数（基于PHPMailer）实现发送邮件功能。可将表单内容保存到数据库中。附件（文件、图片）可保存到服务器目录中，并且有较高的灵活性。非常适合入门级Wordpress开发者使用。

功能特点

  1. 可以将邮件保存在网站的数据库中。并可以导出邮件内容为xls文件。
  2. 增加了验证步骤，优化了验证逻辑，并通过添加陷阱的方式尽可能杜绝垃圾邮件。
  3. 支持google reCAPTCHA。
  4. 有一定自动化的步骤的同时增加了一些自定义的空间，适用于有一定wordpress开发经验的开发者。
  5. SMTP功能可开启或者关闭
  6. 可自定义自动回复邮件的内容。
  7. 可修改关键位置的文本。
  8. 日本邮编输入可自动显示地址信息。
  9. 可上传普通附件，并可以选择是否将附件保存到服务器。（注意，保存选项共同作用于附件和图片）
  10. 可以上传图片并按预定尺寸裁切，并可以选择是否将附件保存到服务器。（注意，保存选项共同作用于附件和图片）
  11. 支持中、日、英三种语言。提示文本处提供三种语言的缺省文本。
  12. 可以做独立的“发送成功页面”。

安装

该模块不是一个标准的插件，需要将模块文件放到指定位置进行引用。
  1. 下载源码
  2. 组件的位置有严格的要求，将源码中的contact-form目录放在主题根目录下的pack文件夹下。即：模块里opeform-ajax-common.php文件为例，它的位置为：wp-content/themes/主题文件夹/pack/contact-form/opeform-ajax-common.php。
  3. 将代码： 
    require 'pack/contact-form/index.php';
    添加到主题的functions.php文件的任意位置以引用该功能。如果基于该模块二次开发，应酌情考虑引入位置。
  4. 进入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为不发送自动回复邮件。
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 screen 表单确认屏幕顶部文字
Thanks 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后页面右下角显示的标志。google reCAPTCHA

Test（测试）

Recipient's email 收件人邮箱。

创建模版

这部分内容是Wordpress创建模版页面的内容。简单创建模版有两种：

  1. 创建与页面别名一致的模版页，假设页面别名为contact。那么，page-contact.php就会自动成为该页面的模版。
  2. 若创建一个不以page-开头的模版页面，例如contact.php。页面顶部填写注释： 
    <?php /* Template Name: Contact */ ?>
    这样，在创建页面时，可以在编辑器右边栏“模版”选项卡中找到该模版。

添加HTML基础结构

请严格遵守下面的结构。一个.item对应一个.control，一个.control里有一个控件短代码。

  1. 最外层块有ope-form这个class
  2. 每组控件在.item这个块里
  3. .title这个块不是必须的
  4. 控件在.control这个块里，通过短代码形式添加控件
  5. 肯定要有个提交按钮

<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-text（确认步骤提示文字），data-thanks-text（发送成功屏幕文字），data-thanks-page（发送成功页面），data-return-redirect（发送成功返回的URL）这几个自定义的属性。如果不设置，将被自动设置成默认值。
需要注意的是data-thanks-page的使用方法。

data-thanks-page属性用于设置“发送成功页面”，该页面是相对于当前页面的路径。开发者需要自行创建页面及模版，将页面slug如下面的示例赋给data-thanks-page属性。
“发送成功页面”模版的顶部要有短代码echo do_shortcode('[opeform_thanks_page]');，用于阻止重复刷新该页面。
默认表单的一切步骤都在同一页面完成，包括发送成功提示。所以，如果自定义的“发送成功页面”，最后发送成功提示将转到data-thanks-page页面。
如果使用data-thanks-page定义了自定义的“发送成功页面”，data-thanks-text和data-return-redirect是无效的。

基于上述规则，示例如下：

<div class="ope-form"
data-form-category="简历箱"
data-confirm-text="请确认您输入的信息"
data-thanks-text="感谢您的支持"
data-return-redirect="https://localhost/mysite/">
...
</div>

或：

<div class="ope-form"
data-form-category="简历箱"
data-confirm-text="请确认您输入的信息"
data-thanks-page="./thanks/">
...
</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（其它）。默认不显示需要填写“其它”具体项目的文本框。只有选择“其他”项时才会显示。
值有三部分组成，用半角逗号分开。

  1. 第一个为checkbox项目名称，以上面示例为例，选项有：男，女，其他
  2. 第二个为是否为必选项，如果不是必须，留空即可。
  3. 第三个为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可以添加一些自定义的进度条什么的。
  • 如果需要修改表单样式，请在主题的样式表中设置样式覆盖模块的样式。不要修改模块中的样式表。