README

使用 amarkal-ui 组件将设置页面添加到您的 WordPress 主题或插件中。

测试版本至: WordPress 4.8
依赖项: amarkal-core, amarkal-ui

概述

amarkal-settings 允许您根据 amarkal-ui 组件创建主题或插件的设置页面。设置页面将数据存储为数据库中的选项，并使用 AJAX 异步存储数据以改善用户体验。

安装

通过 Composer

如果您正在使用命令行

$ composer require askupa-software/amarkal-settings:dev-master

或者只需将以下内容添加到您的 composer.json 文件中

"require": {
     "askupa-software/amarkal-settings": "dev-master"
 }

然后运行以下命令

$ composer install

这将把包安装到目录 vendors/askupa-software/amarkal-settings 中。
现在您只需要包含 composer 自动加载器。

require_once 'path/to/vendor/autoload.php';

手动

从 github 下载 amarkal-core，amarkal-ui 和 amarkal-settings，并将它们包含到您的项目中。

require_once 'path/to/amarkal-core/bootstrap.php';
require_once 'path/to/amarkal-ui/bootstrap.php';
require_once 'path/to/amarkal-settings/bootstrap.php';

添加设置页面

设置页面是基于 amarkal-ui 的图形用户界面，为用户提供了方便地存储和检索主题/插件选项的途径。设置页面作为现有顶级菜单项的子页面显示在管理菜单中。

添加设置页面

以下示例显示了如何添加一个将在“工具”子菜单下可用的设置页面。

$page = amarkal_add_settings_page(array(
    'slug'         => 'my-settings-page',
    'parent_slug'  => 'tools.php', // The 'Tools' top level menu item slug
    'title'        => 'My Settings',
    'menu_title'   => 'My Settings'
));

现在您可以使用返回的实例添加设置字段。任何 Amarkal UI 组件都可以用作字段。

$page->add_field(array(
    'type'       => 'text',
    'default'    => 'Default text...',
    'title'      => 'My Text',
    'name'       => 'my-text'
));

向设置页面添加部分

您还可以将设置分为几个部分，以更好地组织它们并使用户更容易找到所需内容。

添加一个或多个部分时，将出现一个侧边栏，显示所有添加的部分名称，以及一个搜索框，用于在所有部分中搜索设置字段。

$page->add_section(array(
    'slug'         => 'my-section', // Must be unique within the list of sections for this page
    'title'        => 'My Section'
));

// Make sure to add a 'section' argument to fields to associate them with a given section
$page->add_field(array(
    'section'    => 'my-section',
    'type'       => 'text',
    'default'    => 'Default text...',
    'title'      => 'My Text',
    'name'       => 'my-text'
));

检索设置字段值

您可以通过字段名称和注册该字段的页面的 slug 来检索特定字段的值。

此方法首先检查数据库，如果没有找到任何内容，则返回字段的默认值。

$value = amarkal_get_settings_value('my-settings-page', 'my-text');

参考

amarkal_add_settings_page

添加设置页面。

amarkal_add_settings_page( $args )

此函数用于在 WordPress 管理区域创建设置页面。创建后，将在 'parent_slug' 中给出的父 slug 的子菜单中添加一个菜单项。

如果您想创建顶级设置页面，则需要使用 add_menu_page() 创建一个菜单页面，然后将设置页面的 'parent_slug' 设置为您创建的顶级菜单页面的 slug。

参数

• $args (数组) 页面参数列表。可接受的参数包括
  • parent_slug (字符串) 父菜单的缩略名（或标准WordPress管理页面的文件名）。
  • slug (字符串) 指代此菜单的缩略名（对于此菜单应该是唯一的）。
  • title (字符串) 当页面显示时在标题标签中显示的文本。
  • subtitle (字符串) 在页面顶部标题下方显示的文本。
  • menu_title (字符串) 用于菜单的文本。
  • capability (字符串) 此菜单显示给用户所需的权限。用于确定页面是否包含在菜单中。
  • footer_html (字符串) 指定要在设置页面页脚打印的HTML。
  • subfooter_html (字符串) 指定要在设置页面页脚下方打印的HTML。

返回值
(Amarkal\Settings\SettingsPage) 设置页面的实例

示例用法

amarkal_add_settings_page(array(
    'parent_slug'  => 'tools.php',
    'slug'         => 'my-settings-page',
    'title'        => 'My Settings',
    'menu_title'   => 'My Settings',
    'capability'   => 'manage_options'
));

amarkal_get_settings_page

获取设置页面的实例。

amarkal_get_settings_page( $slug )

此函数用于通过其缩略名获取已注册设置页面的实例。

参数

• slug (字符串) 设置页面的缩略名

返回值
(Amarkal\Settings\SettingsPage) 设置页面的实例

示例用法

$page = amarkal_get_settings_page('my-settings-page');

amarkal_get_settings_value

获取给定字段的值。

amarkal_get_settings_value( $slug, $field_name )

此函数用于检索给定字段的值。如果数据库中没有值，则返回默认值。此函数内部调用get_option()，将字段的默认值作为第二个参数提供。

参数

• $slug (字符串) 属于此字段的设置页面的缩略名
• $field_name (字符串) 字段的名称。

返回值
(混合型) 给定字段的值

示例用法

$value = amarkal_get_settings_value('my-settings','my-text');

amarkal_get_settings_values

获取给定设置页面作为数组的所有值。

amarkal_get_settings_values( $slug )

此函数用于检索给定设置页面的所有值。如果数据库中没有值，则返回默认值。此函数内部调用get_option()，将字段的默认值作为第二个参数提供。

参数

• $slug (字符串) 要检索值的设置页面的缩略名

返回值
(数组) 所有字段值的列表

示例用法

$values = amarkal_get_settings_values('my-settings');