README

已废弃 v2.0.4 -> v3.0

此插件不再维护！

使用具有许多新功能的 Kirby Form Block Suite。

概述

此 Kirby 表单插件提供最大限度的灵活性和可用性。它可以在需要的地方用作区块，甚至可以在每页多次使用。

基于 Kirby 3.6 的出色功能。

包含丰富的功能： 🎉

✅ 编辑器可以灵活地组织表单字段。

✅ 从 V2.0 开始，集成了 honeypot 进行垃圾邮件防护。

✅ 通过添加 2 个文件（蓝图和模板）轻松创建自定义表单字段。

✅ 新创建的表单区块将默认使用来自 JSON 文件的数据填充（您可以从现有表单区块中复制）。

✅ 可在区块内查看和管理传入请求。（可选）

✅ 您和/或访客将在收到请求时收到电子邮件。（如果需要）

✅ 可在配置文件中定义自定义表单数据。（例如，用于使用 IP 地址等）。

✅ 支持英语和德语。消息完全可定制/可扩展，适用于开发人员和/或编辑器。

开始之前

是否缺少功能？发布功能请求并捐赠一些东西。我无法保证您的建议将包含在下一个版本中。

安装

仅适用于 Kirby 3.6+！ (在此更新！) 下载并将此存储库复制到您的插件文件夹： /site/plugins/

Composer

composer require microman/kirby-form-blocks

基本用法

只需将 form 放入区块字段中的字段集

fields:
  my_block:
    type: blocks
    fieldsets:
      - form
      ...

如果您不熟悉 Kirbys 的区块字段请查看此处。

在 区块预览 中，您可以设置表单的名称，并检查是否有新的请求。在区块设置中，您有 3 个选项卡

收件箱：显示所有请求。将其设置为（未）阅读、删除或更改单个条目的视图（使用占位符）。（更改显示文本）
表单字段：管理将显示给访客的表单字段。您可以添加更多类型的表单字段。（稍后更多）
选项：设置收到请求时的行为。可以通过其他字段进行扩展

定义默认表单区块数据

如果您的编辑器多次使用相同或类似的形式，设置默认设置可能很有用。要定义默认表单字段和表单选项，请按照以下步骤操作

创建一个表单块
填写所需的字段
复制表单块
将其粘贴到´site/config/formblock_default.json´

如果您的网站是多语言的，您可以为网站上的每种语言设置文件名后缀。（例如 formblock_default_de.json）

自定义输出

快速简单：将 site/plugins/kirby-form-blocks/snippets/blocks/ 复制到 site/snippets/blocks/ 并编辑文件。

表单字段类型

以下表单字段类型默认可用

	名称	输出
1	输入
2	文本区域
3	选择框
4	复选框
5	单选按钮

添加自定义表单字段类型

假设您想创建一个向访客显示信息的表单字段

site/blueprints/blocks/formfields/info.yml

name: Information
icon: alert

fields:
  title:
    type: text
    width: 1/2
  color:
    type: select
    width: 1/2
    options:
      green: Green
      orange: Orange
      red: Red
  info:
    label: form.block.fromfields.select.placeholder
    type: writer

site/snippets/formfields/info.php

<div class="info-field" id="<?= $formfield->slug() ?>" style="background:<?= $formfield->color() ?>">
    
    <?php if($formfield->title()->isNotEmpty()): ?>  
        <h3><?= $formfield->title() ?></h3>
    <?php endif ?>

    <?= $formfield->info() ?>

</div>

Et voilà。您刚刚创建了一个新的表单字段类型

要按面板中的字段排序，您可以在蓝图文件名中使用前缀，例如 05_fieldname。默认字段保持在顶部。

修改默认表单字段类型

只需将 site/plugins/kirby-form-field/blueprints/blocks/formfields 复制到 site/blueprints/blocks/formfields 并编辑它。

要禁用默认表单字段类型，只需删除文件内容。

自定义字段

每个表单字段默认都有以下字段

名称	描述
显示名称	用于标签
唯一标识符	它是与字段一起工作的必需项。
上下文	定义输入类型。对于自动完成和垃圾邮件保护是必需的。
必需	访客必须填写此字段

确保唯一标识符在整个表单块中只使用一次！

向所有表单字段类型添加自定义字段

让我们做一个例子，添加一个用于宽度的字段

site/blueprints/blocks/customfields.yml

width:
  label: Width
  type: select
  options:
    col-12: "1/1"
    col-6: "1/2"
    col-4: "1/3"

输出

<?php foreach ($form->fields() as $field) : ?>

  <div class="<?= $field->width() ?>">

    <?= $field->toHtml() ?>

  </div>
<?php endforeach ?>

消息

消息是文本片段，可以在您的代码中像这样使用：$form->my_message()。

以下消息默认可用

键	描述
notify_subject	通知电子邮件的主题
notify_body	通知电子邮件的内容
confirm_subject	确认电子邮件的主题
confirm_body	通知电子邮件的内容
success_message	如果表单成功发送，向访客显示的消息
fatal_message	如果发生错误，向访客显示的消息
invalid_message	所有有错误的字段的摘要。 {{ fields }} 插入无效表单字段的列表
exists_message	表单已填写（如果启用 verify_content）
send_button	无需解释 🤷‍♂️

有三种方法可以更改/添加消息（按优先级排序）

插件内的翻译文件 site/plugins/kirby-form-field/lib/languages/*.php -> form.block.*
在配置中使用翻译
作为选项卡中的自定义字段。要修改选项卡中的字段，将 site/plugins/kirby-form-field/blueprints/snippets/form_options.yml 复制到 site/blueprints/snippets 并编辑蓝图

success_message:
  label: Custom success message
  type: writer

my_custom_message:
  label: Custom Message
  type: writer

如您所见，您还可以插入用于默认消息的字段，以便编辑器可以自定义它们。

该片段文件夹中还有 form_confirm.yml 和 form_notify.yml。不要修改它们！更好的办法是在配置中禁用底层功能 in the config。

占位符

为类似“Hello {{given-name}}”的消息使用占位符。更多详情请参阅配置->占位符。

对象

表单对象

表单对象为你提供了一些有用的方法，帮助你处理表单块：（例如 $form->showForm()）

方法	描述	参数
showForm	如果表单准备好填充，则返回 `true`	(None)
fields	返回表单字段。	$attrs: 希望的属性（例如 'label' 返回字段的标题，`null` 返回表单字段对象）的数组或字符串
field	通过唯一标识符返回表单字段	$slug: 字段的唯一标识符 $attrs: 希望的属性（例如 'label' 返回字段的标题，`null` 返回表单字段对象）的数组或字符串
isFilled	如果访问者提交了表单，则返回 `true`	(None)
isValid	如果访问者正确填写了表单，则返回 `true`	(None)
isFatal	如果出了严重错误，则返回 `true`	(None)
isSuccess	如果请求成功发送，则返回 `true`	(None)
errorFields	以列表或数组的形式返回无效表单字段	$separator: 用于分隔字段名的字符。 `null` 返回数组
message	返回消息	$key: 文本的键 $replaceArray: 额外的占位符
errorMessage	如果 `isFatal`，则返回错误消息	(None)
successMessage	如果 `isSuccess`，则返回成功消息	(None)
sendNotification *	向操作员发送电子邮件（如果通知已启用）	$body: 电子邮件的内容 $recipient: 要发送到的电子邮件（可选）
sendConfirmation *	向访问者发送电子邮件（如果确认已启用）	$body: 电子邮件的内容 $reply: 访问者可以回复的电子邮件（可选）
setError	将表单状态设置为 `isFatal`	$error: 错误消息 $save: 如果 `true`，则请求将保存到收件箱

* 仅在您想发送额外的电子邮件时使用。默认情况下，电子邮件在插件成功完成后自动发送。

表单字段对象

方法	描述	参数
*	从表单字段中返回字段。 (例如 `$field->custom_field()`)	(None)
value	来自表单数据或默认值的价值	$raw: `true`... ...返回未进行HTML转义的值 ...带有选项：返回slug（不是标签）
label	显示名称	(None)
slug	唯一标识符	(none)
autofill	自动完成的上下文	$html `null` 返回bool `attr` 返回 ' autocomplete="my_context"'
required	如果字段是必需的，则返回true或表达式	$html `null` 返回bool `asterisk` 返回 ' * ' `attr` 返回 ' required'
type	返回字段类型	(none)
isFilled	如果表单字段不为空，则返回true	(none)
isValid	如果表单字段填写正确，则返回true	(none)
errorMessages	如果无效，则返回所有错误的数组	(none)
errorMessage	如果无效，则返回一个错误	(none)
hasOption	如果表单类型是复选框、单选按钮或选择框，则返回 `true`	(none)
selectedOptions	返回所选选项的数组	$prop: 所需属性。默认 = 值
options	返回带有选项的结构字段	(none)
ariaAttr	返回 aria 属性。 (对于无效字段)	(none)

配置

发件人电子邮件地址

'microman.formblock' => [
    'from_email' => 'info@example.com'
],

默认: no-reply@[你的网站根 URL]

如果域名与网站域名不同，请检查 DMARC 以确保电子邮件不会被拒绝。

你可能在本地环境上遇到 SMTP 错误。请在服务器上测试电子邮件功能！

占位符

除了传入的表单数据外，还可以定义额外的占位符。 (可以在您的消息中使用 {{}} ) 例如，确定发送者的 IP 地址

'microman.formblock' => [
  'placeholders' => [
    'ip' => [
      'label' => "IP address",
      'value' => function ($fields) {
        return $_SERVER['REMOTE_ADDR'];
      }
    ]
  ]
],

禁用功能

可以禁用诸如 请求保存、通知电子邮件 或 确认电子邮件 等功能

'microman.formblock' => [
  'disable_inbox' => true,
  'disable_confirm' => true,
  'disable_notify' => true,
],

相应的功能将不再执行，并且在面板中标签/字段将不再可见。

验证内容（自 V2.0 版起）

为了确保访客不会多次提交表单（例如通过刷新页面），此插件检查是否已提交具有相同内容的表单。在这种情况下，向访客显示错误消息。

此功能默认启用，可以使用此示例禁用它

'microman.formblock' => [
  'verify_content' => false,
],

翻译（自 V2.0 版起）

有关更多信息，请参阅消息章节

'microman.formblock' => [
  'translations' => [
    'en' => [
        'success_message' => 'Form send!'
    ],
    'de' => [
        'success_message' => 'Formular versendet!'
    ]
  ]
],

结论

如果您有任何问题或某些功能无法正常工作，请告知我。

希望您会喜欢这个插件。敬请期待！

microman / kirby-form-blocks

维护者

详细信息