README

A zero-configuration drop in module to power your ProcessWire FormBuilder forms with AJAX via HTMX.

功能

将使用 Pro FormBuilder 模块构建的任何表单转换为 AJAX
表单就地处理，提交后无需页面刷新
不与现有样式或 JavaScript 冲突
无需修改即与 FormBuilder 兼容，所有模块行为和功能保持不变
可以作为每个表单与 FormBuilder 本地输出方法一起使用
兼容 ProCache
兼容 FieldtypeFormSelect

需求

ProcessWire >= 3.0
FormBuilder >= 0.5.5 (未经其他版本测试，但应可工作)
PHP >= 8.1
HTMX 库 (此模块未提供)

未包含 HTMX 的原因有很多。最重要的是，此模块使用核心 HTMX 行为构建，预计不会随着新版本而改变，但如果有改变，将进行更新。它还保证了在项目中 HTMX 可能已经存在的情况下不会发生冲突。使用适合您的版本，并自信地将此模块添加到现有应用程序中。

如何使用

步骤 1. 禁用表单的 CSRF 保护。（下面解释原因）

步骤 2. 将对象从 $forms 切换到 $htmxForms

<!-- Replace $forms->render('your_form'); with this: -->
$htmxForms->render('your_form_field');

步骤 3. （没有步骤 3）

好了。

提交按钮在提交时自动禁用，以防止用户点击过快导致的重复请求。

FormBuilderHtmx 使用 FormBuilder 的 "Option C: Preferred Method" 进行渲染。有关其他详细信息，请参阅表单设置页面上的 "嵌入" 选项卡。

$htmxForms->render() 是等效 FormBuilder 方法的直接替换。它可以挂钩（下面详细介绍）并接受其第二个 $vars 参数。通过直接替换，它允许您继续以期望的方式使用 FormBuilder API，包括脚本和 CSS 工具。

<!--
  Keep your workflow, $htmxForms returns the same object as $forms
  The second prefill parameter mirrors FormBuilder, add prefill values as needed
-->
$htmxForm = $htmxForms->render('your_form_field', [
  'first_name' => "Biff",
  'last_name' => "Tannen",
  'email' => "biff@hillvalley.com",
]);

echo $htmxForm->styles;
echo $htmxForm->scripts;
echo $htmxForm;

包含活动指示器

与标准表单不同，它会触发页面刷新，AJAX 推动的表单在用户采取行动后不会提供任何反馈。FormBuilderHtmx 允许您通过向用户显示您选择的一个元素来处理这种情况。查看这些动画以获取灵感和现成的代码。

以下是一个使用 'spinner' 的完整实现示例

<style>
  /*
   * Include some CSS. The `.activity-indicator` class name is up to you. `.htmx-request` is
   * required and must remain unchanged
   */

  .activity-indicator {
    display: none;
  }

  /* Style as you please */
  .htmx-request .activity-indicator,
  .htmx-request.activity-indicator {
    display: inline;
  }
</style>

<!-- The third argument is a CSS selector matching your 'spinner' -->
<?= $htmxForms->render('your_form', [], '#your-form-indicator') ?>

<div id="your-form-indicator" class="activity-indicator">
  <span class="spinner"></span>
</div>

更多好了。

向您的表单添加额外的 HTML 属性

您可以通过传递一个字符串数组作为第四个参数来向 FormBuilder 的 <form> 元素添加额外的 HTML 属性。这允许您添加自定义属性，或将额外的 HTMX 属性添加到进一步扩展您的 FormBuilder 表单功能。

以下是一个在提交表单之前向用户显示确认信息的表单示例

<?= $htmxForms->render('your_form', [], '#your-form-indicator', [
  'hx-confirm="Are you sure you want to submit this form?"'
]) ?>

以下属性将由 FormBuilderHtmx 自动添加

hx-post
hx-headers
hx-disabled-elt="button[type=submit]"
hx-target
hx-swap
hx-indicator 可选，只有当通过 $htmxForms->render() 方法的第三个参数传入CSS选择器时才会添加

尝试添加或替换这些属性可能会导致问题或导致表单无法正确提交。

CSRF保护

对于使用HTMX/AJAX的表单，可能需要禁用CSRF保护 测试以确保提交表单时没有CSRF错误。如果遇到问题，请禁用CSRF。

它是如何工作的？

FormBuilderHtmx在页面加载前修改FormBuilder的标记，通过设置/添加到表单中的属性来启用HTMX处理提交。

当表单提交时，FormBuilder会像往常一样处理数据并返回完整的页面标记。FormBuilderHtmx解析它并提取HTMX期望在响应中包含的内容。

挂钩

FormBuilderHtmx提供了一个可挂钩的方法来处理FormBuilder处理后的页面输出标记。这与原生的可挂钩的FormBuilder::render()方法完全相同。

传递给此挂钩的标记是在上述方式下由FormBuilderHtmx处理后渲染到页面上的标记。

$wire->addHookAfter('FormBuilderHtmx::render', function(HookEvent $event) {
  $formHtmlMarkup = $event->return;

  // Modify markup as desired
  $event->return =<<<EOT
    <p>Look at these AJAX processed results:</p>
    {$formHtmlMarkup}
  EOT;
});

巧妙技巧

此模块允许您在单个页面上多次使用同一字段。只有一个将被提交和处理。

firewire / formbuilder-htmx

维护者

详细信息