README

PerForm简化Craft开发者的表单处理。处理、测试、存储、发送电子邮件通知、配置客户端验证、包含强大的垃圾邮件保护，等等。

要求

此插件需要Craft CMS 3.0.18或更高版本。

安装

要安装PerForm插件，请按照以下说明操作

打开您的终端并转到您的Craft项目
```
 cd /path/to/project
```
然后告诉Composer加载插件
```
 composer require perfectus/perform
```
在控制面板中，转到“设置→插件”并点击PerForm的“安装”按钮。

PerForm在Craft 3.x上运行。

PerForm使用说明

问题

请将您发现的问题报告给PerForm问题页面。

PerForm概述

PerForm是为了Craft CMS网络开发者而构建的，考虑到最大的灵活性。目标是让您以任何方式构建Web表单前端，同时遵循一些简单的约定。在将Web表单包含到您的Twig模板后，该插件将协助您完成以下任务

使用Parsley进行客户端表单验证
使用Google隐形ReCaptcha进行垃圾邮件保护
在控制面板中保存表单提交以备将来参考
通过电子邮件（内置使用Mailtrap的测试）发送表单提交内容

使用PerForm

使用PerForm非常简单。以下是一些使PerForm正常工作的基本要求。

PerForm formTag — 确保表单将提交并由PerForm处理
按照PerForm 表单字段约定构建的表单 — 确保PerForm知道哪些字段需要处理
PerForm 表单设置 — 让PerForm知道如何处理表单提交
PerForm 插件设置 — 配置附加选项并将PerForm与外部服务连接

请继续阅读以下内容，了解更多关于每个概念的信息。我们将构建一个简单的表单，收集名字、姓氏和电子邮件，以展示如何构建、设置和配置由PerForm处理的表单。

PerForm `formTag`

formTag变量生成打开的<form>标签。没有它，表单将不会处理。

{{ craft.perForm.formTag({
  'entryId': entry.id
}) }}

formTag有一个必需的配置选项entryId，指定哪个条目包含将以下包含的表单的表单设置。这将生成类似以下html代码。

<noscript>
    <style type="text/css">
        #perform-submission {
            display: none;
        }
    </style>
    <p class="perform--warning-panel">
        <strong>You don't have JavaScript enabled.</strong><br>
        To continue, please <a href="http://enable-javascript.com/" target="_blank">
        enable JavaScript in your browser</a>.
    </p>
</noscript>

<form role="form" id="perform-submission" method="post" action="" accept-charset="UTF-8">
    <input type="hidden" name="action" value="perform/public/submit-form">
    <input type="hidden" name="entry_id" value="2">
    <input type="hidden" name="CRAFT_CSRF_TOKEN" value="yWz6...">

注意，如果您提供错误的entryId或没有正确设置与提供的entryId关联的表单设置，您将在屏幕上看到类似以下的消息。

PerForm表单字段约定

PerForm不关心您如何决定构建表单，这完全取决于您。在构建表单的过程中，您需要记住一个重要的约定。您需要让PerForm知道哪些字段标签和值需要处理和存储。

<label for="fields_firstName">First Name</label>
<input type="hidden" name="fields[firstName][label]" value="First Name">
<input type="text" id="fields_firstName" name="fields[firstName][value]">

在上面的例子中，PerForm将处理并存储First Name文本框的字段。您需要让PerForm知道字段标签和字段值

标签：使用隐藏字段<input type="hidden" name="fields[firstName][label]" value="First Name">
值：配置输入的name与标签的隐藏字段相对应name="fields[firstName][value]"

注意，在上面的例子中，您可以替换firstName为您想要的任何内容。实际上，您需要为每个要PerForm处理的字段提供一个唯一的'处理程序'。当然，您不需要手动构建字段（您也不应该这样做）。有很多方法可以做到这一点，例如，您可以使用Twig宏、Twig包含或两者的组合。

PerForm表单设置

PerForm附带了一个表单设置字段类型，允许您将字段添加到条目中，该条目将包含表单。您需要创建一个字段并将其添加到条目布局中（实际上，这可以是任何条目，而不仅仅是包含生成表单的模板的条目）。您将通过formTag变量指定包含表单设置的条目。

一旦创建字段并将其与条目布局关联起来，您就可以为特定表单提供适当的设置。

表单标题 — 供用户友好的标签，用于在控制面板的列表页面中识别来自此表单的表单提交。
表单处理程序 — 如果您决定为不同的表单提供不同的模板，并且想要设置自己的电子邮件内容模板，此设置非常有用。
表单主题 — 将在控制面板的表单提交列表中显示，并用于电子邮件通知的电子邮件主题。主题将由Twig处理，因此您可以使用以下格式包含表单中出现的任何字段的值{{ fieldHandle.value }}。
通知收件人 — 在表单提交并处理之后，应接收表单提交通知的一个或多个电子邮件地址。
通知回复到 — 表单提交通知电子邮件使用在控制面板→设置→电子邮件中配置的系统电子邮件地址发送，因此当收件人在他们的电子邮件客户端中点击'回复'按钮时，电子邮件回复不会发送给实际提交表单的人。如果您通过表单收集实际提交者的电子邮件地址，您可以提供该人的电子邮件地址，在这种情况下，您只需引用表单字段的值。例如，如果表单输入处理程序恰好是'email'，则{{ email.value }}。
测试模式启用 — 当此设置打开时，表单提交将自动设置为测试状态，并根据测试电子邮件投递设置进行投递，而不是在'通知收件人'中指定的电子邮件地址。

PerForm插件设置

测试电子邮件投递设置 — 使用Mailtrap电子邮件测试服务来测试PerForm电子邮件通知。在Mailtrap上注册一个账户，并在提供的字段中输入收件箱用户名和密码。
客户端验证 — PerForm目前不支持服务器端表单验证，但您可以在表单提交之前轻松验证表单字段。当您勾选此设置时，PerForm将自动在每个表单中包含'parsley.js'。您需要配置您的表单输入以与Parsley一起使用。
Google隐形reCAPTCHA配置 — 当您启用此设置时，Google隐形reCAPTCHA将自动适用于您网站中所有由PerForm驱动的表单。您可以了解更多关于其工作方式，但您需要做的只是为您的网站和PerForm创建reCAPTCHA API密钥，然后PerForm将处理其他所有事情。
自定义电子邮件模板 — 提供您自己的模板以生成电子邮件通知

示例：简单联系表单

本示例将向您介绍如何将各种概念结合在一起，并最终允许您构建更大、更复杂的表单。

以下模板代码

{% extends "_layouts/base" %}
{% block pageContent %}
  <h1>Contact Form</h1>

  {% if craft.app.request.getParam('success') == '✓' %}
    <p>Thank you for submitting your information</p>
  {% else %}
    {# Generate the PerForm form tag #}
    {{ craft.perForm.formTag({
      'entryId': entry.id
    }) }}

      {# First Name field #}
      <label for="fields_firstName">First Name</label><br>
      <input type="hidden" name="fields[firstName][label]" value="First Name">
      <input type="text" id="fields_firstName" name="fields[firstName][value]">

      <br><br>

      {# Last Name field #}
      <label for="fields_lastName">Last Name</label><br>
      <input type="hidden" name="fields[lastName][label]" value="Last Name">
      <input type="text" id="fields_lastName" name="fields[lastName][value]">

      <br><br>

      {# Email field #}
      <label for="fields_email">Email</label><br>
      <input type="hidden" name="fields[email][label]" value="Email">
      <input type="email" id="fields_email" name="fields[email][value]">

      <br><br>

      <button type="submit">Submit</button>
    </form>
  {% endif %}
{% endblock %}

与以下表单设置

并且，没有任何样式，将生成一个非常简单的表单。

默认情况下，PerForm将重定向浏览器到原始url，并设置一个带有submissionId键的闪存消息（有关重定向和闪存消息的更多信息，请参阅详情），您可以对其进行测试并显示“感谢”消息给访客。因此，在填写和提交表单后，访客将在浏览器中看到以下内容

表单提交将由PerForm处理，并保存在控制面板中

在此处，具有适当权限的用户可以查看表单提交详细信息

并且，通知收件人收到以下电子邮件通知

提交后重定向

默认情况下，PerForm将自动重新加载当前页面。

要覆盖此默认行为，请在PerForm formTag之后包含redirectInput函数并指定您的重定向目的地。

{# Generate the PerForm form tag #}
{{ craft.perForm.formTag({
'entryId': entry.id
}) }}

{{ redirectInput('contact-form/thank-you') }}

有时在“感谢”页面上检索和显示表单提交中包含的信息很方便。您可以通过设置查询字符串参数（尽管，有一种更好的方法）来实现这一点。以下变量可以用于您设置的URL/路径中

submissionId — 表单提交的ID。您可以使用它使用getSubmissionById插件变量检索整个提交内容，然而，出于安全原因，不建议将ID作为查询字符串参数暴露。PerForm中内置了一种更好的方法来完成此操作。
dateCreated — 提交创建的日期/时间
dateUpdated — 提交最后更新的日期/时间（在这种情况下与dateCreated相同）
statusType — 新的、已读、测试 （请注意，由于提交刚刚提交，它将被设置为“新”或“测试”状态）
formHandle — 在表单设置中指定
formTitle — 在表单设置中指定
subject — 使用表单设置中指定的表单主题模板生成的主题
replyTo — 根据表单设置中指定的通知回复到模板提取的电子邮件地址
recipients — 在表单设置中的通知收件人设置中指定的一个或多个电子邮件地址。值作为数组返回。
fields — 包含在表单中并提交给PerForm的字段。值作为数组返回，您可以使用字段句柄来检索提交的值和标签。

例如，如果您的表单看起来像这样

{{ redirectInput('contact-form/thank-you?replyTo={replyTo}&firstName={fields.firstName.value}') }}

{# First Name field #}
<input type="text" id="fields_firstName" name="fields[firstName][value]">

{# Last Name field #}
<input type="text" id="fields_lastName" name="fields[lastName][value]">

{# Email field #}
<input type="text" id="fields_email" name="fields[email][value]">

在您的 contact-form/thank-you.html 模板中，您可以使用 craft.app.request.getQueryParam() 访问参数

<p>
	{{ craft.app.request.getParam('firstName') }}, thank you for submitting your information.
	{% if craft.app.request.getParam('replyTo') is not empty %}
		<br>
		We will use the {{ craft.app.request.getParam('replyTo') }} email address to send you a reply.
	{% endif %}
</p>

使用闪存消息

当表单提交成功处理时，PerForm 会设置一个带有 submissionId 键和提交 ID 的闪存消息，以指示表单提交成功。除了检查表单是否成功处理之外，这还使您能够使用 getSubmissionById 插件变量检索整个提交内容。与将 submissionId 作为查询参数发送相比，这种方法有两个优点。首先，实际的提交 ID 不能轻易地从响应中提取，其次，当页面刷新时它就不再可用（这使得当重定向到包含表单本身的同一模板时，这种方法非常有效）。

使用上面的示例

{{ redirectInput('contact-form/thank-you') }}

{# First Name field #}
<input type="text" id="fields_firstName" name="fields[firstName][value]">

{# Last Name field #}
<input type="text" id="fields_lastName" name="fields[lastName][value]">

{# Email field #}
<input type="text" id="fields_email" name="fields[email][value]">

在您的 contact-form/thank-you.html 模板中，您可以从会话闪存中检索 submissionId 并使用它来使用 getSubmissionById 插件变量（这里是所有提交变量的列表）检索整个提交内容。

{% if craft.app.session.hasFlash('submissionId') %}
	{% set submissionId = craft.app.session.getFlash('submissionId') %}
	{% set submission = craft.perForm.getSubmissionById(submissionId) %}
    <p>
		{{ submission.fields.firstName.value }}, thank you for submitting your information.
        {% if submission.replyTo is not empty %}
            <br>
            We will use the {{ submission.replyTo }} email address to send you a reply.
        {% endif %}
	</p>
{% elseif craft.app.session.hasFlash('error') %}
    <p class="message error">{{ craft.app.session.getFlash('error') }}</p>
{% endif %}

如上例所示，如果未设置带有 submissionId 键的闪存，PerForm 就无法处理表单提交，并且很可能设置了 error 闪存消息。

示例：功能齐全的复杂表单

内容即将推出...

PerForm 小部件

您可以通过启用 PerForm 仪表板小部件 来跟踪各种表单提交。

PerForm 工具

方便的 PerForm 工具允许您轻松地从控制面板中删除所有 测试提交。

控制面板权限

如果您使用的是 Craft CMS "Pro" 版本，PerForm 提供了权限，可以根据用户组授予用户访问权限。这些权限在 设置 → 用户 → 用户组 中设置。

授予 PerForm 通用访问权限

有了 PerForm 的 通用访问权限，用户可以

列出、查看、删除和更改所有表单提交的状态
添加并使用 PerForm 仪表板小部件

授予 PerForm 工具访问权限

有了 PerForm 的 工具访问权限，用户可以

访问 Craft CMS 工具部分下的 PerForm 页面，并轻松删除所有测试表单提交

PerForm 路线图

一些待办事项和潜在功能的想法

处理通过 AJAX 提交的表单
在 测试模式 中添加表单提交字段的预览
在表单提交后添加发送收据或确认的选项
提交您的新功能请求，如果您需要 PerForm 执行对其他 Craft 开发者有用的特定操作...

由 Perfectus Digital Solutions 提供

perfectus / perform

维护者

详情

README

要求

安装

PerForm使用说明

问题

PerForm概述

使用PerForm

PerForm `formTag`

PerForm表单字段约定

PerForm表单设置

PerForm插件设置

示例：简单联系表单

提交后重定向

使用闪存消息

示例：功能齐全的复杂表单

PerForm 小部件

PerForm 工具

控制面板权限

授予 PerForm 通用访问权限

授予 PerForm 工具访问权限

PerForm 路线图

perfectus / perform

维护者

详情

README

要求

安装

PerForm使用说明

问题

PerForm概述

使用PerForm

PerForm formTag

PerForm表单字段约定

PerForm表单设置

PerForm插件设置

示例：简单联系表单

提交后重定向

使用闪存消息

示例：功能齐全的复杂表单

PerForm 小部件

PerForm 工具

控制面板权限

授予 PerForm 通用访问权限

授予 PerForm 工具访问权限

PerForm 路线图

PerForm `formTag`