README

此插件允许您将电子邮件联系方式表单添加到您的网站上。

安装

要安装联系方式插件，请按照以下步骤操作

1. 将contactform/文件夹上传到您的craft/plugins/文件夹。
2. 从Craft控制面板转到设置 > 插件并启用联系方式插件。
3. 单击“联系方式”进入插件的设置页面，并按需配置插件。

用法

您的联系方式表单模板可以看起来像这样

{% macro errorList(errors) %}
    {% if errors %}
        <ul class="errors">
            {% for error in errors %}
                <li>{{ error }}</li>
            {% endfor %}
        </ul>
    {% endif %}
{% endmacro %}

{% from _self import errorList %}

<form method="post" action="" accept-charset="UTF-8">
    {{ getCsrfInput() }}
    <input type="hidden" name="action" value="contactForm/sendMessage">
    <input type="hidden" name="redirect" value="contact/thanks">

    <h3><label for="fromName">Your Name</label></h3>
    <input id="fromName" type="text" name="fromName" value="{% if message is defined %}{{ message.fromName }}{% endif %}">
    {{ message is defined and message ? errorList(message.getErrors('fromName')) }}

    <h3><label for="fromEmail">Your Email</label></h3>
    <input id="fromEmail" type="email" name="fromEmail" value="{% if message is defined %}{{ message.fromEmail }}{% endif %}">
    {{ message is defined and message ? errorList(message.getErrors('fromEmail')) }}

    <h3><label for="subject">Subject</label></h3>
    <input id="subject" type="text" name="subject" value="{% if message is defined %}{{ message.subject }}{% endif %}">
    {{ message is defined and message ? errorList(message.getErrors('subject')) }}

    <h3><label for="message">Message</label></h3>
    <textarea rows="10" cols="40" id="message" name="message">{% if message is defined %}{{ message.message }}{% endif %}</textarea>
    {{ message is defined and message ? errorList(message.getErrors('message')) }}

    {{ craft.contactform.getReCaptchaInput()|raw }}
    {{ message is defined and message ? errorList(message.getErrors('reCaptchaResponse')) }}

    <input type="submit" value="Send">
</form>

唯一必需的字段是“fromEmail”和“message”。其他所有内容都是可选的。

提交后重定向

如果您有一个名为“redirect”的隐藏输入，用户在成功发送电子邮件后将被重定向到它。以下变量可以用于您设置的URL/path中

• {fromName}
• {fromEmail}
• {subject}

例如，如果您想重定向到“contact/thanks”页面并传递发件人的名字，您可以设置输入如下

<input type="hidden" name="redirect" value="contact/thanks?from={fromName}">

在您的contact/thanks.html模板中，您可以使用 craft.request.getQuery() 访问该“from”参数

<p>Thanks for sending that in, {{ craft.request.getQuery('from') }}!</p>

注意，如果您不包括“redirect”输入，当前页面将被重新加载。

添加额外字段

您可以通过将“message”字段拆分成多个字段来向您的表单添加额外字段，使用数组语法为输入名称

<h3><label for="message">Message</label></h3>
<textarea rows="10" cols="40" id="message" name="message[body]">{% if message is defined %}{{ message.message }}{% endif %}</textarea>

<h3><label for="phone">Your phone number</label></h3>
<input id="phone" type="text" name="message[Phone]" value="">

<h3>What services are you interested in?</h3>
<label><input type="checkbox" name="message[Services][]" value="Design"> Design</label>
<label><input type="checkbox" name="message[Services][]" value="Development"> Development</label>
<label><input type="checkbox" name="message[Services][]" value="Strategy"> Strategy</label>
<label><input type="checkbox" name="message[Services][]" value="Marketing"> Marketing</label>

如果您有一个主要的“消息”字段，您应该将其命名为 message[body]，就像在示例中那样。

使用以上表单发送的电子邮件可能会产生以下消息

Phone: (555) 123-4567

Services: Design, Development

Hey guys, I really loved this simple contact form (I'm so tired of agencies
asking for everything but my social security number up front), so I trust
you guys know a thing or two about usability.

I run a small coffee shop and we want to start attracting more freelancer-
types to spend their days working from our shop (and sipping fine coffee!).
A clean new website with lots of social media integration would probably
help us out quite a bit there. Can you help us with that?

Hope to hear from you soon.

Cathy Chino

覆盖插件设置

如果您在craft/config文件夹中创建了一个名为contactform.php的配置文件，您可以在控制面板中覆盖插件设置。由于该配置文件完全支持多环境，这是一种在不同的环境中拥有不同设置的便捷方式。

以下是该配置文件可能的样子，以及您可以覆盖的所有可能值的列表。

    <?php

    return array(
        'toEmail'             => 'bond@007.com',
        'prependSubject'      => '',
        'prependSender'       => '',
        'allowAttachments'    => false,
        'honeypotField'       => 'dieSpammers',
        'successFlashMessage' => 'Congrats, yo!'
    );

动态添加电子邮件接收者（需要Craft 2.5+）

您可以通过在模板中添加名为“toEmail”的隐藏输入字段来程序化地添加电子邮件接收者

<input type="hidden" name="toEmail" value="{{ 'me@example.com'|hash }}">

如果您想添加多个接收者，您可以提供一个以逗号分隔的电子邮件列表

<input type="hidden" name="toEmail" value="{{ 'me@example.com,me2@example.com'|hash }}">

然后从您的craft/config/contactform.php配置文件中，您需要添加一些逻辑

    <?php
    namespace Craft;

    $toEmail = craft()->request->getPost('toEmail');
    $toEmail = craft()->security->validateData($toEmail);

    return array(
        'toEmail' => ($toEmail ?: null),
        ...
    );

在这个例子中，如果$toEmail不存在或验证失败（被篡改），插件将回退到插件设置中定义的“toEmail”，因此您也必须定义它。

“蜜罐”字段

蜜罐验证码是一种简单的反垃圾邮件技术，它大大降低了垃圾邮件软件的效率，而无需期望您的访客解码各种扭曲的字母形式。

简要来说，它的工作原理如下

1. 您在表单中添加一个正常的文本字段（我们的“蜜罐”），并使用CSS隐藏它。
2. 普通（人类）访客不会填写这个不可见的文本字段，但那些疯狂的垃圾邮件软件会。
3. 联系人表单插件会检查“诱饵”表单字段是否包含文本。如果包含，它会假定表单是由“恶人”提交的，并将其忽略（但假装一切正常，这样恶人就不会察觉）。

“诱饵”实现示例

在命名表单字段时，最好避免使用像“dieEvilSpammers”这样的名字，而选择一些更具诱惑力的名字。例如

<input id="preferredKitten" name="preferredKitten" type="text">

在这种情况下，您可以使用以下CSS隐藏您的表单字段

input#preferredKitten { display: none; }

文件附件

如果您想使您的联系表单接受文件附件，请按照以下步骤操作

1. 进入CP中的设置 > 插件 > 联系表单，并确保插件设置为允许附件。
2. 确保您的HTML <form> 标签包含 enctype="multipart/form-data"。
3. 在您的表单中添加一个 <input type="file" name="attachment">。
4. 如果您想允许多个文件附件，请使用多个 <input type="file" name="attachment[]"> 输入。

Ajax表单提交

如果您想通过Ajax发送联系人表单提交，只需向您的网站发送带有所有通常要发送数据的POST请求即可

$('#my-form').submit(function(ev) {
    // Prevent the form from actually submitting
    ev.preventDefault();

    // Get the post data
    var data = $(this).serialize();

    // Send it to the server
    $.post('/', data, function(response) {
        if (response.success) {
            $('#thanks').fadeIn();
        } else {
            // response.error will be an object containing any validation errors that occurred, indexed by field name
            // e.g. response.error.fromName => ['From Name is required']
            alert('An error occurred. Please try again.');
        }
    });
});

contactForm.beforeSend事件

其他插件可以在发送电子邮件之前通知联系表单插件，并且甚至有机会阻止电子邮件发送。

class SomePlugin extends BasePlugin
{
    // ...

    public function init()
    {
        craft()->on('contactForm.beforeSend', function(ContactFormEvent $event) {
            $message = $event->params['message'];

            // ...

            if ($isVulgar)
            {
                // Setting $isValid to false will cause a validation error
                // and prevent the email from being sent

                $message->addError('message', 'Do you kiss your mother with those lips?');
                $event->isValid = false;
            }

            if ($isSpam)
            {
                // Setting $fakeIt to true will make things look as if the email was sent,
                // but really it wasn't

                $event->fakeIt = true;
            }
        });
    }
}

contactForm.beforeMessageCompile事件

其他插件可以监听此事件来更改电子邮件的纯文本正文以及HTML正文。

class SomePlugin extends BasePlugin
{
    // ...

    public function init()
    {
        craft()->on('contactForm.beforeMessageCompile', function(ContactFormMessageEvent $event) {
            $message = $event->params['message'];
            $htmlMessage = $event->params['htmlMessage'];
            $messageFields = $event->params['messageFields'];

            // ...

            $event->params['message'] = 'Make email great again! - '.$message;
            $event->params['htmlMessage'] = '<p>Make email great again! - '.$message.'</p>';
        });
    }
}

变更日志

1.8.1

• 修复了一个问题，该问题导致电子邮件的HTML正文被转义，并在电子邮件中显示HTML实体。

1.8.0

• 添加了通过contactForm.beforeMessageCompile事件修改电子邮件的纯文本和HTML正文的能力。
• 修复了一个问题，该问题导致在电子邮件正文或主题中输入的Twig代码被解析。

1.7.0

• 添加了在验证错误发生时通过message.messageFields访问单个消息字段值的能力。例如，现在可以通过message.messageFields['Phone']访问输入message[Phone]的值。
• 在生成的电子邮件正文中，自定义消息字段值之间现在只有单行换行符，而不是两行。

1.6.0

• 添加了将多个文件附加到联系电子邮件的能力。
• 添加了通过“successFlashMessage”设置更改闪存成功消息的能力。
• 添加了通过craft/config/contactform.php配置设置覆盖插件设置的能力。
• “prependSender”和“prependSubject”设置现在可以是空字符串。
• 修复了一个问题，即“allowAttachments”配置设置没有被尊重。

1.5.0

• 添加了对Craft 2.5的一些功能的支持。

1.4.0

• 添加了对在‘redirect’ URL中传递{fromName}、{fromEmail}和{subject}的支持。

1.3.0

• 添加了对多个电子邮件地址的支持。
• 添加了ContactFormService。
• 添加了contactForm.beforeSend事件，允许第三方插件添加额外的验证。

1.2.0

• 添加了对诱饵验证码的支持。

1.1.0

• 添加了提交附件的能力。
• 添加了通过Ajax提交表单的能力。
• 添加了提交复选框列表的能力，这些列表在电子邮件中以逗号分隔的列表形式编译。

1.0.0

• 初始发布