README

一个简单的框架，用于创建WordPress选项页。

可以轻松用于LaraWelP主题。

#基本用法

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

use LaraWelP\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 的用法

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

use LaraWelP\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 LaraWelP\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');

OptionsPage

选项

menuSlug

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

menuTitle

用于菜单的文本。

pageTitle

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

optionGroup

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

optionName

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

capability

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

position

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

iconUrl

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

parent

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

sections

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

renderFunction

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

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

use LaraWelP\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。

部分标题

部分标题。

description

部分描述。

renderFunction

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

fields

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

capability

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

方法

register()

注册设置页面。

OptionsField

选项

id

该字段的ID。

部分标题

该字段的标题。

类型

字段的类型。默认为 'text'。详细信息请见字段类型。

capability

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

renderFunction

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

sanitizeFunction

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

字段类型

常见选项

属性（数组）

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

defaultValue（混合型）

字段的默认值。

颜色

与常见选项相同。

日期

与常见选项相同。

电子邮件

与常见选项相同。

隐藏

与常见选项相同。

数字

与常见选项相同。

密码

与常见选项相同。

范围

与常见选项相同。

搜索

与常见选项相同。

多行文本框

与常见选项相同。

文本

与常见选项相同。

时间

与常见选项相同。

网址

与常见选项相同。

复选框

水平（true）

复选框的布局。如果您想垂直放置复选框，请设置为 false。

options（[]）

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

复选框

文本（字符串）

复选框的文本。

值（字符串）

复选框的值。

单选按钮

与复选框相同。

选择

与复选框相同。

文件

maxFileSize（字符串）

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

isJson（布尔型）

如果您要上传json文件，请设置为 true。
默认值为 false。

媒体

button_text（字符串）

媒体上传按钮的文本。

media_uploader_title（字符串）

媒体上传的标题。