README

用于创建 WordPress 选项页面的简单框架。

#基本用法

以下是一个创建选项页面的示例。

use Laraish\Options\OptionsPage;

$optionsPage = new OptionsPage([
    'menuSlug'    => 'my_options_page',
    'menuTitle'   => 'My Options Page',
    'pageTitle'   => 'My Options Page',
    'iconUrl'     => 'dashicons-welcome-learn-more',
    'optionGroup' => 'my_options_page',
    'optionName'  => 'my_options',
    'capability'  => 'manage_categories',
    'sections'    => [
        [
            'id'          => 'section-id',
            'title'       => 'Section title',
            'description' => 'Section Description',
            'fields'      => [
                [
                    'id'          => 'my-avatar',
                    'type'        => 'media',
                    'title'       => 'Avatar',
                    'description' => 'Choose an image for your avatar.'
                ],
                [
                    'id'    => 'my-email',
                    'type'  => 'email',
                    'title' => 'E-mail',
                ],
                [
                    'id'         => 'my-nice-name',
                    'type'       => 'text',
                    'title'      => 'Nice name',
                    'attributes' => [
                        'placeholder' => 'your nice name',
                        'maxlength'   => 10,
                        'class'       => 'regular-text'
                    ],
                ],
                [
                    'id'    => 'my-description',
                    'type'  => 'textarea',
                    'title' => 'About Me',
                ],
            ]
        ]
    ],
    'helpTabs'    => [
        [
            'title'    => 'tab-1',
            'content'  => '<p>description here</p>',
        ],
        [
            'title'    => 'tab-2',
            'content'  => '<p>description here</p>',
        ]
    ],
    'scripts'     => ['https://unpkg.com/vue/dist/vue.js'],
    'styles'      => ['/my-css.css'],
]);
    
$optionsPage->register();

上面的示例代码将创建一个看起来像这样的选项页面

OptionsSection 和 OptionsField 的用法

您还可以将 'sections' 的值替换为一个 OptionsSection 对象的数组，并将 'fields' 的值替换为一个 OptionsField 对象的数组。

use Laraish\Options\OptionsPage;

/*------------------------------------*\
    # Field objects
\*------------------------------------*/

$avatarField = new OptionsField([
    'id'          => 'my-avatar',
    'type'        => 'media',
    'title'       => 'Avatar',
    'description' => 'Choose an image for your avatar.'
]);

$emailField = new OptionsField([
    'id'    => 'my-email',
    'type'  => 'email',
    'title' => 'E-mail',
]);

$niceNameField = new OptionsField([
    'id'         => 'my-nice-name',
    'type'       => 'text',
    'title'      => 'Nice name',
    'attributes' => [
        'placeholder' => 'your nice name',
        'maxlength'   => 10,
        'class'       => 'regular-text'
    ]
]);

$descriptionField = new OptionsField([
    'id'    => 'my-description',
    'type'  => 'textarea',
    'title' => 'About Me',
]);

$demoField = new OptionsField([
    'id'    => 'my-demo',
    'type'  => 'text',
    'title' => 'Demo text field',
]);



/*------------------------------------*\
    # Section object
\*------------------------------------*/

$demoSection = new OptionsSection([
    'id'          => 'section-id',
    'title'       => 'Section title',
    'description' => 'Section Description',
    'fields'      => [
        $demoField,
    ]
]);



/*------------------------------------*\
    # Page object
\*------------------------------------*/

$optionsPage = new OptionsPage([
    'menuSlug'    => 'my_options_page',
    'menuTitle'   => 'My Options Page',
    'pageTitle'   => 'My Options Page',
    'iconUrl'     => 'dashicons-welcome-learn-more',
    'optionGroup' => 'my_options_page',
    'optionName'  => 'my_options',
    'capability'  => 'manage_categories',
    'sections'    => [
        [
            'id'          => 'section-id',
            'title'       => 'Section title',
            'description' => 'Section Description',
            'fields'      => [
                $avatarField,
                $emailField,
                $niceNameField,
                $descriptionField,
            ]
        ],

        $demoSection,
    ],
    'helpTabs'    => [
        [
            'title'   => 'tab-1',
            'content' => '<p>description here</p>',
        ],
        [
            'title'   => 'tab-2',
            'content' => '<p>description here</p>',
        ]
    ],
    'scripts'     => ['https://unpkg.com/vue/dist/vue.js'],
    'styles'      => ['/my-css.css'],
]);


/*------------------------------------*\
    # register page/section/field
\*------------------------------------*/

// register page
$optionsPage->register();

// register a section to a page(Settings -> General)
$demoSection->register('general', 'demo-section-group', 'demo-section-options');

// register a field to a section of page(Settings -> General -> `default` section)
$demoField->register('general', 'default', 'demo-section-group', 'demo-section-options');

获取选项的值

您可以使用 OptionsRepository 获取选项的值。

use Laraish\Options\OptionsRepository;

// Get the value of 'my-nice-name' in 'my_options'.
// 'my_options' is the option name.
$myOptions = new OptionsRepository('my_options');
echo $myOptions->get('my-nice-name');
    
// also you can set the value by calling the set() method.
$myOptions->set('my_options','new value');

选项页面

选项

menuSlug

用于引用菜单的 slug 名称（对于此菜单应该是唯一的）。

menuTitle

用于菜单的文本。

pageTitle

当选择菜单时，在页面标题标签中显示的文本。

optionGroup

您希望在页面上使用的选项组。

optionName

您希望在页面上使用的选项名称。

capability

此菜单对用户显示所需的 能力。

position

此菜单在此菜单顺序中的位置。

iconUrl

用于菜单的图标 URL（或 图标名称）。

parent

如果您希望将页面作为顶级页面的子页面，请在此处设置顶级页面。

sections

要插入页面的设置-部分。此数组的每个元素代表一个设置-部分。
有关更多详细信息，请参阅 Options for OptionsSection。

renderFunction

用于输出页面内容的函数。
此函数检索两个参数；第一个是一个 OptionsPage 实例，第二个是一个 OptionsForm 实例。通过使用 OptionsForm 对象，您可以通过比硬编码更容易地创建表单输入元素。

以下是一个自定义选项页输出示例。

use Laraish\Options\OptionsPage;

$optionsPage = new OptionsPage([
    'menuSlug'       => 'my_options_page',
    'menuTitle'      => 'My Options Page',
    'pageTitle'      => 'My Options Page',
    'optionGroup'    => 'my_options_page',
    'optionName'     => 'my_options',
    'renderFunction' => function (OptionsPage $page, OptionsForm $form) {
        ?>
        <div class="wrap">
            <h1><?php echo $page->pageTitle(); ?></h1>
            <form action="options.php" method="post" enctype="multipart/form-data">
                <?php
                // output security fields for the registered setting "{{ $this->optionGroup }}"
                settings_fields($page->optionGroup());


                // output fields
                ?>
                <p><?php echo $form->email('email', ['attributes' => ['placeholder' => 'foo@example.com']]); ?></p>
                <p><?php echo $form->textarea('about-us'); ?></p>


                <?php
                // output save settings button
                submit_button();
                ?>
            </form>
        </div>
        <?php
    }
]);

helpTabs

要添加到页面的帮助选项卡。每个选项卡由一个 数组 表示。

scripts

要添加到页面的脚本。

styles

要添加到页面的样式。

方法

register()

注册设置页面。

OptionsSection

选项

id

部分的 ID。

title

部分的标题。

description

部分的描述。

renderFunction

填充部分所需内容的函数。此函数应输出其输出。

fields

部分的设置字段。有关更多详细信息，请参阅 Options for OptionsField。

capability

此部分对当前用户显示所需 能力。

方法

register()

注册设置页面。

OptionsField

选项

id

此字段的 ID。

title

此字段的标题。

type

字段类型。默认为 'text'。有关详细信息，请参阅字段类型。

capability

当前用户显示此字段所需的权限。

renderFunction

填充字段所需内容的函数。该函数应回显其输出。
此函数将接收一个包含两个元素的参数（数组）：field（选项字段）和form（选项表单）对象。

sanitizeFunction

在保存选项数据之前调用的清理函数。

字段类型

常用选项

attributes (数组)

字段元素的属性。
例如 ['placeholder'=> '输入您的姓名', 'class'=> 'foo bar baz']。

defaultValue (混合类型)

字段的默认值。

颜色

与常用选项相同。

日期

与常用选项相同。

电子邮件

与常用选项相同。

隐藏

与常用选项相同。

数字

与常用选项相同。

密码

与常用选项相同。

范围

与常用选项相同。

搜索

与常用选项相同。

多行文本框

与常用选项相同。

文本

与常用选项相同。

时间

与常用选项相同。

网址

与常用选项相同。

复选框

水平（true）

复选框的布局。如果您希望将复选框垂直排列，则设置为 false。

options ([])

选项数组。
例如 ['Red'=> '#f00', 'Green'=> '#0f0', 'Blue'=> '#00f']。

复选框

text (字符串)

复选框的文本。

value (字符串)

复选框的值。

单选按钮

与复选框相同。

选择

与复选框相同。

文件

maxFileSize (字符串)

文件的最大大小（字节）。

isJson (布尔值)

如果您将要上传 JSON 文件，则设置为 true。
默认值为 false。

媒体

button_text (字符串)

媒体上传按钮的文本。

media_uploader_title (字符串)

媒体上传器的标题。