README

专为开发者构建的 WordPress 表单解决方案。

为什么

作为一名开发者，我经常发现与 WordPress 中的各种表单插件合作是一件头疼的事情。主要痛点是这些表单生成大量深度嵌套的标记，这使得将这些表单的样式与设计匹配变得非常痛苦。

此外，有时设计需要对该标记的构建方式进行彻底的改变。虽然所有顶级表单插件都允许你更改该标记，但这通常并不直接。

我认为这些插件存在这个问题，是因为它们是为最终用户构建的，而不是为开发者构建的。你看，大多数表单插件都有一个拖放界面，允许非程序员创建表单。甚至复杂的表单！这真是太棒了。

但这实际上突出了这些插件从第一天起就不是为开发者构建的事实。它们是为高级用户构建的。

介绍 OMG 表单

这就是 OMG 表单发挥作用的地方。它从一开始就是为开发者而构建的，仅限开发者。但这是怎么做到的？你不需要为高级用户制作它吗？不。我相信

90% 的用户只需要一个或两个表单。
一旦网站上线，用户很少需要更改这些表单，或完全不需要。
即使用户确实想要一个新的表单，我可能还需要帮助他们，尽管他们技术上能够自己制作表单。

如果是这样，那么为什么我不使用一个将开发者体验放在首位的表单解决方案呢？这就是 OMG 表单发挥作用的地方。

目标

OMG 表单有一些核心目标，它致力于实现这些目标。

使开发者能够轻松覆盖默认字段模板以匹配其设计。
提供一个开发者 API，使开发者能够轻松定义表单及其字段，而无需在 WordPress 管理员中四处点击。此功能的次要目标是使创建表单的过程既快速又可重复。
使用插件模型，使开发者能够扩展核心 OMG 表单库以创建自己的插件。
OMG 表单最终将能够替换前端的所有表单相关需求，例如登录、注册、支付、前端文章创建、联系表单、订阅表单等。这将允许开发者为所有网站表单提供一致的标记和样式。

安装

OMG 表单可以通过 composer 安装。

$ composer require developwithwp/omg-forms

一旦安装了此包，如果您的项目尚未安装，则需要调用 Composer 的自动加载器。

if ( file_exists( get_template_directory() . '/vendor/autoload.php' ) ) {
    require( 'vendor/autoload.php' );
}

使用

现在您可以创建您的第一个表单了。OMG 表单提供了一个用于创建新表单的辅助方法 \OMGForms\Core\register_form()。

此函数期望一个类似于 register_post_type 期望的参数数组。

让我们从定义一个非常简单的表单开始。

$args = [
	'name'              =>  'contact-form',
	'redirect'          =>  false,
	'email'             =>  false,
	'form_type'         =>  'basic-form',
	'success_message'   =>  'Thank you!',
	'fields' => [
		[
			'slug'      =>   'your-name',
			'label'     =>   'Your Name',
			'type'      =>   'text',
			'required'  =>   false
		],
		[
			'slug'      =>  'email-address',
			'label'     =>  'Your Email',
			'type'      =>  'email',
			'required'  =>   true
		],
		[
			'slug'      =>   'company',
			'label'     =>   'Your Company',
			'type'      =>   'text',
			'required'  =>   false
		]
	]
];
\OMGForms\Core\register_form( $args );

如你所见，该表单在表单和字段级别都允许大量配置。

一旦您定义了一个表单，您可以通过调用 display_form 来渲染它。

echo \OMGForms\Core\display_form( 'my-form-name' );

或通过内置的短代码。

[omgform form="my-form-name"]

API

\OMGForms\Core\register_form([args])

args

name

类型：string (唯一名称) 默认：none

参数用于给表单赋予一个唯一名称。当需要显示表单时，您将使用此名称。表单名称需要是 snake_case 或 camelCase。

form_type

类型： 字符串/数组 (基本表单) 默认： 无

此设置告知OMG表单您正在创建哪种插件，或“表单类型”。例如，如果这是一个标准联系表单，那么您将使用基本插件，并将此参数设置为 basic-form。其他示例包括 authorize_net 和 constant-contact。

此设置也可以是一个表单类型的数组。当您需要一个表单具有多种用途时，这很有用。例如 [ 'authorize_net', 'basic-form' ]。此配置将导致您的表单通过Authorize.net向用户收费，同时将交易记录保存为基本表单提交。

redirect

类型： 布尔值 (true/false) 默认： 无

用于告知OMG表单在表单提交成功后是否应进行重定向。

redirect_to

类型： 字符串 (URL) 默认： 无

如果将 redirect 设置为 true，OMG表单将重定向用户到该页面。

email

类型： 布尔值 (true/false) 默认： 无

用于告知OMG表单在表单提交成功后是否应通过电子邮件通知某人。

email_to

类型： 字符串 (电子邮件地址) 默认： 无

如果将 email 设置为 true，OMG表单将在表单成功提交后向此人发送电子邮件。

success_message

类型： 布尔值 (true/false) 默认： 无

此消息将在表单提交成功后替换表单。当然，如果您已将表单设置为 重定向，则表单将直接重定向。

rest_api

类型： 布尔值 (true/false) 默认： false

此设置由插件作者使用，以告知OMG表单其插件是否应使用PHP API或JavaScript API。false = JS API 和 true = PHP API

再次强调，最终用户不需要担心此选项。由插件开发者处理此选项的自动设置。插件作者应 查阅钩子列表了解如何正确执行此操作。

classname

类型： 字符串 默认： 无

此参数允许您定义一个CSS类名，该类名将被添加到表单包装HTML元素中。

groups

类型： 数组 默认： 无

此参数允许您定义组。组用于将各种表单字段组合在一起。groups数组中的每个组本身也是一个数组，包含以下参数

id - 字符串 (snake_case) - 应该对每个表单是唯一的。
title - 字符串 - 允许您为表单的每个部分或组提供标题。
order - 数字 - OMG表单使用此值来确定在表单中放置该组的顺序。
class - 字符串 (可选) - 向组包装HTML元素添加CSS类。

组示例

'groups'    => [
            [
                'id'        => 'group_1',
                'title'     => esc_html__('Group One Title', 'text-domain'),
                'order'     => '1',
                'class'     => 'my-group-class'
            ],
            [
                'id'        => 'group_2',
                'title'     => esc_html__('Group Two Title', 'text-domain'),
                'order'     => '2'
            ]
        ]

fields

类型： 数组 默认： 无

fields参数将包含表单所需的全部字段。这是所有魔法发生的地方。fields数组中的每个字段本身也是一个数组，可能包含以下参数

slug - 字符串 (snake_case) (必需) - 应该对每个表单是唯一的。
label - 字符串 (必需) - 此文本将用于与此表单输入关联的HTML标签。
type - 字符串 (必需) - 告知OMG表单此字段应使用哪种类型的HTML表单字段。查看支持的字段列表，以查看OMG表单支持的字段类型。
必填 - bool (true/false) - 告诉OMG Forms该字段是否为必填项。如果设置为true，则会在HTML输入字段中添加一个必填属性。如果您选择在您自己的表单模板中省略此选项，则OMG Forms将在服务器端检查这些字段是否为空。
class - string (CSS类) - 将CSS类添加到表单包装元素。
placeholder - string - 将占位符添加到OMG Forms的HTML输出中。
template - string (文件名) - 告诉OMG Forms加载该字段类型的自定义模板的两种方法之一。有关更多信息，请参阅修改OMG表单字段模板。
group - string - 如果您的表单正在使用分组，则OMG Forms将使用此参数在显示表单时正确分组表单字段。
options - array - 如果该字段类型具有多个选项，则此参数用于列出这些选项。选项数组中的每个选项都是一个关联数组，应包含 value 和 label 键。
sanitize_cb - string - 此参数在服务器端用于清理字段的值。默认情况下，OMG Forms会清理所有字段值，但此参数提供了更细粒度的控制。

字段示例

'fields' => [
    [
        'slug'          =>  'my-slug',
        'type'          =>  'select',
        'label'         =>  esc_html__( 'My Select', 'text-domain'),
        'class'         =>  'my-select-class',
        'template'      =>  'my-select.php',
        'placeholder'   =>  esc_html__( 'Select Placeholder', 'text-domain' ),
        'options'       =>  [
            [
                'value' =>  'value_1',
                'label' =>  esc_html__( 'Value One', 'text-domain' )
            ],
            [
                'value' =>  'value_2',
                'label' =>  esc_html__( 'Value Two', 'text-domain' )
            ]
        ],
        'group'         => 'group_1'
    ],
    [
        'slug'          =>  'my-number',
        'type'          =>  'number',
        'label'         =>  esc_html__( 'My Label', 'text-domain'),
        'class'         =>  'my-class',
        'template'      =>  'my-template.php',
        'group'         =>  'group_1',
        'sanitize_cb'   =>  'absint'
    ]
]

支持的字段类型

复选框
email
隐藏
多选框
数字
密码
单选按钮
选择
提交
电话
文本
文本区域

自定义表单

OMG Forms内置了一个机制，可以轻松覆盖字段HTML。

有两种方法可以告诉OMG Forms在渲染特定字段类型时加载哪些模板。但是，无论您选择哪种选项，您首先需要在主题根目录中创建一个 forms 目录。

选项1 这是最好的选项。

为要覆盖的字段类型创建一个文件，并将其放置在 forms 文件夹中。(注意：请确保使用相同的名称。)因此，如果您想覆盖所有文本字段的模板，则创建一个名为 text.php 的字段。
作为入门，我们建议您复制OMG Forms附带模板中的代码。这将为您修改字段HTML标记提供一个良好的起点。

选项2 如果您需要根据表单/字段更改字段类型的标记，则此选项很有用。此选项有两个步骤

创建一个文件，并将其放置在 forms 文件夹中。您将希望给此文件一个独特的名称。例如，如果我们正在更改文本字段，我们不想将文件命名为 text.php。我们可以将其命名为类似 donate-text.php 的名称。
创建文件并在其中编写新文本字段的HTML标记后，您需要告诉表单使用此字段模板。您可以通过在注册表单时将文件名传递给 template 参数来实现这一点。*有关更多信息，请参阅字段API部分。

钩子列表

动作钩子

omg_form_before_form - 允许开发人员在表单HTML之前添加HTML标记。

omg_form_before_form_submit - 允许开发人员在HTML表单字段之后、提交按钮之前添加HTML标记。

omg_form_after_form - 允许开发人员在表单HTML之后添加HTML标记。

omg_form_validation - 提供了一种添加额外验证检查的方法。这些检查在OMG Forms页面加载时运行，用于通知开发人员他们可能遇到的表单问题。

omg-form-settings-hook - OMG 表单包含一个设置页面。此钩子允许插件作者向此页面添加额外的设置部分和字段。

筛选钩子

omg_forms_save_data - 这是插件作者创建插件的主要钩子，此钩子公开了经过清洗和验证的数据，以便插件可以使用这些数据执行其预期功能。

rest_allow_anonymous_entries 允许插件作者限制表单提交给登录用户。默认情况下，此选项设置为 true，意味着匿名用户可以提交表单。

omg_forms_sanitize_data - 允许插件作者在清洗过程中设置额外的清洗步骤。

omg-form-filter-field-args - 允许插件作者在表单注册时修改字段参数。当您需要确保某个表单以特定的字段参数设置时，这非常有用。

omg_form_filter_register_args - 与 omg-form-filter-field-args 类似，此过滤器允许您在表单创建后修改整个表单参数。例如，许多插件使用此过滤器强制特定类型的表单设置 rest_api => true。

路线图

为条件字段添加逻辑

developwithwp / omg-forms

维护者

详细信息

README

目录

为什么

介绍 OMG 表单

目标

安装

使用

API

\OMGForms\Core\register_form([args])

args

name

form_type

redirect

redirect_to

email

email_to

success_message

rest_api

classname

groups

组示例

fields

字段示例

支持的字段类型

自定义表单

钩子列表

动作钩子

筛选钩子

路线图