wordpress添加theme option(step by step)

Wayne Shen

首先在主题文件夹创建inc,文件夹,创建两个文件,一个theme_functions,php(可选),一个wlk_theme_options.php.

第一步我们首先要注册admin page.首先注册的是一级的admin page,也就是menu page. 用到的函数是add_menu_page()。函数用法如下:

add_menu_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', string $icon_url = '', int $position = null )

具体参数为:第一个是页面点进去显示在标题栏上的标题,第二个显示为在左侧管理菜单栏上显示的名称(较短,因为空间不够),第三个是权限或者生产力,wordpress专门有个学问叫做Roles and Capabilities,就是每个角色能做什么。具体链接在这里,这里我们用到的一般都是manage_options的capibility.第四个是页面的slug,也就是类似于页面的id,唯一识别码。在最后会以admin.php?page=wlk_admin_page这种显示。第五个是callback函数,也就是你在页面要呈现的内容,通常这个函数是由表格构成的,可以单独创建一个wp_custom_form.php之类的文件创建表格然后在这个管理页面进行require.下面一个是dashicon,可以直接粘贴wordpress的dashicon代码,也可以进行自定义的icon。最后一个函数的位置是position,就是你要在菜单栏哪个位置展示。数值越低越早展示。一般默认。

注册一级admin page的样例如下:

function wlk_register_admin_pages() {

  // $page_title, $menu_title, $capability, $menu_slug, '', null
  add_menu_page( 'wlk Theme Options','Options','manage_options','wlk_admin_page','wlk_create_admin_page','dashicons-admin-network' );

  add_action('admin_init','wlk_register_admin_fields');  
}
add_action('admin_menu','wlk_register_admin_pages');

function wlk_create_admin_page() {
  require_once get_template_directory() . '/inc/templates/wlk_admin_form.php';
}

function wlk_register_admin_fields() {

}

这样会在左侧创建一个菜单名字为Options的按钮,点进去就是你可以进行下一步操作的主题或者插件选项设置。创建好页面之后我们要进行的是注册选项的字段。通过add_action(‘admin_init’,’wlk_register_admin_fields’);钩子来进行注册,通过函数wlk_register_admin_fields来添加注册内容。

下面我们添加二级的管理页面。这个函数是:

add_submenu_page( string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null )

属性是一样的操作。只不过第一个参数变成了父级管理页面的slug,也就是我们上文提到的wlk_admin_page。然后子级的管理页面不需要icon。

当创建子级管理页面的时候,你会发现上面多了一个和父级管理页面一样的子级页面,这个是wordpress默认创建的。所以我们要repeat 一样的settings,所以第一个子级的页面title跟父级的要设置一样,menu的name可以不变,slug也要变成和父级页面一样,因为我们要一样的页面来作为子级页面,所以callback函数也是一样。

简而言之就是设置第一个子级页面跟父级页面一样的选项,点击父级选项按钮的时候就直接跳转到子级选项。

theme option以下几项缺一不可:

先注册admin page,然后注册field section, 然后resgister fields,然后add settings field.

Settings Api

Setting api 允许半自动管理包含设置表格的管理页。它允许您定义设置页、这些页中的节以及节中的字段。新的setting page可以添加setting section和setting fields,存在的setting page也可以添加新的setting section和setting fields进去。

settings api的优势:

  • Handling Form Submissions – Let WordPress handle retrieving and storing your $_POST submissions.
  • Include Security Measures – You get extra security measures such as nonces, etc. for free.
  • Sanitizing Data – You get access to the same methods that the rest of WordPress uses for ensuring strings are safe to use.

我们先在注册管理页面的函数里添加钩子,add_action(‘admin_init’,’wlk_register_admin_fields’);,然后创建对应函数,

function wlk_register_admin_fields() {
register_setting( ‘wlk-setting-group’,’first_name’ ); //创建setting group, 第二个参数是Input里面的name值。
}并首先添加setting,用到register_setting() 函数。

register_setting函数用法是:register_setting( string $option_group, string $option_name, array $args = array() );

第一个参数option group名字:

$option_group

(string) (Required) A settings group name. Should correspond to an allowed option key name. Default allowed option key names include ‘general’, ‘discussion’, ‘media’, ‘reading’, ‘writing’, ‘misc’, ‘options’, and ‘privacy’. 与允许的option值名必须对应。是唯一的名字我们希望保存这些集合

第二个是

$option_name

(string) (Required) The name of an option to sanitize and save.是option的名字,用来过滤和保存。是pacific single option name.

第三个是数组,来描述和进行函数的callback. 用法是:

$args

(array) (Optional) Data used to describe the setting when registered.

  • ‘type’
    (string) The type of data associated with this setting. Valid values are ‘string’, ‘boolean’, ‘integer’, ‘number’, ‘array’, and ‘object’.
  • ‘description’
    (string) A description of the data attached to this setting.
  • ‘sanitize_callback’
    (callable) A callback function that sanitizes the option’s value.
  • ‘show_in_rest’
    (bool|array) Whether data associated with this setting should be included in the REST API. When registering complex settings, this argument may optionally be an array with a ‘schema’ key.
  • ‘default’
    (mixed) Default value when calling get_option().

Default value: array().使用的时候基本保存默认

theme options 注册fields由register setting和add_settings_field组成。register注册option_group并添加option到表。add_settings_field添加新的字段区域到设置页的setion里,同时通过callback函数input里面的name值和注册的option相对应,来进行数据的写入。

Theme form 的代码:

<h1><?php __('设置主题选项'); ?></h1>

<?php settings_errors(); ?>

<form action="options.php" method="post">
	<?php settings_fields( 'dom-fields-group' ); ?>
	<?php do_settings_sections( 'dom_admin_page' ); ?>
	<?php submit_button(); ?>
</form>