README

这个Kirby表单插件提供了最大的灵活性和可用性。它可以在需要的地方用作块，甚至可以每页多次使用。通过集成的mailview字段，您可以在面板中显示请求。

功能丰富： 🎉

⭐️ 编辑器可以灵活组织表单字段。

⭐️ 无需重新加载页面即可快速验证表单（即使在填写过程中）。

⭐️ 可以在块内或使用mailview字段查看和管理传入请求。（包括上传的文件）

⭐️ 您和/或访客将在收到请求时收到电子邮件。

⭐️ 可以在配置或每个表单的面板中更改所有默认文本元素（包括邮件模板）。

⭐️ 每页允许多个表单。

⭐️ 出站电子邮件的模板。

⭐️ 通过添加2个文件（蓝图和模板）轻松创建新的表单字段类型。

⭐️ 集成蜜罐的垃圾邮件保护。

⭐️ 预样式表单

⭐️ 完全支持英语、德语、意大利语、法语、立陶宛语和匈牙利语

安装

仅适用于Kirby > 4.0！

手动

下载并将插件复制到您的插件文件夹中：/site/plugins/

使用Composer

composer require microman/kirby-form-block-suite

获取许可证

有两种许可证可供选择

单站许可证

无限许可证

有关其他插件的更多信息

如果您在使用许可证时遇到问题，请检查此文档末尾的故障排除。

如何使用？

只需在蓝图创建一个块字段，并将form添加到字段集属性中

fields:
  my_block:
    type: blocks
    fieldsets:
      - form

然后使用以下方式在模板中输出块字段

<?= $my_block->toBlocks() =>

如果您不熟悉Kirby块字段，请查看这里。

使用内置样式

为了快速开始使用漂亮的表单，我们集成了基于BEM的样式。不需要框架。其他表单将不受此影响。

要使用内置样式，请将以下行添加到网站头部元素中，在您的样式之前：<?= snippet('blocks/formcore/styles') ?>

要更改默认颜色，请将以下行添加到样式表中

:root {
    --formblock-color: #0d47a1;
    --formblock-color-invert: #fff;
    --formblock-color-error: #CC0000;
    --formblock-color-success: #007E33;
}

设置您的表单块

创建表单块

在插入表单块后，您可以为表单设置名称。

单击显示请求按钮，将打开一个抽屉，其中包含以下选项卡

收件箱： 包含当前表单块的 Mailview 字段。
表单字段： 管理将向访客显示的表单字段。您可以添加更多类型的表单字段。（稍后介绍）
选项： 设置表单的行为。这也可以用于自定义设置。

设置您的表单字段

在 表单字段 选项卡中，您将找到所有在表单中显示的字段。您可以通过点击菜单中的添加来添加更多。

显示标题 中的占位符取自访客在表单中输入的数据。您还可以使用一些额外的占位符。

记住

每个表单字段都需要一个唯一的标识符。确保每个 id 只使用一次。即使是选项条目的 id。否则提交将失败。

默认可用的表单字段类型

关于附件字段类型的说明： 要增加最大文件大小，请将 php.ini 中的 upload_max_filesize、post_max_size 和 memory_limit 设置为所需的值。

定义默认表单块数据

如果您添加了新的 表单块。将附加一个自定义的表单字段和选项集。要更改此设置，请按照以下步骤操作

创建表单块
按需填写
复制表单块
将其粘贴到 site/config/formblock_default_[language_code].json

Mailview字段

您可以使用 mailview 字段来显示当前页和子页的所有请求。

要使用 mailview 字段，请将以下内容插入到您的蓝图

mailview:
  label: My form requests
  type: mailview

功能

新请求和已读请求的精彩概览
查看所有传入请求，将其设置为已读/未读或删除它。
单击请求，将显示访客输入的所有表单数据。
每个表单都按折叠组。折叠的状态将被记住

为了清晰的概览，命名您的表单块。

☝️ 注意！删除表单块将删除此表单块的所有请求，而不会提示！

高级自定义

自定义输出

快速简单：从 site/plugins/kirby-form-blocks/snippets/blocks/ 复制以下文件/文件夹到 site/snippets/blocks/ 并编辑文件

form.php：包含修改说明和您表单的结构
/formtemplate：包含表单的片段。您可以通过 <?= $block->template('your-snippet') ?> 添加更多并插入它
/formfields：您可以在这里找到每个表单字段类型的片段。要添加自定义表单字段，请遵循以下说明

查看 form.php 中的注释以获取重要的修改信息。

表单对象

表单对象提供了一些有用的方法，可以帮助您使用表单块：（例如 $block->showForm()）

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

表单字段对象

要获取表单字段对象，请使用 $block->field('slug_of_the_form_field') 或使用 foreach ($form->fields() as $field) 迭代它

添加自定义表单字段类型

假设您想创建一个表单字段类型，向访客显示一些信息

site/theme/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/theme/snippets/blocks/formfields/info.php

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

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

</div>

确保您的元素包含属性 data-form="field"。

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 ?>

扩展选项

为了给编辑器提供更多选项，您可以在“选项标签”中添加/修改字段。正如您将在下一个捕获中看到的那样，您可以在这里给编辑器提供覆盖默认文本块的能力。

要修改“选项标签”中的字段，将site/plugins/kirby-form-field/blueprints/snippets/form_options.yml复制到site/blueprints/snippets并编辑它

invalid_message:
  label: Custom success message
  type: writer
  help: form.block.default.help

my_custom_message:
  label: Custom Message
  type: writer

您也可以用form_confirm.yml和form_notify.yml这样做。例如（> v4.1.0），如果您想提供设置回复地址的机会，请将这些行添加到form_notify.yml

notify_reply:
  label: Reply
  type: email
  when:
    enable_notify: true

同样的方法也适用于BCC和确认邮件

notify_bcc
confirm_reply
confirm_bcc

要禁用确认或通知，请使用配置。

消息

消息是用于前端或通知/确认邮件中的文本片段。
您可以在代码中手动使用消息，如下所示：$block->my_message()。
在消息中使用占位符，如下所示：亲爱的{{title}} {{name}}。有关占位符的更多信息。
对于单语言页面，请在配置中设置默认语言
有三种方法可以更改/添加消息（按优先级排序）

复制并修改翻译文件site/plugins/kirby-form-field/lib/languages/*.php -> form.block.message.*
在带有翻译的配置中
让编辑器决定：在选项标签中使用自定义字段

可用的文本块

配置

出站电子邮件的电子邮件地址

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

默认：no-reply@[您网站的根URL]。这是以下消息的后备电子邮件地址：notify_email、notify_from和confirm_email。

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

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

纯文本电子邮件

默认情况下，插件将使用HTML作为确认/通知电子邮件的正文。您可以通过这种方式禁用它

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

感谢felix

蜜罐

表单块插件在表单中插入一个隐藏的蜜罐字段，以防止机器人发起请求。如果机器人填写此字段，请求将失败。每个字段都有一个上下文字段。插件检查正在使用的上下文，并从该数组获取蜜罐字段的下一个可用上下文。

您可以使用此设置更改顺序和上下文类型。

'microman.formblock' => [
  'honeypot_variants' => ["email", "name", "url"]
],

占位符

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

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

您可以在任何地方（邮件、文本块、显示名称）使用占位符，如下所示：{{ip}}

禁用功能

可以禁用像“通知电子邮件”或“确认电子邮件”这样的函数

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

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

电子邮件模板

从版本4.3.6开始，您可以这样设置外出电子邮件的模板

'microman.formblock' => [
  'email_template_confirmation' => require kirby()->root('site') . '/templates/emails/confirmation.php',
  'email_template_notification' => `
    { name } has sent you a message
  `
],

翻译

以这种方式更改自定义文本

'microman.formblock' => [
  'translations' => [
    'en' => [
        'success_message' => 'Your beautiful request has been sent.'
    ],
    'de' => [
        'success_message' => 'Deine wunderschöne Anfrage wurde versendet.'
    ]
  ]
],

见消息章节获取更多信息。

动态验证

表单是动态验证的（提交时不会重新加载页面）。您可以通过这种方式禁用此功能

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

如果您禁用此功能，您将失去一些功能

填充时无验证
发送后将删除附件（访客需要在验证失败时再次添加它们）
无上传进度条
发送后表单不会居中

电子邮件字段

对于确认或通知电子邮件，需要有一个包含访客电子邮件地址的字段。您可以这样设置电子邮件字段的ID。

'microman.formblock' => [
  'email_field' => 'email',
],

如果没有找到具有该ID的字段，插件将采用第一个字段类型为“电子邮件”的字段。

钩子成功

'hooks' => [
  'formblock.success:after' => function (\microman\FormRequest $request) {
      //Your code
  },
  
]

钩子验证

当表单字段正在验证时触发。

$errors是所有发生的错误数组。您可以添加或删除错误。

此示例显示在输入特定电子邮件地址时显示错误消息。

'hooks' => [
  'formblock.validation:before' => function (string $slug, string $value, array $errors): array
  {
    if ($slug === 'email' && in_array($value, [ 'mail_1@spam.com', 'mail_2@spam.com' ])) {
      array_push($errors, "This is an invalid email adress.");
    }
    return $errors;
  }
]

故障排除

在您打开问题之前，请仔细阅读本章。

问题：我如何在Kirby环境中使用表单块套件？

解决方案：此插件是一个Kirby块。在开始之前，请仔细阅读本手册。

问题：表单不会发送

解决方案：移除（如果使用）自定义模板并再次尝试。如果仍然不起作用，请打开浏览器中的开发者工具（F11），检查控制台。为后续支持制作截图。

问题：在面板中保存表单时出错

解决方案：确保所有表单字段都有一个唯一的标识符。（点击向导图标从显示名称自动填充）

问题：表单没有翻译成正确的语言？

解决方案：您的网站不是多语言的。或者Kirby不知道访客的语言。手动设置默认语言

'microman.formblock' => [
  'default_language' => 'de'
]

对于多语言网站，将忽略此设置。

问题：验证许可证密钥时出错

解决方案

如果您还没有许可证？获取单个站点许可证或无限站点许可证。
您的服务器需要连接到许可证服务器：https://license.mircroman.ch
您的许可证密钥已被另一个主机验证：请发送一封电子邮件（包括您的许可证密钥）以释放分配。
删除许可证文件并再次尝试。文件夹：/site/config/.formblock_license

问题：验证问题