oomphinc/wp-forms-api

WordPress中的Drupal风格API，用于创建和编辑表单

维护者

详细信息

github.com/oomphinc/WP-Forms-API

主页

源代码

问题

安装数: 1,069

依赖项: 0

建议者: 0

安全性: 0

星标: 56

关注者: 16

分支: 11

开放问题: 15

类型:wordpress-muplugin

v1.3 2017-03-07 17:14 UTC

Requires

Requires (Dev)

MIT e44a6fe30f9c4247c3e1da55178c26d760298097

apiwordpressFormsfieldswpelements

This package is auto-updated.

Last update: 2024-09-07 15:28:14 UTC

README

WordPress中的Drupal风格API，用于创建和处理表单。

提供由静态方法组成的 WP_Forms_API 类，可以用于渲染由任意数据结构定义的表单。您还可以将那些表单提交的结果处理成一组连贯的值，平滑处理数据类型、验证（进行中：#35）、条件逻辑，并允许通过过滤器在WordPress中功能性地集成。

为什么？

在WordPress中编写和管理管理表单是一件非常痛苦的事情，而数据驱动的方案则更加灵活和类似Drupal。WordPress倾向于使用字面量标记模板来实现表单和其他复杂的标记结构，但这些结构可能非常难以管理和更新。我还没有看到任何其他类似的开发项目，能够将Drupal的一些最佳想法引入WordPress，从而为开发者和客户双方提供快速开发工具。

由数据集而不是模板和标记驱动的表单，在渲染的表单标记中创建了一个非常通用、可预测和可定制的结构，并且易于管理和更新表单结构。

还提供了更多特定于WordPress的表单控件，例如“选择图片”或“选择文章”字段，这可以用极少的代码实现强大的管理表单。

概述

有两个基本元素

'form'，它是一个任何关联数组。

'element'，一个至少包含 #type 和 #key 键的表单。

构建

此项目使用NPM管理依赖项，使用gulp构建。使用 npm install 安装所有依赖项。使用 gulp 构建 CSS 文件。

API快速入门

/**
 * Define a form called 'my-form' which contains an address1 and address2
 * input, and another form called 'citystatezip' which contains three input
 * elements: city, state, zipcode
 */
$form = array(
  '#id' => 'my-form',

  'address1' => array(
    '#label' => "Street",
    '#type' => 'text',
    '#placeholder' => "Line 1",
  ),
  'address2' => array(
    '#type' => 'text',
    '#placeholder' => "Line 2"
  ),

  'citystatezip' => array(
    'city' => array(
      '#type' => 'text',
      '#label' => "City",
      '#placeholder' => "Boston",
      '#size' => 20
    ),
    'state' => array(
      '#type' => 'text',
      '#label' => "State",
      '#placeholder' => "MA",
      '#size' => 4,
    ),
    'zipcode' => array(
      '#type' => 'text',
      '#label' => "ZIP",
      '#placeholder' => "01011",
      '#size' => 7
    )
  ),
);

/**
 * Define the values for this form
 */
$values = array(
  'city' => "Omaha",
  'state' => "Nebraska"
);

/**
 * You can render the form in whatever context you'd like: Front-end, meta boxes,
 * wherever. Does not render containing <form> elements: the form is expected to be
 * defined at this point.
 */
echo WP_Forms_API::render_form( $form, $values );

/**
 * Now I want to save the elements from this form. Each element gets an input
 * with the same name as its '#key' which defaults to its array key.
 */
add_action( 'save_post', function( $post ) use ( $form ) {
  $post = get_post( $post );

  // Fill in posted values for this form in $values. Every key
  // in $values is guaranteed to be defined for every input in defined in $form.
  WP_Forms_API::process_form( $form, $values );

  update_post_meta( $post->ID, 'city', $values['city'] );
} )

参考

表单和元素由简单的关联数组表示。

表单是一个顶级对象，但元素也是一个表单。

特殊键以 '#' 开头，其他所有键都解释为元素本身。

包含 #type 键的任何表单都被视为输入元素，并将创建相应的命名表单输入。

函数

此插件实现了一个 WP_Forms_API 类，它提供了以下静态方法

  • WP_Forms_API::render_form( $form, &$values )

递归地使用 $values 中的值渲染表单，并返回其标记。这是您将需要的首要渲染函数。在渲染之前应用 wp_form 过滤器。

$form - (数组) - 要渲染的表单。

$values - (数组引用) - 此表单中元素的值。虽然表单结构是嵌套和层级的，但值结构是平的（大多数情况：请参阅“复合”值）。

$top - (可选数组) - 顶级表单。

  • WP_Forms_API::render_element( $element, &$values ) - 渲染单个元素。

渲染一个元素及其任何子表单，返回渲染的标记。您必须在元素中指定一个标量 #key，否则将抛出异常。

$form - (数组) - 要渲染的表单。

$values - (数组引用) - 此表单中元素的值。虽然表单结构是嵌套和层级的，但值结构是平的（大多数情况：请参阅“复合”值）。

在渲染之前应用 wp_form_element 过滤器到元素。

  • WP_Forms_API::make_tag( $tagname, $attrs, $content = null )

创建并返回单个HTML标签。

$tagname - (字符串) - 要输出的HTML标签名称。如果为空，则不执行任何操作。

$attrs - (数组) - 此标签的HTML属性关联数组。

$content - (字符串|false) - 此标签的内容（如有）。如果为null，则输出自闭合标签。如果为false，则该标签不会闭合。

  • WP_Forms_API::get_elements( $form ) - 初始化并返回表单的所有元素。

$form - (数组) 从中提取元素的表单。

使用此函数从表单中获取初始化的子元素，跳过所有特殊键。

  • WP_Forms_API::process_form( $form, &$values, $input = null ) - 处理提交的表单并提取提交的值。

$form - (数组) - 要处理的表单。

$values - (数组引用) - 将结果值保存到该结构中。

$input - (数组，可选) - 输入数组。默认为$_POST。

过滤器

在渲染之前，表单和表单元素分别通过wp_form和wp_form_element WP过滤器进行运行。这给开发者提供了定义特殊输入标签（通过在#tag属性中设置）以及更新或隐藏渲染时的元素的能力。

wp_form过滤器接收$form, $top作为参数，其中$form是当前表单节点，$top是顶级表单。您可以使用#id键来识别特定表单，但也可以使用以#开头的任何任意键。

wp_form_element过滤器接收$element, $form

表单

表单中的所有键都是可选的。

  • #id (字符串)

此表单的引用ID，用于过滤输出。当定义时，元素在渲染前会通过过滤器wp_form_element_{$form_id}-{$element_key}运行，因此可以进行修改、删除或其他操作。

  • #label (字符串)

此表单或元素的标签。

  • #class (数组)

在class属性中的CSS类。

  • #attrs (数组)

用于渲染容器的标签的属性。如果指定了class键，则它会在#class中的类之前添加。

  • #form (数组)

顶级表单。默认为表单本身。

  • #container (字符串)

此表单或元素的容器标签名称。默认为div。

  • #container_classes (数组)

要添加到容器元素的CSS类数组。

元素

元素是一个包含至少一个#type键的关联数组。元素可以具有表单的任何属性，以及以下属性

  • #type (字符串)

当存在时，表示元素是输入元素。值

  • 'text' – 普通文本输入。

  • 'select' - 选择框。需要#options键。

  • 'checkbox' - 布尔值。

  • 'textarea' - 文本区域。

  • 'multiple' - 值集合。

  • 'composite' - 作为数组在#key中发布的组合值。

  • 'image' - 来自媒体库的图像

  • 'post_select' - 帖子

  • 任何其他值都将作为文本输入渲染。您可以使用自定义类型以及wp_form_element过滤器来定义输入标签类型

  • #key (字符串)

此元素的键。用于创建默认表单元素的name属性和类的slug。

  • #placeholder (字符串)

要在表单元素中使用的占位符。适用于'text'和'textarea'类型。

  • #options (数组)

此输入元素的选项，如'value' => "Label"。仅适用于选择。

  • #required (bool)

键是否必需。（待办事项：目前仅影响'select'类型元素。）

  • #name (字符串，可选)

输入元素名称 - 默认为 #key。

  • #slug（字符串，可选）

CSS元素名称 - 默认为 #key。

  • #size（整数）

元素的大小。

  • #multiple（数组）

当 $form['#type'] == 'multiple' 时必需。定义另一个表单，其值将被收集到这个元素的数组中。

  • #add_link（字符串）

当使用 #multiple 时，显示“添加项目”按钮的文本。

  • #remove_link（字符串）

当使用 #multiple 时，显示“移除项目”按钮的文本。

  • #post_type（字符串）

当 #type = 'post_select' 时，用于搜索的有效文章类型的空间分隔列表。

  • #conditional（数组）

根据元素的值显示或隐藏元素。请注意，条件逻辑仅适用于会触发JavaScript改变事件的输入类型（例如选择菜单、复选框、单选按钮等）。

  • element - 应对更改此元素值的元素的jQuery选择器（例如 #element-id、.element-class 等）。
  • action - 对元素执行的操作。可以是 'show' 或 'hide'。
  • value - 如果输入的值与此值相同，则显示|隐藏目标元素。

可过滤的元素属性

这些属性应仅在 wp_form_element 过滤器中修改。

  • #content（字符串）

要放入输入标签中的任何内容。如果提供了此值，将附加从渲染标签获得的附加内容。仅适用于 'select' 和 'checkbox' 类型，但如果有提供内容，将渲染具有此内容标签。

  • #tag（字符串）

用于输入的实际标签名称。

渲染的输入名称

使用此API渲染的表单输入元素接收在 #name 中指定的名称，默认为其 #key。

对于 '#type' => 'composite'，当前元素下表单树中的任何元素都将接收导致提交关联数组的名称。例如，以下表单

$form = array(
  'address' => array(
    '#type' => 'composite',
    'city' => array( '#type' => 'text', '#label' => "City" ),
    'state' => array( '#type' => 'text', '#label' => "State" ),
    'zip' => array( '#type' => 'text', '#label' => "ZIP" ),
  )
);

将产生三个名为 address[city]、address[state] 和 address[zip] 的输入元素。

对于 '#type' => 'multiple'，必须指定一个 #multiple 键，它是一个将值收集到索引数组的表单。例如，以下表单

$form = array(
  'favorites' => array(
    '#type' => 'multiple',
    '#multiple' => array(
      'name' => array( '#type' => 'text', '#label' => "Favorite:" )
    )
  )
);

将产生一个具有多个值的表单，具有名为 favorites[0][name]、favorites[1][name] 等等的输入，对于每个提交的值。表单将始终渲染至少一个空输入。当使用多值表单元素时，将队列脚本处理 wp-forms，它管理添加/删除多个元素的控制。

通常，在使用 process_form() 时，名称对您来说并不重要，但了解调用 process_form() 后 $values 的结构很重要。

处理

使用方法 WP_Forms_API::process_form( $form, $values ) 将 $values 填充为 $form 中定义的命名元素。默认情况下将使用 $_POST 中的值，但您可以通过传递一个可选的第三个参数来获取元素值。

wp_form_process 过滤器以参数 $form, &$values, &$input 被调用，允许在渲染之前修改表单或子表单。您可以在 $form['#form'] 中访问顶层表单。

wp_form_process_element 过滤器以参数 $element, &$values, &$input 被调用，允许在处理之前修改单个元素。您可以在 $element['#form'] 中访问此元素所属的子表单，以及在 $element['#form']['#form'] 中访问顶层表单。

在这些过滤器中，&$values 和 &$input 可能指的是原始 $values 和 $input 数组的子数组。要访问这些结构的顶层，对于表单，请访问 $form['#form']['#values'] 和 $form['#form']['#input']，对于元素，请访问 $element['#form']['#form']['#values'] 和 $element['#form']['#form']['#input']。

CSS

元素别名是由父元素链构建的，用 '-' 分隔。这些别名用于形成元素的 CSS 类名，以便进行针对性样式化。

表单会获得以下类：.wp-form，如果 #id 已定义，则为 .wp-form-{$form['#id']}。它们还会接收属性 id="{$element['#id']}"

每个元素都在标签为 #container 的容器元素中渲染，其类由 #container_classes 定义。容器元素还会添加以下类：.wp-form-element .wp-form-element-{$slug}。

每个输入元素都使用标签 $element['#tag'] 和 $element['#attrs'] 中的属性进行渲染。这些值可以使用 wp_form_element 过滤器针对每个元素进行修改。默认类为 .wp-form-input 和 .wp-form-input-{$element['#slug']}。

标签接收类 .wp-form-label 和 .wp-form-label-{$element['#slug']}。

示例

一个示例表单可能看起来如下，它捕获一个姓名和一个邮编

<form method="post" action="/my/form/handler">
<?php
	$form = array(
		'name' => array(
			'#type' => 'text',
			'#label' => "Enter your name:",
			'#placeholder' => "Charlie Brown"
		),
		'zipcode' => array(
			'#type' => 'text',
			'#label' => "Enter your ZIP code:",
			'#placeholder' => "90210",
			'#size' => 5
		),
		'save' => array(
			'#type' => 'submit',
			'#value' => "Save Information"
		)
	);

	echo WP_Forms_API::render_form( $form, $input );
?>
</form>

此表单将显示两个输入字段：'name' 和 'zipcode'，以及一个标记为 "保存信息" 的提交按钮。

您可以使用 WP_Forms_API::process_form() 处理此表单

<!-- Then process the form -->
<?php
	WP_Forms_API::process_form( $form, $values );
?>

<p>
	Your name is: <?php echo esc_html( $form['name'] ); ?>
</p>

<p>
	Your ZIP is: <?php echo esc_html( $form['zipcode'] ); ?>
</p>

测试

此软件包包含 PHP 单元测试。要开始测试，请安装 composer 依赖关系和测试数据库

$ composer install

$ bin/install-wp-tests.sh <db-name> <db-user> <db-pass>

然后，您可以简单地通过执行 bin/run-tests 来执行测试。

请帮助！

此项目只是我对另一个项目所做工作的概括。我在 WordPress 中构建表单已经花费了很多令人沮丧的时间，我知道一定有更简单的方法。这并不声称与 Drupal 表单 API 相当强大，但也许有一天，在你的帮助下，它可能可以！

由 Oomph, Inc 提供的插件

Oomph 是一家全面服务的数字设计和工程公司，帮助高端品牌和媒体公司提供大规模内容互动解决方案。 http://oomphinc.com/