README

内容

简介
安装和升级
从 zem_contact_reborn 迁移
用法
标签
高级示例
样式
插件 API 和回调事件
常见问题解答
作者/致谢

简介

Textpattern CMS 表单邮件插件。 <txp:com_connect /> 生成一个灵活、可定制的电子邮件联系表单。它旨在用作商业和私人网站的调查表单，并包含一些功能，有助于减少此类表单的常见问题（无效的电子邮件地址、信息缺失）。

请在此GitHub项目的“问题”页面报告此插件的错误和问题。

功能

可以指定任意 HTML5 文本字段，包括用于验证的最小/最大/必需设置。
电子邮件地址验证，包括对有效 MX 记录的检查（仅限 Unix）。
安全转义输入数据。
UTF-8 安全。
可访问的表单布局，包括 <label>、<legend> 和 <fieldset> 标签。
各种类和 ID，以便轻松美化表单的所有部分。
防垃圾邮件 API（由 Tranquillo 的 pap_contact_cleaner 插件使用）和投递 API 以更改或扩展插件的功能。

历史

请参阅 GitHub 上的变更日志。

安装和升级

需要 Textpattern 4.7.0+

从 GitHub 项目页面下载此插件的最新版本，将代码粘贴到 Textpattern 管理员>插件面板，安装并启用插件。访问论坛主题获取更多信息或报告插件的成败。

要卸载，请从插件面板中删除。

或者，可以使用 Composer 安装此插件

$ composer require textpattern/com_connect:*

从 zem_contact_reborn 迁移

如果您是从 zem_contact_reborn（此插件的先前版本）升级，请注意以下差异

标签已从 <txp:zem_contact ... /> 全局重命名为 <txp:com_connect ... /> - 请相应地调整您的代码。
类 zemConnectForm、zemError、zemRequired、zemThanks、zemText、zemEmail、zemTextarea、zemSubmit、zemSelect、zemOption、zemCheckbox 和 zemRadio 已分别重命名为 comConnectForm、comError、comRequired、comThanks、comText、comEmail、comTextarea、comSubmit、comSelect、comOption、comCheckbox 和 comRadio，请相应调整您的代码。
禁用或删除 zem_contact_lang 插件。语言字符串现在作为插件本身的一部分打包。如果您有尚未打包的翻译 Textpack，请提交以包含在内。
基于输入元素 name 的类不再自动应用。仅设置以 com 开头的默认类名。要使用自定义类，请为每个标签使用 class 属性，或使用全局 classes 属性来设置错误和信息消息的名称。
如果您的站点的“Doctype”首选项设置为 html5，则可以在标签中使用 HTML5 属性。否则，它们将被忽略。
首先由浏览器执行必填元素和 min/max 约束的验证，然后是插件。因此，如果您指定某个字段为必填，并且它留空，则浏览器通常会阻止表单提交。为了绕过（大部分）浏览器检查，请在您的 <txp:com_connect /> 标签中指定 browser_validate="0"。

用法

联系表单

以下是最简单的表单示例，它生成一个默认表单，包含“姓名”、“电子邮件”和“消息”字段。电子邮件将发送到 recipient@example.com，用户的提供的电子邮件地址作为 From: 地址。

<txp:com_connect to="recipient@example.com" />

要明确指定字段，可以使用类似以下的方式

<txp:com_connect to="recipient@example.com">
    <txp:com_connect_email />
    <txp:com_connect_text label="Phone" min="7" max="15" />
    <txp:com_connect_textarea label="Your question" />
    <txp:com_connect_submit label="Send" />
</txp:com_connect>

或者，将字段说明放在 Textpattern 表单中，并按如下方式调用它

<txp:com_connect to="recipient@example.com" form="my-contact-form" />

发送文章

在单个文章的上下文中，此插件可以将文章（如果存在摘录，则为摘录）发送到访客指定的电子邮件地址。这需要至少两个标签

com_connect，用于创建一个通过设置 send_article 属性而最初隐藏的表单。
com_connect_send_article，用于创建一个“发送文章”链接，当点击时将揭示上述表单。

<txp:com_connect send_article="1" />
<txp:com_connect_send_article />

默认情况下，表单包含您的姓名和电子邮件地址、收件人的电子邮件地址和一条个人消息的字段，但与联系表单类似，您可以创建自己的表单布局。以下是一些您需要了解的事项

在 com_connect 标签中将 send_article 属性设置为 1。
使用带有 send_article 属性设置为 1 的 com_connect_email 标签。此字段将用作收件人电子邮件地址。

<txp:com_connect to="you@example.com" send_article="1">
    <txp:com_connect_email label="Recipient Email" send_article="1" />
    <txp:com_connect_email label="Your Email" />
    <txp:com_connect_submit label="Send Article" />
</txp:com_connect>

<txp:com_connect_send_article />

；accesskey="character"
：设置焦点在字段上的快捷键。
；autofocus="boolean"
：在页面加载时自动将光标定位在此字段上。只能有一个字段具有此属性。
；dir="value"
：文本方向（ltr、rtl 或 auto）。
；disabled="boolean"
：输入控件是否接受用户输入。如果设置，则元素不会随表单一起提交，也不会受到任何 checkValidity() JavaScript 调用的约束。
；hidden="boolean"
：输入控件的可见性。
；id="id"
：控件的控制 HTML 标识符。
; lang="value"
: 管理字段的 ISO 639 语言简码（例如 en-gb，de-de）。
; list="id"
: 与 <datalist> 标签结合使用，以指定一组选项。id 是要使用的 datalist 的引用。
; readonly="boolean"
: 控件不接受用户输入，但在表单提交时将被处理，并可进行验证。
; spellcheck="value"
: 字段是否受拼写检查的影响（true = 是，default = 浏览器决定，或 false = 否）。
; style="style rules"
: 应用到输入控件的内联 CSS 样式规则。
; tabindex="number"
: 使用制表键在元素之间跳转的顺序。
; title="value"
: 通常用于悬停提示，描述输入控件在您的应用程序中的用途。
; translate="boolean"
: 是否将属性内容提交给语言翻译。

com_connect 标签

<txp:com_connect />

可以作为单个（自闭合）或容器标签使用。将此放置在您希望输入表单出现的位置。如果有状态和错误消息，将显示在表单之前。

属性

; body_form="form name"
: 使用指定的表单作为消息正文文本。
; class="space-separated values"
: 设置标签的 CSS 类名。默认：comConnectForm。要从元素中完全删除 class 属性，请使用 class=""。
; classes="comma-separated key:value pairs"
: 设置错误/信息条件的 CSS 类。指定为冒号分隔的值对，例如 classes="required: req_field, element: warn_field"。最多有四个可自定义。
: element: 为任何原因验证失败的每个表单字段设置。默认：errorElement。
: wrapper: 包围表单上显示的错误列表的类。默认：comError。
: required: 当必填元素未完成时分配的类。默认：comRequired。
: thanks: 应用到围绕 thanks_form 的包装器的类。默认：comThanks。
; copysender="boolean"
: 是否向发送者的地址发送电子邮件的副本。可用值：1（是）或 0（否）。默认是 0。
; expire="number"
: 表单将在多少秒后过期，因此需要刷新页面才能发送。默认是 600。
; form="form name"
: 使用指定的表单，包含联系表单字段的布局。
; from="email address"
: 发送电子邮件时在“发件人：”字段中使用的电子邮件地址。默认为发送者的电子邮件地址。如果指定，则将发送者的电子邮件地址放在“回复：”字段中。
; from_form="form name"
: 使用指定的表单（覆盖 from 属性）。
; label="text"
: 联系表单的标签。如果设置为空字符串，则将抑制字段集和图例标签的显示。默认是 Contact。
; lang="lang-code"
: 覆盖通常从当前管理员端语言中使用的语言字符串。例如，lang="fr-fr" 将加载法语字符串。必须已存在所选语言的 Textpack。
; browser_validate="boolean"
: 如果您希望停止浏览器验证表单字段值和输入元素的“required”状态，请设置为 0。那么插件本身将负责验证，并在提交后指示错误条件。默认是 1。
; redirect="URL"
: 转向指定的 URL（覆盖 thanks 和 thanks_form 属性）。URL 必须相对于 Textpattern 网站地址 URL。示例：redirect="monkey" 将转向 http://example.com/monkey。
; replyto=boolean|email address
: 控制消息回复的电子邮件地址。选项
: true（默认）：如果指定了 from 地址，则使用表单本身的电子邮件地址（<txp:com_connect_email> 标签的值）。否则为空。
: false：始终使用 from 电子邮件地址作为回复地址。请注意，如果省略了 from，则电子邮件可能来自无人，并且可能被接收服务器拒绝。
: email address：如果它是有效的地址，则使用指定的电子邮件地址作为回复地址。
; required="boolean"
: 是否在提交表单之前要求完成此联系表单中的所有标签。可以通过在相关标签中使用 required 属性逐字段覆盖。有效值：1（是）或 0（否）。默认是 1。
; send_article="boolean"
: 是否使用此表单发送文章。有效值：1（是）或 0（否）。默认是 0。
; show_error="boolean"
: 是否显示错误和状态消息。有效值：1（是）或 0（否）。默认是 1。
; show_input="boolean"
: 是否显示表单 <input> 字段。有效值：1（是）或 0（否）。默认是 1。
; subject="subject text"
: 发送电子邮件时使用的主题。默认是网站名称。
; subject_form="form name"
: 使用指定的表单（覆盖 subject 属性）。
; thanks="text"
: 成功提交消息后显示的消息。默认是 谢谢，您的消息已发送。
; thanks_form="form name"
: 使用指定的表单（覆盖 thanks 属性）。
; to="email address" required
: 收件人电子邮件地址。可以指定多个收件人，用逗号分隔。
; to_form="form name"
: 使用指定的表单（覆盖 to 属性）。

示例

示例 1：内置联系表单

当作为单个标签使用时，将生成一个带有“姓名”、“电子邮件”和“消息”字段的默认表单。电子邮件将发送到 recipient@example.com，用户提供的电子邮件地址作为 From: 地址。

<txp:com_connect to="recipient@example.com" />

示例 2：构建自定义表单容器

当作为容器标签使用时，允许更多的灵活性，例如

<txp:com_connect to="recipient@example.com">
    <txp:com_connect_email />
    <txp:com_connect_text type="tel" label="Phone" min="7" max="15" />
    <txp:com_connect_textarea label="Your question" />
    <txp:com_connect_submit label="Send" />
</txp:com_connect>

示例 3：自定义消息格式化

使用 body_form 属性构建发送给收件人的自定义内容

<txp:com_connect to="recipient@example.com" body_form="message-formatting" />

名为 message-formatting 的 body_form 表单模板如下

============
Email received.

<txp:com_connect_if name="email"><txp:com_connect_label name="email" />: <txp:com_connect_value name="email" /><txp:else />Mr. Nobody</txp:com_connect_if> wrote:

<txp:com_connect_if name="message"><txp:com_connect_value name="message" /><txp:else />Nothing much :(</txp:com_connect_if>

============

示例 4：HTML 和纯文本电子邮件内容

使用 body_form 属性在纯文本和 HTML 格式中构建发送给收件人的自定义内容

<txp:com_connect to="recipient@example.com" body_form="message-formatting" />

使用名为 message-formatting 的 body_form 表单模板如下，并注意 <txp:com_connect_mime> 标签，它表示紧跟给定 type 的内容。使用带有 type="end" 的标签表示内容完整。

============
<txp:com_connect_mime type="text" />
Fields submitted:
<txp:com_connect_fields break="">
<txp:com_connect_label />: <txp:com_connect_value />
</txp:com_connect_fields>

<txp:com_connect_mime type="html" />
<table width="600" style="font-family:Arial, Helvetica, sans-serif; font-size:12px;">
<txp:com_connect_fields break="tr">
<td style="padding:10px 0">
   <txp:com_connect_label />
</td>
<td style="padding:10px 0">
   <txp:com_connect_value />
</td>
</txp:com_connect_fields>
</table>

<txp:com_connect_mime type="end" />
============

com_connect_text 标签

<txp:com_connect_text />

创建一个文本 <input> 字段和相应的 <label> 标签。输入值将包含在电子邮件中，在标签之前。

属性

; autocomplete="value"
: 表示控制值的浏览器是否可以自动完成。如果 type 属性的值为 password，则忽略此属性。可能的值是：off（浏览器不自动完成输入）或 on（浏览器可以自动完成值，基于用户在之前使用中输入的值）。默认为未设置。
; break="tag"
: 在 <label> 和 <input> 字段之间插入换行标签。默认为 <br />。使用 break="" 将标签和输入字段放在同一行。
; class="space-separated values"
: 设置标签的 CSS class 名称。默认：comText。要从元素中完全删除 class 属性，请使用 class=""。
; default="value"
: 没有提供输入时的默认值。
; html_form="id"
: 字段所附 <form> 标签的 HTML id。默认与包含的表单相关联。
; inputmode="value"
: 向浏览器提示显示哪个键盘。当 type 属性的值为 text、password 或 url 时，此属性适用。可能的值包括
: verbatim：字母数字内容，非散文内容，如用户名和密码。
: latin：用户的首选语言中的拉丁字母输入，启用了诸如文本预测等辅助功能。用于人机通信，如搜索框。
: latin-name：与拉丁字母相同，但用于人名。
: latin-prose：与拉丁字母相同，但具有更积极的辅助功能。用于人际通信，如电子邮件的即时消息。
: full-width-latin：与拉丁-prose相同，但用于用户的辅助语言。
: kana：使用全角字符的假名或罗马字输入，通常为平假名输入，支持转换为汉字。用于日本文字输入。
: katakana：使用全角字符的片假名输入，支持转换为汉字。用于日本文字输入。
: numeric：数字输入，包括0到9的数字键、用户的首选千位分隔符字符和表示负数的字符。用于数字代码，例如信用卡号码。对于实际数字，首选使用 type="number"。
: tel：电话输入，包括星号和井号键。如果可能，请使用 type="tel"。
: email：电子邮件输入。如果可能，请使用 <txp:com_connect_email />。
: url：URL输入。如果可能，请使用 type="url"。
; label="text"
: 向用户显示的文本标签。默认为 Text。
; label_position="text"
: 标签相对于 <input> 字段的位置。可用的值：before 或 after。默认为 before。
; max=value"
: 对于基于字符的输入，使用 HTML5 maxlength 属性的最大输入值长度（字符数）。要从元素中完全删除 maxlength 属性（不建议），请使用 max=""。对于基于数字的输入，字段接受的输入值最大值，使用 HTML5 max 属性（可以是负值）。默认为 100。要从数字输入元素中完全删除 max 属性，请使用 max=""。
; min="value"
: 对于基于字符的输入，使用 HTML5 minlength 属性的最小输入值长度（字符数）。默认未设置，即没有最小限制。对于基于数字的输入，字段接受的输入值最小值，使用 HTML5 min 属性（可以是负值）。默认为 0。要从数字输入元素中完全删除 min 属性，请使用 min=""。
; name="value"
: 字段名称，用于 HTML <input> 标签。
; pattern="regex"
：控制字段数据格式期望的正则表达式。仅用于基于字符的输入。
；placeholder="text"
：当<input>字段为空时显示的引导文本。
; required="boolean"
：此字段是否必须填写。可用的值：1（是）或0（否）。默认值是<txp:com_connect>标签的required属性中设置的值——如果两个属性都没有设置，则默认为1。
；size="value"
：<input>字段的大小（字符数）。
；step="value"
：对于基于数字的输入，最小值和最大值之间的间隔。
；type="value"
：文本输入类型。默认是text。可选择以下选项：
：color
：date
：datetime
：datetime-local
：month
：number
：password
：range
：search
：tel
：text
：time
：url
：week

示例

示例 1：文本输入框

<txp:com_connect_text label="Your name" />

示例 2：范围滑动条

<txp:com_connect_text type="range" label="UK shoe size" min="1" max="15" />

示例 3：带验证的电话输入

创建一个电话字段，带有英国电话号码格式的验证模式

<txp:com_connect_text type="tel" label="Telephone" pattern="^\s*\(?(020[7,8]{1}\)?[ ]?[1-9]{1}[0-9{2}[ ]?[0-9]{4})|(0[1-8]{1}[0-9]{3}\)?[ ]?[1-9]{1}[0-9]{2}[ ]?[0-9]{3})\s*$" required="1" />

com_connect_email 标签

<txp:com_connect_email />

<input>字段用于用户的电子邮件地址。

输入的电子邮件地址将自动验证，以确保其格式为“abc@xxx.yyy[.zzz]”。在非Windows服务器上，将进行测试以验证该域名是否存在A或MX记录。这两个测试都不能防止垃圾邮件，但有助于检测意外输入错误。

属性

; autocomplete="value"
：指示控制值是否可以由浏览器自动完成。可能的值是：off（浏览器不会自动完成输入）或on（浏览器可以根据用户在之前的用法中输入的值自动完成值）。默认未设置。
; break="tag"
: 在 <label> 和 <input> 字段之间插入换行标签。默认为 <br />。使用 break="" 将标签和输入字段放在同一行。
; class="space-separated values"
：设置标签的CSS class名称。默认：comEmail。要完全删除元素的class属性，使用class=""。
; default="value"
: 没有提供输入时的默认值。
; html_form="id"
: 字段所附 <form> 标签的 HTML id。默认与包含的表单相关联。
; label="text"
：显示给用户的文本标签。默认是Email。
; label_position="text"
: 标签相对于 <input> 字段的位置。可用的值：before 或 after。默认为 before。
；max="integer"
：使用HTML5 maxlength属性定义的最大输入值长度（字符数）。默认是100。要完全删除元素的maxlength属性（不建议），使用max=""。
；min="integer"
：使用HTML5 minlength属性定义的最小输入值长度（字符数）。默认未设置，即没有最小限制。
; name="value"
: 字段名称，用于 HTML <input> 标签。
；placeholder="text"
：当<input>字段为空时显示的引导文本。
; required="boolean"
：此字段是否必须填写。可用的值：1（是）或0（否）。默认值是<txp:com_connect>标签的required属性中设置的值——如果两个属性都没有设置，则默认为1。
; send_article="boolean"
：当使用发送文章功能时，此字段是否用作收件人电子邮件地址。可用的值：1（是）或0（否）。默认是0。
；size="value"
：<input>字段的大小（字符数）。

示例

示例 1：标准电子邮件字段

<txp:com_connect_email label="Your email address" />

com_connect_textarea 标签

<txp:com_connect_textarea />

创建一个<textarea>。

属性

; autocomplete="value"
：指示控制值是否可以由浏览器自动完成。可能的值是：off（浏览器不会自动完成输入）或on（浏览器可以根据用户在之前的用法中输入的值自动完成值）。默认未设置。
; break="tag"
：在<label>和<textarea>之间的换行标签。默认是<br />。使用break=""将<label>和<input>字段放在同一行。
; class="space-separated values"
：设置<textarea>的CSS class名称。默认：comTextarea。要完全删除元素的class属性，使用class=""。
；cols="integer"
：<textarea>的列数，以字符为单位。默认是58。
; default="value"
: 没有提供输入时的默认值。
; html_form="id"
：与<textarea>关联的HTML id的<form>标签。默认与包含的表单关联。
; label="text"
：显示给用户的文本标签。默认是Message。
; label_position="text"
：标签相对于<textarea>字段的位置。可用的值：before或after。默认是before。
；max="integer"
：使用HTML5 maxlength属性定义的最大输入值长度（字符数）。默认是10000。要完全删除元素的maxlength属性（不建议），使用max=""。
；min="integer"
：使用HTML5 minlength属性定义的最小输入值长度（字符数）。默认未设置，即没有最小限制。
; name="value"
: 字段名称，用于 HTML <input> 标签。
；placeholder="text"
：当 <textarea> 为空时显示的引导文本。
; required="boolean"
：此字段是否必须填写。可用的值：1（是）或0（否）。默认值是<txp:com_connect>标签的required属性中设置的值——如果两个属性都没有设置，则默认为1。
；rows="integer"
：<textarea> 的行数，以字符为单位。默认为 8。
；wrap="value"
：控制单词换行。可用值：hard 或 soft。如果未指定此属性，则默认为 soft。

示例

示例 1：标准文本区域

创建一个宽度为 40 个字符、高度为 10 行的文本区域，并带有自定义标签

<txp:com_connect_textarea cols="40" rows="10" label="Your question" />

com_connect_submit 标签

<txp:com_connect_submit />

创建一个提交按钮。当用作容器标签时，将使用 <button> 元素而不是 <input> 元素。

属性

; class="space-separated values"
：设置标签的 CSS class 名称。默认：comSubmit。要从元素中完全删除 class 属性，请使用 class=""。
; html_form="id"
：按钮所附加的 HTML <form> 标签的 id。默认与包含的表单关联。
; label="text"
：提交按钮上显示的文本。默认为 发送。

示例

示例 1：标准提交按钮

<txp:com_connect_submit />

示例 2：具有自定义文本的提交按钮

<txp:com_connect_submit label="To the moooon" />

示例 3：用作容器标签

这允许您在提交按钮中使用 Textpattern 标签和 HTML 标记

<txp:com_connect_submit><strong>Send</strong> question</txp:com_connect_submit>

示例 4：图像按钮

如上例 3，但使用图像作为按钮

<txp:com_connect_submit>
    <img src="path/to/img.png" alt="submit">
</txp:com_connect_submit>

com_connect_select 标签

<txp:com_connect_select />

创建下拉选择 <select> 列表或可滚动 <select> 列表框的容器标签（通过使用 size 属性）。

属性

; break="tag"
：标签和 <select> 字段之间的换行标签。默认为 <br />。使用 break="" 将标签和输入字段放在同一行。
; class="space-separated values"
：设置列表的 CSS class 名称。默认：comSelect。要从元素中完全删除 class 属性，请使用 class=""。
；delimiter="character"
：使用 options 属性时，列表项之间的分隔字符。默认为 ,（逗号）。如果此标签用作容器，则忽略。
; label="text"
：显示给用户的文本标签。默认为 Option。
; label_position="text"
：标签相对于 <select> 字段的位置。可用值：before 或 after。默认为 before。
; html_form="id"
：HTML <form> 标签的 id，其中包含 <select>。默认与包含的表单关联。
；multiple="boolean"
：是否允许从选项集中选择多个选项。默认：未设置。
; name="value"
：用作 HTML <select> 标签的字段名称。
；options="comma-separated values"
：要在选择框中显示的项目列表（之前称为 list）。将第一个条目用 {大括号} 包围，以表示它是“空”占位符。或者，可以在该标签的容器内使用 <txp:com_connect_option /> 标签。
; required="boolean"
：此字段是否必须填写。可用的值：1（是）或0（否）。默认值是<txp:com_connect>标签的required属性中设置的值——如果两个属性都没有设置，则默认为1。
；selected="value"
：默认选择的列表项。
；size="value"
：如果要将 <select> 表示为可滚动的列表框，则此属性表示一次应可见的列表行数。默认未设置（即下拉选择 <select> 列表）。

示例

示例 1：单列下拉选择列表

一个标签为“部门”的列表，包含三个选项和一个默认显示的空白选项，标签为“选择部门”，强制用户进行选择。

<txp:com_connect_select label="Department" options="{Choose dept},Marketing,Sales,Support" />

示例 2：使用 com_connect 选项标签

与上述示例相同，但默认选择“销售”。

<txp:com_connect_select label="Department" selected="Sales">
    <txp:com_connect_option label="{Choose dept}" />
    <txp:com_connect_option label="Marketing" />
    <txp:com_connect_option label="Sales" />
    <txp:com_connect_option label="Support" />
</txp:com_connect_select>

使用选项标签的优点是您可以在标签和标签之外独立命名选项。您还可以向单个选项标签添加布尔 selected 属性，而不是向包含的 select 标签添加。

示例 3：多选

<txp:com_connect_select label="Ice cream flavours" multiple>
    <txp:com_connect_option label="{Choose your favourites}" />
    <txp:com_connect_option label="Vanilla" />
    <txp:com_connect_option label="Strawberry" />
    <txp:com_connect_option label="Raspberry" />
    <txp:com_connect_option label="Chocolate" />
    <txp:com_connect_option label="Mint choc-chip" name="mint-with-chocolate-chips" />
</txp:com_connect_select>

com_connect_option 标签

<txp:com_connect_option />

创建下拉选择选项。可以作为单个（自闭合）或容器标签使用。另见上面提到的com_connect_select标签。

属性

; class="space-separated values"
: 设置选项的CSS类名。默认：comOption。要完全从元素中移除class属性，请使用class=""。
; label="text" 必需
: 向用户显示的此选项的文本标签。用大括号将标签包围，以表示列表开头为空占位符。注意，如果您使用此大括号语法，则值将被强制设置为value=""，即任何提供的值都将被忽略。
; selected="boolean"
: 此项是否选中，也可以在容器标签的selected属性中指定。可用的值：1（是）或0（否）。
; value="text"
: 在提交时与此选项关联的值。默认是标签。

示例 1：包含三个选项的下拉选择列表

<txp:com_connect_select label="Department">
    <txp:com_connect_option label="Marketing" />
    <txp:com_connect_option label="Sales" />
    <txp:com_connect_option label="Support" />
</txp:com_connect_select>

示例 2：传递不同的值而不是标签

默认选中“销售”。

<txp:com_connect_select label="Department">
    <txp:com_connect_option value="contact-marketing">Marketing</txp:com_connect_option>
    <txp:com_connect_option value="contact-sales" selected>Sales</txp:com_connect_option>
    <txp:com_connect_option value="contact-support">Support</txp:com_connect_option>
</txp:com_connect_select>

com_connect_checkbox 标签

<txp:com_connect_checkbox />

创建复选框。

属性

; break="tag"
: 在复选框按钮和标签之间插入换行标签。默认为一个空格。使用break="br"将复选框和标签放在不同的行上。
; checked="boolean"
: 在首次显示时此框是否选中。可用的值：1（是）或0（否）。默认是0。
; class="space-separated values"
: 设置选项的CSS类名。默认：comCheckbox。要完全从元素中移除class属性，请使用class=""。
; html_form="id"
: 与复选框相关联的<form>标签的HTML id。默认与包含的表单关联。
; label="text"
: 向用户显示的文本标签。默认是Checkbox。
; label_position="text"
: 标签相对于<input>字段的相对位置。可用的值：before或after。默认是after。
; name="value"
: 字段名称，用于 HTML <input> 标签。
; required="boolean"
: 此复选框是否必须填写。可用的值：1（是）或0（否）。默认是在<txp:com_connect>标签的required属性中设置的内容 - 如果两个属性都没有设置，则默认为1。
; value="text"
: 如果选项被选中，则在电子邮件中发送的值。如果没有设置，则使用是/否。

示例

示例 1：接受服务条款

必须由用户在发送电子邮件之前勾选的包装协议。

<txp:com_connect_checkbox label="I accept the terms and conditions" />

示例 2：可选复选框

With which operating systems are you familiar?<br />
<txp:com_connect_checkbox label="Windows" required="0" /><br />
<txp:com_connect_checkbox label="Unix/Linux/BSD" required="0" /><br />
<txp:com_connect_checkbox label="macOS" required="0" />

com_connect_radio 标签

<txp:com_connect_radio />

创建单选按钮。

属性

; break="tag"
: 在单选按钮和标签之间插入换行标签。默认为一个空格。使用break="br"将单选按钮和标签放在不同的行上。
; checked="boolean"
: 在表单首次显示时此单选选项是否选中。可用的值：1（是）或0（否）。默认是0。
; class="space-separated values"
: 设置单选按钮的CSS类名。默认：comRadio。要完全从元素中移除class属性，请使用class=""。
; group="text" 必需
: 用于在电子邮件中描述此组单选按钮的文本。此属性值在后续单选按钮中保留，因此您只需在组的第一个单选按钮上设置它。默认是Radio。
; html_form="id"
: 与单选按钮相关联的<form>标签的HTML id。默认与包含的表单关联。
; label="text" 必需
: 作为单选按钮选项向用户显示的文本。
; name="value" 建议
: 作为在HTML <input>标签中使用字段名称。此属性值在后续单选按钮中保留，因此您只需在组的第一个单选按钮上设置它。如果没有设置，则从group属性派生。
; required="boolean"
：是否必须填写此收音机设置。可用的值：1（是）或0（否）。默认值是<txp:com_connect>标签的required属性中设置的值——如果没有设置任何属性，则默认为1。您应仅在组的第一个单选按钮上设置required属性，或为组中的所有单选按钮设置相同的属性值。
; value="text"
：如果选中选项，则在电子邮件中发送的值。如果未设置，则使用标签。

示例

示例 1：单选按钮组

通过在组中的第一个单选按钮上设置group属性，将组互斥的单选按钮分组。电子邮件消息中只使用每个组中选中的单选按钮。消息将按照group: label的形式输出每个选中的单选按钮。

<txp:com_connect_radio label="Medium" group="I like my steak" />
<txp:com_connect_radio label="Rare" />
<txp:com_connect_radio label="Well done" />
<txp:com_connect_radio label="Wine" group="With a glass of" />
<txp:com_connect_radio label="Beer" />
<txp:com_connect_radio label="Water" />

com_connect_secret 标签

<txp:com_connect_secret />

此标签对表单或HTML输出没有影响，但将在电子邮件中包含附加信息。它可以作为一个单标签（自闭合标签）或作为容器标签使用。

属性

; label="text"
：用于在电子邮件中标识字段。默认为Secret。
; name="text"
：内部使用。只有当您有多个具有相同标签的“秘密”表单元素时才设置此属性。
; value="value"
：您想要添加到电子邮件中的文本。

示例

示例 1：作为单个（自闭合）标签

<txp:com_connect_secret value="The answer is 42" />

示例 2：作为容器标签

<txp:com_connect_secret label="Dear user">
    Please provide a useful example for this tag!
</txp:com_connect_secret>

com_connect_serverinfo 标签

<txp:com_connect_serverinfo />

此标签对表单或HTML输出没有影响，但将在电子邮件中基于PHP $_SERVER变量包含附加信息。

属性

; label="text"
：用于在电子邮件中标识字段。默认值为name属性的值。
; name="value" required
：服务器变量的名称。有关完整列表，请参阅PHP手册。

示例

示例 1：将访问者的IP地址添加到电子邮件中

<txp:com_connect_serverinfo name="REMOTE_ADDR" label="IP number" />

示例 2：将访问者浏览器的名称添加到电子邮件中

<txp:com_connect_serverinfo name="HTTP_USER_AGENT" label="Browser" />

com_connect_send_article 标签

<txp:com_connect_send_article />

在您想要显示“发送文章”链接的单个文章表单中使用此标签。

属性

; linktext="text"
：显示链接的文本。默认为send article。

示例

示例 1：在文章表单中

<txp:com_connect_send_article linktext="Send this article" />

com_connect_fields 标签

<txp:com_connect_fields />

遍历提交的字段集。仅在body_form中真正有用，用于在电子邮件正文中格式化用户提供的文本。

属性

; break="text or tag"
：用于分隔每个项目的标签或文本。默认为, @. 使用@break=""来移除此属性的效应。
; class="space-separated values"
：设置包装标签的CSS class名称。默认：未设置。
; label="text"
：要遍历的字段标签的逗号分隔列表。
; name="text"
：要遍历的字段名称的逗号分隔列表。
; wraptag="tag"
：HTML标签（不带尖括号）用于包装字段集。默认：未设置。

请注意，label和name可以单独使用或一起使用。如果两者都省略，则遍历整个字段集。

示例

示例 1：创建提交字段的未有序列表

<txp:com_connect_fields wraptag="ul" break="li">
   <txp:com_connect_label /> = <txp:com_connect_value />
</txp:com_connect_fields>

com_connect_mime 标签

<txp:com_connect_mime />

在body_form中使用此标签以在纯文本电子邮件客户端和/或支持HTML的电子邮件客户端中区分消息的各个部分。

属性

；type="value"
：标签后面跟随的内容类型。从text（纯文本）、html或end（表示块的结束）中选择。

示例

示例 1：纯文本和HTML正文内容

<txp:com_connect_mime type="text" />
<txp:com_connect_fields break="">
   <txp:com_connect_label />: <txp:com_connect_value />
</txp:com_connect_fields>
<txp:com_connect_mime type="html" />
<txp:com_connect_fields wraptag="ul" break="li">
   <txp:com_connect_label /> = <txp:com_connect_value />
</txp:com_connect_fields>
<txp:com_connect_mime type="end" />

请注意，新标签有三个用途

一个用于表示纯文本内容的开始（type="text"）。
一个用于表示HTML内容的开始（type="html"）。
一个用于表示所有内容的结束（type="end"）。

无论您使用文本/HTML类型中的一个还是两个，您都需要“end”，否则您将只能得到垃圾消息。

com_connect_label 标签

<txp:com_connect_label />

返回给定属性名称的标签。

属性

; name="text"
：要检索标签的字段名称。如果用于 <txp:com_connect_fields> 容器内，则 name 为可选，将返回集合中的当前字段。

com_connect_value 标签

<txp:com_connect_value />

通过名称或标签返回给定属性的值。

属性

; break="text or tag"
：如果值是多个（例如，多选选项列表），则使用分隔符断开标签或文本。默认为 , @. 使用 @break="" 以移除此属性的影响。
; class="space-separated values"
：设置包装标签的CSS class名称。默认：未设置。
; label="text"
：要检索值的字段的标签。
; name="text"
：要检索值的字段名称。
; wraptag="tag"
：要包装字段的 HTML 标签（不带尖括号）。默认：未设置。

如果用于 <txp:com_connect_fields> 容器内，则 name 和 label 为可选，标签将使用集合中的当前字段。

com_connect_if 标签

<txp:com_connect_if />

用于检查变量条件的条件标签，无论是通过名称还是标签。

属性

; label="text"
：要检查的字段的标签。
; name="text"
：要检查的字段名称。
; value="text"
：与给定字段进行比较的值。留空仅检查字段是否已分配任何值。

如果用于 <txp:com_connect_fields> 容器内，则 name 和 label 为可选，标签将测试集合中的当前字段。

示例

示例 1：如果访问者输入了特定的值，则采取行动

<txp:com_connect_if name="delivery" value="courier">
   <txp:com_connect_label name="delivery" />: <txp:com_connect_value name="delivery" />
</txp:com_connect_if>.

高级示例

分离输入和错误表单

使用 show_input 和 show_error 在页面不同部分显示表单和错误消息。一个表单用于确保两个表单的内容相同，否则它们将被视为两个独立的形式。第一个表单仅显示错误（无输入），第二个表单仅显示输入字段（无错误）。

<div id="error">
    <txp:com_connect form="contact_form" show_input="0" />
</div>
<div id="inputform">
    <txp:com_connect form="contact_form" show_error="0" />
</div>

除了 show_error 和 show_input 属性之外，其他所有属性在两个表单中必须是 100% 相同，否则它们将被视为两个无关的形式。

用户可选的主题字段

指定 subject_form 属性并创建一个包含 com_connect_select 标签的表单

<txp:com_connect to="you@example.com" subject_form="my_subject_form" />
    <txp:com_connect_text label="Name" /><br />
    <txp:com_connect_email /><br />
    <txp:com_connect_select label="Choose Subject" options=",Question,Feedback" /><br />
    <txp:com_connect_textarea label="Message" /><br />
</txp:com_connect>

创建一个名为“my_subject_form”的 Textpattern 表单，包含以下内容

<txp:php>
    global $com_connect_form;
    echo $com_connect_form['Choose Subject'];
</txp:php>

在 com_connect_select 标签中使用的 label 必须与 subject_form 中的对应变量相同。这里我们使用了 选择主题。

如果您想为所有主题添加一个公共前缀，请使用包含以下内容的 subject_form

<txp:php>
    global $com_connect_form;
    echo 'My common prefix - ' . $com_connect_form['Choose Subject'];
</txp:php>

用户可选的收件人，不显示电子邮件地址

指定 to_form 属性并创建一个包含 com_connect_select 标签的表单

<txp:com_connect to_form="my_com_connect_to_form">
    <txp:com_connect_text label="Name" /><br />
    <txp:com_connect_email /><br />
    <txp:com_connect_select label="Department" options=",Support,Sales" /><br />
    <txp:com_connect_textarea label="Message" /><br />
</txp:com_connect>

创建一个名为“my_com_connect_to_form”的 Textpattern 表单，包含以下内容

<txp:php>
    global $com_connect_form;
    switch($com_connect_form['Department'][0])
    {
        case 'Support':
            echo 'crew@example.com';
            break;
        case 'Sales':
            echo 'showmethemoney@example.com';
            break;
        default:
            echo 'someone@example.com';
    }
</txp:php>

在 com_connect_select 标签中使用的 label 必须与 to_form 中的对应变量相同。这里我们使用了 部门。

在 to_form 中指定一个“默认”电子邮件地址，以确保在添加或更改选择/单选选项并忘记更新 to_form 的情况下使用有效的电子邮件地址。

警告：永远不要使用 com_connect_text、com_connect_email 或 com_connect_textarea 等标签来设置收件人地址，否则您的表单可能会被滥用以向任何电子邮件地址发送垃圾邮件！

样式

表单本身在 <form> HTML 标签上设置了默认 class 为 comConnectForm。

如果使用 thanks_form 模板，则该模板的包装器具有默认 class 为 comThanks。

错误消息列表（如果有）在包含错误列表的 ul HTML 标签上设置了默认 class 为 comError。此类名可以使用 com_connect 标签的 classes 属性重写。

所有表单元素和相应的标签默认都设置了以下类（或 id）

以下之一：comText、comEmail、comTextarea、comSelect、comOption、comRadio、comCheckbox 或 comSubmit。默认情况下，应该很明显哪个 class 用于哪个表单元素（以及相应的标签）。您可以通过使用自己的 class 属性来覆盖这些名称。
根据表单元素是否必填，或者访问者输入的内容中是否发现了错误，使用 comRequired 和/或 errorElement。使用 com_connect 标签中的 classes 属性来覆盖这些。
为相应标签的 name 属性设置的独立 id 或 class。当根据此 class 样式化表单时，您应显式设置 name 属性，因为自动生成的名称可能会在新版本的 com_connect 中更改。

com_connect 的 API

com_connect 插件的插件 API，最初由 Tranquillo 开发，允许其他插件与联系表单交互。这允许额外的功能，例如防止评论垃圾邮件、HTML 邮件、新闻通讯发送等附加到基础插件。

com_connect 中存在四个回调事件

comconnect.submit 在表单提交并检查值是否为空或有效的电子邮件地址后调用，但在发送邮件之前。
comconnect.form 允许您向显示给访问者的联系表单中注入内容（字段）。
comconnect.render 允许您注入或更改整个 <form> 的标记。对于编辑类似 enctype（例如，对于将文件附件模块链接到此插件的模块）等事物非常有用。
comconnect.deliver 在交付前立即调用，并宣传预期的有效载荷，以便您可以对其进行操作。例如，您可以执行像添加 CC: 或 BCC: 字段这样简单的事情。或者，将 MIME 类型标题更改为 text/html 并根据提供的正文数据添加一些 HTML 内容，然后让 com_connect 处理邮件。或者，您可以拦截整个邮件过程，使用第三方系统自行处理邮件，并告诉 com_connect 跳过其内部邮件过程。

以下是一些对插件开发者来说可能有趣的命令

// This will call your function before the form is submitted so you can analyse the submitted data
register_callback('abc_myfunction', 'comconnect.submit');

// This will call your function and add the output (use @return $mystuff;@) to the contact-form.
register_callback('abc_myotherfunction2', 'comconnect.form');

// To get hold of the form-variables you can use global com_connect_form;
// With the following two lines you can tell com_connect if your plugin found spam.
$evaluator =& get_comconnect_evaluator();

// The passed value must be non-zero to mark the content as spam.
// Value must be a number between 0 and 1.
$evaluator -> add_comconnect_status(1);

可以同时激活多个插件，并且它们中的每一个都可以将提交的内容标记为垃圾邮件并阻止表单提交。

示例

register_callback('pap_comconnect_form','comconnect.form');
register_callback('pap_comconnect_submit','comconnect.submit');

function pap_comconnect_form()
{
    $field = '<div style="display:none">'.
        finput('text','phone',ps('phone'),'','','','','','phone').'<br />'.
        finput('text','mail',ps('mail'),'','','','','','mail').'</div>';
    return $field;</code>
}

function pap_comconnect_submit()
{
    $checking_mail_field = trim(ps('mail'));
    $checking_phone_field = trim(ps('phone'));
    $evaluation =& get_comconnect_evaluator();

    // If the hidden fields are filled out, the contact form won't be submitted!
    if ($checking_mail_field != '' or $checking_phone_field != '') {
        $evaluation -> add_comconnect_status(1);
    }

    return;
}

对于交付回调，您向插件发送您的意图，以便 com_connect 知道在您的交付插件执行后要做什么。返回以下字符串

comconnect.send（或没有返回值）以允许 com_connect 继续邮寄内容。
comconnect.skip 跳过 com_connect 的邮寄（即第三方处理邮件过程）并返回“success”给访问者。
comconnect.fail 跳过 com_connect 的邮寄并将“fail”返回给访问者。

或者简单地 exit 您的插件以停止整个操作，因此不会提供任何 com_connect 反馈。

常见问题解答

我该如何移除围绕联系表单的 legend 和 fieldset？

在 com_connect 标签中设置 label 属性为空值（label=""）。

没有发送电子邮件。我该如何诊断和修复这个问题？

首先尝试一个简单的联系表单，仅使用带有设置为有效电子邮件地址的 to 属性的 com_connect 标签。如果那样发送不了邮件，填写 Textpattern 管理员>首选项中的“SMTP 信封发件人地址”字段。如果这也没有帮助，请查看您的邮件服务器日志文件以了解问题所在。

我使用哪个标签来创建提交按钮？

只需使用正常的 HTML 代码来创建提交按钮。由于历史原因，此插件仍然提供 com_connect_submit 标签，但它提供的额外功能很少。

我如何在每封电子邮件的主题中获取一个唯一的（顺序）号码？

在com_connect标签的subject属性中尝试使用rvm_counter标签。

我想在文章列表中使用联系表单（每个文章一个表单），但我如何让每个表单都唯一呢？

您可以通过使其中一个属性值唯一来使每个表单唯一。参见之前的问题，了解如何使用subject属性实现此操作。

发送文章：我可以让人们指定多个收件人吗？

不。现在的“发送文章”功能已经足够垃圾。

发送文章：我可以在不点击链接的情况下显示联系表单吗？

当然，只需将其放在com_connect标签之上即可。

<txp:php>$_GET['com_connect_send_article']='yes';</txp:php>

我如何使用此表单上传文件？

您不能，但请查看ext_file_attach模块或mem_form插件。

我可以使用此插件发送HTML电子邮件吗？

是的。

我可以使用此插件发送新闻通讯吗？

不行，除非使用像mem_postmaster这样的插件。

我有一个这里没有列出的问题

首先再次阅读插件文档（您现在所在的页面）。如果这不能回答您的问题，请访问Textpattern论坛。

作者/致谢

zem编写了zem_contact 0.6插件，本插件最初基于此插件。
Mary完全修改了插件代码。
Stuart将其转换为插件，添加了修改后的帮助文本和额外的代码。维护所有版本直到4.0.3.17。
wet添加了com_connect_radio标签。
Tranquillo添加了反垃圾邮件API和zem_contact_send_article功能。
aslsw66、jdykast和其他人提供了额外的代码。
Ruud清理并审核了代码以消除错误，并完全修改了帮助文本。维护所有版本直到4.0.3.20。
Bloke是v4.5.0.0的维护者。
被采纳为社区插件，现在由核心开发团队维护。
由Textpattern社区支持并进行了破坏性测试。感谢所有额外贡献者。

textpattern / com_connect

维护者

详细信息