WordPress中添加自定义参数(setting API)

在开发wordpress插件中，向wordpress数据库中添加参数是必须的，不然我们需要另外的方式来处理这些参数。wordpress中提供了一些setting API 来让你在现有的setting页面中添加自定义参数。

首先看看wordpress的控制面板(dashboard)中，有一栏是设置相关的，这些设置也分为几个页，缺省的有“常规选项”，“撰写”，“阅读”，“讨论”，等等，如果你安装了一些插件，有些插件会自己带一个设置页面。

这篇文章介绍下如何向这些缺省页中添加参数。

第一步 添加组

假定我们要在阅读页面中添加一些参数，那么首先需要向这个页面添加一个组（section），添加组的函数是
add_settings_section($id, $title, $callback, $page)

 
其中
$id为组的名字。
$title是在页面上显示的组的名字。
$callback是显示该组内容的函数，这个函数需要显示他的输出。
$page是setting页的名字，也就是上面提到的几个设置页，他们对应的名字分别为（general,reading,writing,media等等）

add_settings_section(‘eg_setting_section’,
 ‘Example settings section in reading’,
 ‘eg_setting_section_callback_function’,
 ‘reading’);

function eg_setting_section_callback_function() {
 echo ‘

following is our settings section

';
}

这个调用将在reading页面添加一个section，该section的id为eg_setting_section,标题为‘Example settings section in reading’,同时指定了一个callback函数，添加的页面是reading。
下面就是callback函数的定义，只是简单的显示了一段话。

第二步 添加变量

这样就向reading页面中添加了一个设置组，但是什么自定一变量都还没有加进去。
要在这个组中添加一个变量，需要调用函数
add_settings_field($id, $title, $callback, $page, $section = ‘default’, $args = array())

其中
$id为变量名字
$title为变量在页面上显示的名字
$callback为显示该变量
$page 页面，同上面的函数
$section 组id ，也就是上面提到的eg_setting_section。
$args 额外的参数

下面是实例：
add_settings_field(‘eg_setting_name’,
 ‘Example setting Name’,
 ‘eg_setting_callback_function’,
 ‘reading’,
 ‘eg_setting_section’);

function eg_setting_callback_function() {
 echo ‘ Explanation text';
}

其中，添加的变量名为eg_setting_name，显示在页面上的名字为“Example setting Name” ，callback函数为eg_setting_callback_function ，页面为reading，section为上面添加的eg_setting_section。

再看这个回调(callback)函数
显示的是一个input box，名字为变量名，然后是input box的一些属性，最后是该变量名的解释。
注意这里调用了一个函数
checked(1,get_option(‘eg_setting_name’,false))
关于这个函数，可以参考下面这两种等价的写法
/>

/>

后面可以跟第三个可选参数，含义为
whether the function echoes “checked” when the two values are identical  Note: whether this is true or false, the appropriate value will be returned.
这里应该没有第三个参数，我怀疑原文这里的代码有点问题。所以把false作为get_option的参数，而不是checked的参数。

关于get_option函数，他用来从数据库中获得一个参数的值，通常用法为
 
其中’option name’ 为参数名字，$default 意思是如果这个参数数据库中没有，缺省的返回值。

第三步 注册变量

好，到现在我们在reading页面添加了一个section，并且为这个section添加了一个变量，接下来就需要注册这个变量，然后wordpress后台就会在我们改动这个变量值是自动更新数据库。
register_setting( $option_group, $option_name, $sanitize_callback )

要注册上面的那个变量，调用为
register_setting(‘reading’,’eg_setting_name’);

最后需要把添加section，变量，注册变量的部分做成一个函数，并且把这个函数添加到admin_init action中，并且把这个php做成一个插件，启用这个插件，就可以在reading页面中看到这个变量了。

以下是完整的代码：

01
02  // ------------------------------------------------------------------
03  // Add all your sections, fields and settings during admin_init
04  // ------------------------------------------------------------------
05  //
06
07  function eg_settings_api_init() {
08   // Add the section to reading settings so we can add our
09   // fields to it
10   add_settings_section('eg_setting_section',
11   'Example settings section in reading',
12   'eg_setting_section_callback_function',
13   'reading');
14
15   // Add the field with the names and function to use for our new
16   // settings, put it in our new section
17   add_settings_field('eg_setting_name',
18   'Example setting Name',
19   'eg_setting_callback_function',
20   'reading',
21   'eg_setting_section');
22
23   // Register our setting so that $_POST handling is done for us and
24   // our callback function just has to echo the
25   register_setting('reading','eg_setting_name');
26  }// eg_settings_api_init()
27
28  add_action('admin_init', 'eg_settings_api_init');
29
30
31  // ------------------------------------------------------------------
32  // Settings section callback function
33  // ------------------------------------------------------------------
34  //
35  // This function is needed if we added a new section. This function
36  // will be run at the start of our section
37  //
38
39  function eg_setting_section_callback_function() {
40   echo 'Intro text for our settings section';
41  }
42
43  // ------------------------------------------------------------------
44  // Callback function for our example setting
45  // ------------------------------------------------------------------
46  //
47  // creates a checkbox true/false option. Other types are surely possible
48  //
49
50  function eg_setting_callback_function() {
51   echo ' . checked( 1, get_option('eg_setting_name', false) ) . ' /> Explanation text';
52  }
53 ?>

这段代码做出的效果如下图：

参考手册：http://codex.wordpress.org/Settings_API#Function_Reference