README

使用标准 HTML5 标记来创建 WordPress 的完整功能表单

功能

仅使用 HTML5 语法构建表单。没有 GUI、短代码、没有废话
与任何有效的 HTML 表单兼容。只需复制任何网站上的任何表单即可工作。 它是魔法！
提交将保存为自定义帖子类型帖子。表单值将保存为自定义字段。
验证带有原生 HTML5 required 属性标记的必填字段。
它是可修改的。 使用钩子和 API 添加您自己的功能。
接收表单提交的电子邮件通知
通过输入类型=file 完全支持上传到媒体库
与 Polylang 兼容的多语言支持
通过过滤器钩子提供预定义的静态 HTML 表单
动态值，如 %USER_EMAIL% 用于预先填充表单数据

为什么？

现代 HTML 标记本身就是一个构建表单的好方法。使用 Libre Form，无需学习难以定制的笨拙表单构建器。

只需使用标准 HTML 输入构建，或复制表单到您的 WordPress 网站，它将神奇地工作。如果您不想，无需触摸 PHP 代码。

默认情况下，在插件的核心中包含必需字段验证、电子邮件通知、将文件上传到 WP 相册等，但您还可以使用 Libre Form 提供的钩子和 API 添加您自己的功能。

试试看

TryoutWP 为我们提供了一个实时演示，您可以在这里找到。它反映了当前版本，而不是 master 分支。

屏幕截图

编辑表单

表单在默认的 Twentysixteen 主题中显示

提交视图

单个提交视图

安装

Composer 方法（首选）

通过 Composer 安装插件

composer require anttiviljami/wp-libre-form

激活插件

wp plugin activate wp-libre-form

传统方法

此插件可在官方 WordPress.org 插件目录中找到。

您还可以按照以下说明直接上传 zip 文件安装插件

下载插件
通过 WordPress 插件上传器或您首选的方法将插件上传到 /wp-content/plugins/
激活插件

过滤器/操作 API

过滤器：wplf_validate_submission

用于添加对您表单的验证。

表单特定钩子

此过滤器支持表单特定钩子

wplf_{form_id}_validate_submission
wplf_{form_slug}_validate_submission

这些过滤器仅应用于目标表单，通过 ID 或 slug。

示例：Google ReCaptcha 集成

/**
 * ReCaptcha for WP Libre Form
 */
add_filter( 'wplf_validate_submission', 'wplf_recaptcha' );
function wplf_recaptcha( $return ) {
  // skip this validation if submission has already failed
  if ( ! $return->ok ) {
    return $return;
  }

  $secret = RECAPTCHA_KEY; // substitute with your own secret recaptcha key string
  $options = [
    'http' => [
      'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
      'method'  => 'POST',
      'content' => http_build_query([
        'secret' => $secret,
        'response' => $_POST['g-recaptcha-response'],
      ])
    ],
  ];

  $context  = stream_context_create( $options );
  $result = file_get_contents( 'https://www.google.com/recaptcha/api/siteverify', false, $context );

  $captcha_obj = json_decode( $result );

  if ( false === $captcha_obj->success ) {
    $return->ok = 0;
    $return->error = __("Please prove you're not a robot before submitting.");
  }

  return $return;
}

操作：wplf_post_validate_submission

在表单验证完成后触发。

表单特定钩子

此操作支持表单特定钩子

wplf_{form_id}_post_validate_submission
wplf_{form_slug}_post_validate_submission

这些操作仅针对通过 ID 或 slug 指定的目标表单运行。

示例：向提交中的电子邮件发送感谢邮件

add_action( 'wplf_post_validate_submission', 'my_email_thankyou' );
function my_email_thankyou( $return ) {
  // recipient details from submission
  $name = sanitize_text_field( $_POST['name'] );
  $email = sanitize_email( $_POST['email'] );

  // email subject
  $subject = __( 'Thank You For Submitting A Form' );

  // text body of email
  $body = wp_sprintf( __('Thanks, %s for clicking Submit on this glorious HTML5 Form!'), $name );

  // send the email
  wp_mail( $email, $subject, $body );
}

过滤器：wplf_disable_validate_additional_fields

默认情况下禁用动态生成的字段。如果您希望允许提交中未设置的字段，可以使用此过滤器。

表单特定钩子

此过滤器支持表单特定钩子

wplf_{form_id}_disable_validate_additional_fields
wplf_{form_slug}_disable_validate_additional_fields

这些过滤器仅应用于目标表单，通过 ID 或 slug。

为所有表单禁用附加字段验证

add_filter( 'wplf_disable_validate_additional_fields' , '__return_true' );

过滤器：wplf_allowed_additional_form_fields

您可以提供自己的允许字段名集合，而不是完全禁用附加字段验证。

表单特定钩子

此过滤器支持表单特定钩子

wplf_{form_id}_allowed_additional_form_fields
wplf_{form_slug}_allowed_additional_form_fields

这些过滤器仅应用于目标表单，通过 ID 或 slug。

为所有表单禁用附加字段验证

add_filter( 'wplf_allowed_additional_form_fields' , ['dynamic-field-name'] );

过滤器：wplf_dynamic_values

添加或自定义表单中可用的动态值。

示例：新值

add_filter('wplf_dynamic_values', function($values) {
  $values['SOMETHING'] = [
    'callback' => function() { return 'something'; },
    'labels' => [
      'name' => 'Something',
      'description' => 'Something really useful.'
    ],
  ];

  return $values;
});

// <input type="text" placeholder="%SOMETHING%" name="something">

过滤器：wplf_uploaded_file_name

如果您选择不将上传的文件添加到媒体库，您可以更改文件上传的名称。

add_filter('wplf_uploaded_file_name', function($name, $file, $id) {
  return "my_".$name;
}, 10, 3);

过滤器：wplf_uploaded_file_path

如果您选择不将上传的文件添加到媒体库，您可以更改文件上传的路径。

add_filter('wplf_uploaded_file_path', function($name, $file, $id) {
  return $name.".userfile";
}, 10, 3);

插件

1.5版本公开了一个新的函数，wplf()。它简单地返回WP Libre Form类的实例。

这允许您将您的插件注册为WP Libre Form插件，从而允许您在需要时公开API和插件设置页面。

$wplf = wplf();
$plugin = new YourPlugin();

$wplf->plugins->register([
  "name" => "YourPlugin", // The name you wish to show on the WPLF plugin page. Willl also be used to access public methods in your plugin
  "description" => "What your plugin does in a sentence or two",
  "link" => "https://toyourplugin.com", // Plugin URL. Can be wordpress.org or pretty much any URL where you can download the plugin
  "version" => YOUR_PLUGIN_VERSION, // Define a constant containing your plugin version
  "instance" => $plugin, // Your plugin, instantiated. Users can access your public methods
  "settings_page" => [$plugin, "render_settings_page"], // Function that renders your settings page, or a string that contains the link to it. Leave empty to disable.
]);

如果您在名称中使用空格，您可以像这样访问插件实例

wplf()->plugins->{"您的插件"}->somePublicMethod()

JavaScript API

客户端回调

WP Libre Form支持使用window.wplf对象在表单提交后执行客户端回调。示例用法

window.wplf.successCallbacks.push(res => alert('Form submission success: ' + res.form_id));
window.wplf.errorCallbacks.push(() => alert('Form submission failed!'));

这些回调将按出现的顺序执行。

为了避免JavaScript运行得太早，请将wplf-form-js添加到您的队列依赖项

wp_enqueue_script( "themejs", "/path/to/theme.js", array( "wplf-form-js" ), ... );

否则，您可能会遇到类似“无法读取未定义属性的属性”的错误。

由REST API驱动的站点

您可以从REST API中获取表单。只需使用/wp/v2/wplf-form来检索表单。您可以使用过滤器获取单个表单

/wp/v2/wplf-form?slug=form-slug

然而，如果您从与WP站点URL不同的域发送表单，您可能会遇到CORS问题提交表单，您可以使用以下方法解决这个问题

add_action('wplf_pre_validate_submission', function() {
  $origin = $_SERVER['HTTP_ORIGIN'];
  header("Access-Control-Allow-Origin: $origin");
  header("Access-Control-Allow-Credentials: true");
});

请注意，上述代码片段会将您的表单提交对全世界开放。

如果您想的话，也可以使用“官方”的JS包。

window.ajax_object = {
  ajax_url: `${WP.url}/wp-admin/admin-ajax.php`,
  ajax_credentials: 'include', // different origin
  wplf_assets_dir: `${WP.url}/wp-content/plugins/wp-libre-form/assets`,
}

await new Promise((resolve, reject) => {
  const script = document.createElement('script')
  const timeout = setTimeout(reject, 30000)
  script.src = `${WP.url}/wp-content/plugins/wp-libre-form/assets/scripts/wplf-form.js`
  script.onload = (e) => {
    clearInterval(timeout)
    resolve()
  }

  document.body.appendChild(script)
})

多语言

您可以使用Polylang创建多语言表单。WPLF会在您使用特殊模板标记时注册并自动获取翻译。

示例

<input type="text" placeholder="{{ Test string }}" name="test">

您也可以禁用此功能，并创建自己的WPML中间件，如果您愿意的话。

add_filter( 'wplf_load_polylang' , __return_false );

向表单元素添加额外类

您可以使用短代码中的xclass属性添加自己的额外类以供CSS使用。

[libre-form id="1" xclass="extra"]

向表单元素添加额外属性

您可以通过将其添加到短代码轻松地向表单元素添加任何自定义属性

[libre-form id="1" data-custom-attr="contactme"]

该属性将按原样在<form>元素上呈现

<form class="libre-form libre-form-1" data-custom-attr="contactme">

从预定义的HTML模板导入表单

有时一个项目可能需要静态表单，这些表单不应在管理面板中进行编辑。

此插件允许您在项目源代码中定义HTML表单，并将它们导入特定表单的表单管理器中。

创建静态HTML模板

最简单的方法是创建一个HTML5文件并读取其内容。其他选项包括使用Twig来渲染HTML模板。

记住：WPLF将自动插入form标签，这意味着您只需要创建位于form标签内的标记。

将模板导入WPLF

创建完表单模板后，您需要通知WPLF。您可以使用wplf_import_html_template过滤器钩子为此目的

<?php

add_filter( 'wplf_import_html_template', function ( $template, $form_id ) {
    $some_form_id = 123;

    if ( $form_id === $some_form_id ) {
        // You can also render Twig templates and similar here
        return file_get_contents( '/path/to/template/file.html' );
    }

    return $template;
}, 10, 2 );

$template变量应是一个原始HTML字符串。如果将其设置为null，则不会导入任何模板。

在导入特定表单的模板后，该表单的编辑视图将设置为只读模式，这意味着您必须通过代码而不是在管理面板内编辑表单来修改静态HTML模板。

否则，表单应正常工作，这意味着您可以使用WPLF功能，就像以前一样。

anttiviljami / wp-libre-form

维护者

详细信息

README

功能

为什么？

试试看

屏幕截图

编辑表单

表单在默认的 Twentysixteen 主题中显示

提交视图

单个提交视图

安装

Composer 方法（首选）

传统方法

过滤器/操作 API

过滤器：wplf_validate_submission

表单特定钩子

示例：Google ReCaptcha 集成

操作：wplf_post_validate_submission

表单特定钩子

示例：向提交中的电子邮件发送感谢邮件

过滤器：wplf_disable_validate_additional_fields

表单特定钩子

过滤器：wplf_allowed_additional_form_fields

表单特定钩子

过滤器：wplf_dynamic_values

示例：新值

过滤器：wplf_uploaded_file_name

过滤器：wplf_uploaded_file_path

插件

JavaScript API

客户端回调

由REST API驱动的站点

多语言

向表单元素添加额外类

向表单元素添加额外属性

从预定义的HTML模板导入表单

创建静态HTML模板

将模板导入WPLF