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

要插入到页面中的设置-部分。此数组中的每个元素代表一个设置-部分。
有关 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()

注册设置页面。

选项部分

选项

id

部分的 ID。

部分的标题。

部分的描述。

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

fields

renderFunction

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

所需的能力

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

capability

选项字段

方法

register()

注册设置页面。

此字段的 ID。

选项

id

此字段的标题。

部分的标题。

type

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

所需的能力

capability

此字段显示给当前用户所需的能力。

renderFunction

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

sanitizeFunction

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

字段类型

常见选项

属性（数组）

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

defaultValue (mixed)

字段的默认值。

颜色

与常见选项相同。

日期

与常见选项相同。

电子邮件

与常见选项相同。

隐藏

与常见选项相同。

数字

与常见选项相同。

密码

与常见选项相同。

范围

与常见选项相同。

搜索

与常见选项相同。

多行文本框

与常见选项相同。

文本

与常见选项相同。

时间

与常见选项相同。

网址

与常见选项相同。

复选框

水平（true）

复选框的布局。如果要垂直排列复选框，则设置为false。

options ([])

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

复选框

text (string)

复选框的文本。

value (string)

复选框的值。

单选按钮

与复选框相同。

选择框

与复选框相同。

文件

maxFileSize (string)

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

isJson (bool)

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

媒体

button_text (string)

媒体上传按钮的文本。

media_uploader_title (string)

媒体上传器的标题。