README

一个用于在WordPress设置页面渲染表单字段的包。

你可能需要一个带有表单和字段的设置页面，并且每次创建自定义插件时都必须渲染字段。

也许，你已经有一些生成表单字段的代码片段，否则这个包就是为你准备的。

安装

您可以通过composer安装此包

composer require roelmagdaleno/wp-settings-page-fields

用法

每个受支持的表单元素都扩展了Roel\WP\Settings\Element类，并必须使用相同的构造函数实例化

<?php

$element = new Element( $id, $settings, $option_name );

以下是支持的参数

• $id：表单元素的id。使用id()方法获取id。
• $settings：表单元素的设置（一些表单元素有特定的设置）。
• $option_name：存储值的数据库选项名称。

WordPress

要使用此包在您的设置页面中注册和渲染表单元素，您可以使用

<?php

use Roel\WP\Settings\Elements\{
    Checkbox,
    Text,
};

$settings = array(
    new Checkbox( 'allow-user', array(
        'label'       => 'Allow user?',
        'description' => 'Allow user to do current action.',
    ), 'rmr_settings' ),
    new Text( 'api-key', array(
        'label'       => 'API Key',
        'description' => 'Insert the API Key.',
    ), 'rmr_settings' ),
);

foreach ( $settings as $setting ) {
    add_settings_field(
        $setting->id(),
        $setting->label(),
        array( $setting, 'print' ),
        'your-page'
    );
}

请记住将array( $setting, 'print' )作为回调添加以渲染设置字段。变量$setting是一个Roel\WP\Settings\Element实例。

渲染

这就是如何创建表单元素实例并渲染HTML的方法

使用render方法

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text->render();

使用print方法

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

$text->print();

直接使用echo到实例化的类

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text;

属性

name属性

每个表单元素都包含一个name属性。此属性将用于将当前元素的值分配给$_POST变量，因此您可以像将其插入数据库一样管理该值。

name属性值是通过使用option_name和id生成的。所以，在下一个示例中

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text->render();

name属性将是

<input type="text" name="rmr_settings[api-key]" />

然后，在PHP中，您将像这样访问该输入的值

$_POST['rmr_settings'] = array(
    'api-key' => 'my-api-key',
);

HTML属性

您可以为您的表单元素添加HTML属性

<?php

use Roel\WP\Settings\Elements\Text;

$settings = array(
    'label'       => 'API Key',
    'description' => 'Insert your API Key in this form field.',
    'attributes'  => array(
        'data-value'  => 'value',
        'data-custom' => 'custom',
        'oninput'     => 'myFunction(\'myValue'\)'
    ),
);

$text = new Text( 'api-key', $settings, 'rmr_settings' );

echo $text->render();

组

看看这个例子

<?php

use Roel\WP\Settings\Elements\{
    Checkbox,
    Text,
};

$settings = array(
    new Checkbox( 'allow-user', array(
        'label'       => 'Allow user?',
        'description' => 'Allow user to do current action.',
    ), 'rmr_settings' ),
    new Checkbox( 'allow-admin', array(
        'label'       => 'Allow admin?',
        'description' => 'Allow admin to do current action.',
    ), 'rmr_settings' ),
    new Text( 'api-key', array(
        'label'       => 'API Key',
        'description' => 'Insert the API Key.',
    ), 'rmr_settings' ),
);

foreach ( $settings as $setting ) {
    add_settings_field(
        $setting->id(),
        $setting->label(),
        array( $setting, 'print' ),
        'your-page'
    );
}

您看到rmr_settings选项名重复吗？现在想象一下，在同一个页面上添加超过10个设置。对于这种情况，您可以使用Roel\WP\Settings\Group类。

实例接受两个参数

• $elements（数组）：要分组的元素。
• $option_name（字符串）：每个元素的选项名称。

传递的选项名称将被设置到每个传递的表单元素。

<?php

use Roel\WP\Settings\Group;
use Roel\WP\Settings\Elements\{
    Checkbox,
    Text,
};

$elements = array(
    new Checkbox( 'allow-user', array(
        'label'       => 'Allow user?',
        'description' => 'Allow user to do current action.',
    ) ),
    new Checkbox( 'allow-admin', array(
        'label'       => 'Allow admin?',
        'description' => 'Allow admin to do current action.',
    ) ),
    new Text( 'api-key', array(
        'label'       => 'API Key',
        'description' => 'Insert the API Key.',
    ) ),
);

$group = new Group( $elements, 'rmr_settings' );

foreach ( $group->elements() as $element ) {
    add_settings_field(
        $element->id(),
        $element->label(),
        array( $element, 'print' ),
        'your-page'
    );
}

在声明了带有所需参数的Group类之后，您可以使用elements()方法获取元素，这样您就可以循环和渲染它们。

设置

请参阅Wiki部分中的可用设置和更多信息。

过滤器

每个表单元素都有两个过滤器来更改HTML输出

• 更改所有已注册元素的HTML输出。
• 更改特定元素的HTML输出。

请参阅Wiki部分中的所有表单元素的过滤器和其他信息。

表单元素

以下是到目前为止支持的表单元素

• 复选框
• 隐藏
• 数字
• 单选按钮
• 下拉列表
• 文本
• 文本区域