README

简单但灵活的联系表单构建器，带自定义字段、验证和被动反垃圾邮件。

安装

GitHub 克隆到 /plugins 目录

git clone https://github.com/jan-vince/smallcontactform

OctoberCMS 后端

只需在以下搜索字段中查找 'Small Contact Form'

设置 > 更新 & 插件 > 安装插件

权限

设置 > 管理员

您可以设置权限以限制对 设置 > 小插件 > 联系表单 和消息列表的访问。

使用 composer 安装

编辑 composer.json 并添加新的仓库

"repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/jan-vince/smallcontactform"
    }
]

在命令行中运行

composer require janvince/smallcontactform

设置新的联系表单

设置 > 小联系表单

表单

您可以为 CSS 类名和一般成功/错误消息设置自己的名称。
如果需要，可以使用占位符代替标签。
成功提交后可以隐藏表单。

启用 AJAX

默认情况下，发送表单将触发页面刷新。使用 AJAX，可以不刷新页面完成所有操作，这会更友好。
如果用户的浏览器不支持（或已禁用）JavaScript，发送后表单仍然会在页面刷新后工作。

对于启用 AJAX 的表单，可以在发送前要求确认对话框。

添加资产

如果您想快速开始，可以启用“添加资产”复选框 - 然后添加 CSS 和 JS 资产。
这将包括必要的样式（Bootstrap、AJAX、October AJAX）和脚本（jQuery、Bootstrap、October AJAX 框架和附加组件）。

但是，您必须像这样将 Twig 标签 {% styles %} 和 {% scripts %} 包含到布局或页面中

<html>
    <head>
        {% styles %}
    </head>
<body>

    {% page %}

    {% scripts %}

</body>

</html>

如果您想手动插入资产，可以这样做（或类似方法）

<html>
    <head>
        <link href="{{['~/modules/system/assets/css/framework.extras.css']|theme }}.css" rel="stylesheet">
    </head>
<body>

    {% page %}

    <script type="text/javascript" src="{{ [
        '@jquery',
        '@framework',
        '@framework.extras']|theme}}.js">
    </script>

</body>

</html>

备注

您可以在邮件模板中添加备注。字段可通过 {{ form_notes }} 访问。

可以在组件属性中覆盖表单备注内容。

发送按钮

您可以设置按钮类和文本。

表单发送后的重定向

您有一些选项来控制表单成功发送后的重定向。

在主要表单设置中，您可以允许重定向并设置固定 URL（内部或外部）
在组件属性（在 CMS 页面或布局中）中，您可以覆盖特定表单的主要重定向设置
您可以将动态重定向 URL 作为标记参数添加，例如 {% component 'contactForm' redirect_url = ('/success#'~this.page.id) %}

如果使用标记参数，请勿忘记在表单主要设置中允许表单重定向或在组件参数中（更合适）允许重定向！没有标记参数来允许重定向。

字段

在这里，您可以添加字段来构建您的联系（或其他）表单。

这个想法很简单（解决方案也是这样）

点击添加新字段
- 设置其名称（用于 <input name="{{name}}" id="{{name}}">），因此它应该是小写且没有特殊字符。
- 如果您需要，请设置标签（用于输入字段上方的描述性文本）
- 如果您希望光标自动跳转到此字段，请设置自动聚焦（如果勾选多个字段，光标跳转到第一个）

当选择下拉列表时，将显示值/选项重复器。您可以添加所需的所有值。

提示：您可以通过添加具有空 ID 的值来添加下拉列表空选项。

您还可以使用 自定义代码 来完全控制生成的代码。

还有一个 自定义内容 字段，可以在字段处添加格式化内容。

字段数据验证

您可以从预定义的规则中选择，或添加自定义验证器规则（请参阅文档）。

某些规则需要额外的验证模式，而有些则不需要。

您可以添加一个或多个验证规则及其错误消息。
错误消息将在输入字段上方显示。
您可以通过拖放左边的圆圈来重新排列字段（按 Ctrl+点击（在 MacOS 上按 Cmd+点击）右上角箭头可以折叠所有字段）。

提示：对于下拉验证，您可以在 pattern 字段中使用具有规则 in 的 custom 验证类型和 ID 列表（例如：1,2,3）。

注意：有一个 custom_not_regex 验证规则作为内置 regex 的反向。

列映射

系统将所有表单数据写入数据库，但为了快速查看，名称、电子邮件和消息列在消息列表中单独可见。

但是，您必须通过将其映射到您的表单字段来帮助系统识别这些列。

这些映射还用于自动回复电子邮件，其中至少电子邮件字段映射很重要。

反垃圾邮件

被动反垃圾邮件

这是一个非常简单的被动反垃圾邮件实现（受 Nette AntiSpam Control 启发）。

其背后的想法是检查表单发送的速度以及机器人捕捉字段是否被填写。

允许时，您可以设置表单延迟（以秒为单位），以防止过快的表单发送（通常由机器人引起）。您可以添加自定义错误消息（将在表单上方的通用错误消息框中显示）。
您可以为不支持 JavaScript 的浏览器添加反垃圾邮件字段标签和错误消息。
如果 JavaScript 正在运行，反垃圾邮件字段将自动隐藏并清除。

Google reCaptcha

Google reCaptcha 反垃圾邮件保护实现。

设置

首先，您必须在 reCaptcha 管理面板中创建新的 API 密钥对。

点击 reCaptcha 欢迎页面上的 获取 reCAPTCHA 按钮。设置标签并选择 reCAPTCHA v2（或 v2 无痕）选项，然后点击注册按钮。

将站点密钥和密钥复制到联系表单的设置字段中。

如果您希望联系表单自动将服务器脚本包含在布局中，请检查表单设置中的按钮。

reCaptcha 无痕

如果您使用 reCaptcha 无痕并希望隐藏 reCaptcha 徽章，您可以将以下内容添加到您的样式表中。

.grecaptcha-badge { 
    visibility: hidden;
}

但请记住，在您的联系表单附近添加有关隐私政策的信息（或作为自定义内容字段）。

检查发送者的 IP 地址

您可以通过限制来自单个 IP 地址的提交来添加额外的表单保护。

此检查具有自己的错误消息和用于设置最大提交的自定义字段。

电子邮件

邮件可以直接发送或排队（必须配置 OctoberCMS 队列！）。

不要忘记在 设置 > 邮件 > 邮件配置 中配置邮件首选项！

电子邮件模板中的数据

所有电子邮件模板中都可用变量

fields 是数组 [ '字段名称' => '帖子值' ]
fieldsDetails 是数组 [ '字段名称' => ['名称'，'值'，'类型'，...] ]
uploads 是上传的数组（类 System\Models\File）
messageObject 是所选消息的模型实例

允许自动回复

可以将电子邮件发送给表单发送者作为确认。

您必须输入电子邮件地址和姓名 - 它将用作 FROM 字段
邮件主题可以在这里手动添加（或在 设置 > 邮件 > 邮件模板（代码：janvince.smallcontactform::mail.autoreply） 中编辑）
邮件收件人地址和名称必须分配给表单字段（仅显示对应字段类型的选项 - 如果看不到，请尝试在字段选项卡中检查其类型）
可以设置邮件回复地址
消息字段也可以分配（并将单独保存到数据库中）

允许通知

一旦联系表单被发送，可以立即向提供的电子邮件地址（或逗号分隔的地址列表）发送通知。

通知电子邮件的 回复到 地址将设置为联系表单中的电子邮件地址（如果使用此字段）。

您也可以强制将 发件人 地址设置为在联系表单中输入的地址 - 但并非所有电子邮件系统都支持此功能！

翻译

您可以使用 RainLab Translate 插件进行翻译。

安装翻译插件后，请至少在 设置 > 翻译 > 管理语言 中添加两种语言。要使翻译生效，布局/页面中必须包含 localePicker 组件。

表单文本

大多数小型联系表单的文本可以直接在 设置 > 小型插件 > 联系表单 中编辑。

自定义表单字段

翻译插件目前不支持翻译单个重复字段，因此表单字段文本（标签、验证错误消息）必须现在在字典中进行翻译： 设置 > 翻译 > 翻译消息

请注意，表单字段标签将在第一次表单渲染后（在您的前端页面上）显示在字典中，验证错误消息将在第一次发送后显示。

电子邮件模板

您可以在 设置 > 邮件 > 邮件模板 中创建自己的电子邮件模板（提示：请查看以 janvince.smallcontactform:: 开头的默认模板）。

请记住您的电子邮件模板 CODE 并将其放入 设置 > 小型插件 > 联系表单 > 邮件选项卡 中的小型联系表单电子邮件设置中。每种语言可以有特定的模板。

电子邮件模板内部可用 {{fields}} 和 {{fieldsDetails}} 数组。

您还可以使用 {{url}} 变量来获取原始请求 URL。

如果您的自定义表单字段名称为“email”，您可以在模板中使用 {{fields.email}}。

您可以使用来迭代上传的文件

{% for item in uploads %}
    <a href="{{ item.getPath }}">Uploaded file</a>
{% endfor %}

您可以使用例如 {{ messageObject.id }} 访问模型数据。

GOOGLE ANALYTICS

如果您想使用这些设置，请确保在您的网站上包含 Google Analytics 脚本。您可以使用 Rainlab Google Analytics 插件。

事件

您可以允许在表单成功发送时将事件发送到您的 GA 账户。

有可翻译的字段用于类别、操作和标签。

所有事件设置都可以在组件属性中覆盖，因此如果您使用多个表单，您可以针对每个表单自定义事件。

消息列表

所有从联系表单发送的数据都保存在后端消息列表中。

如果电子邮件、名称和消息字段在 设置 > 小型插件 > 联系表单 > 列映射选项卡 中分配，则它们将分别保存并显示在不同的列中。

您可以通过单击记录来查看所有表单数据。消息将被标记为已读。

仪表板报告小部件

在 OctoberCMS 仪表板上可用报告小部件。

消息统计

显示基本消息统计信息。

新消息

显示新消息的数量。如果有任何消息，颜色将变为绿色。

您可以简单地单击小部件来打开消息列表。

覆盖表单设置

您可以在组件下拉菜单（在页面或布局上）或通过在组件调用中传递它们来覆盖一些表单设置。

表单设置

此外，还有一个别名列，包含使用的表单的别名，并保存在消息日志中（默认情况下，此字段在消息表中不可见）。

[contactForm myForm]
form_description = 'Form used in home page'
disable_fields = 'name|message'
send_btn_label = 'Go'
form_success_msg = 'Ok, sent :)'
form_error_msg = 'Houston, we have a problem'

您可以在 Twig 组件标签中覆盖表单属性，例如

{% component 'myForm' form_description = 'My other description' send_btn_label = 'Stay in touch' %}

这甚至可以更复杂

{% set myVar = 12345 %}
{% component 'myForm' form_description = ('Current value: ' ~ myVar) %}

在电子邮件模板中，您可以这样访问一些变量

Form alias: {{fields.form_alias}}
Form description: {{fields.form_description}}

当您在 {% component form_description = 'My description' %} 中覆盖表单描述时，描述将作为 隐藏字段 添加到表单中。不要使用此功能来存储私人数据，因为这在页面 HTML 代码中很容易看到！

覆盖通知电子邮件选项

您可以设置不同的电子邮件地址，以便将发送表单的通知发送到那里，并且还可以更改通知模板。

模板必须存在于“设置”>“邮件”>“邮件配置”中.

如果您向 notification_template 属性添加了区域字符串（如 notification_template_en），则该字符串具有优先级，如果 App::getLocale() 返回 en，则将使用该字符串。

[contactForm salesForm]
disable_notifications = true
notification_address_to = 'sales@domain.com'
notification_address_from = 'contactform@domain.com'
notification_template = 'notification-sales'
notification_template_en = 'notification-sales-en'
notification_template_cs = 'notification-sales-cs'
notification_subject = 'Notification sent by form {{ fields.form_alias }} on {{ "now"|date }}'

notification_template 中的区域字符串不能在 Twig 中使用！

覆盖自动回复电子邮件选项

您可以设置不同的电子邮件地址和名称用于自动回复消息，并且还可以使用不同的自动回复模板。

模板必须存在于“设置”>“邮件”>“邮件配置”中.

如果您向 autoreply_template 或 autoreply_address_from_name 属性添加了区域字符串（如 autoreply_template_en 或 autoreply_address_from_name_en），则该字符串具有优先级，如果 App::getLocale() 返回 en，则将使用该字符串。

[contactForm orderForm]
autoreply_address_from = 'order@domain.com'
autoreply_address_from_name = 'Orders'
autoreply_address_from_name_en = 'Orders'
autoreply_address_from_name_cs = 'Objednávky'
autoreply_template = 'autoreply-order'
autoreply_template_en = 'autoreply-order-en'
autoreply_template_cs = 'autoreply-order-cs'
autoreply_subject = 'Autoreply sent by form {{ fields.form_alias }} on {{ "now"|date }}'

您知道您可以在电子邮件模板的主题中使用表单变量吗？在“设置”>“邮件模板”中创建新的模板，并将主题字段设置为例如： My form {{ fields.form_alias }}。

禁用某些表单字段

您可以通过传递它们的名称到 disable_fields 组件属性来禁用一些定义的表单字段。

可以使用竖线 | 分隔多个字段。

[contactForm]
disable_fields = 'phone|name|confirmation'

或者您可以选择禁用某些功能

[contactForm]
disable_notifications = true
disable_autoreply = true

如何做

对抗垃圾邮件

禁止在（消息）字段中发送 URL。

使用自定义规则
添加您的验证错误文本
使用验证规则： custom_not_regex
使用验证： /(http|https|ftp|ftps)\:\/\/?/

添加下拉字段中的空选项

您可以通过添加空 ID 和一些值轻松添加空选项。

验证下拉字段

如果您想验证下拉选项，则可以使用具有 ID 列表作为验证模式的自定义验证规则 in。

我要感谢
OctoberCMS 团队成员和支持者为这个伟大的系统。
Andrew Measham 为他的照片。
Font Awesome 为其漂亮的图标。

由 Jan Vince 创建，来自捷克共和国的自由职业网页设计师。

janvince / smallcontactform

维护者

详细信息