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 ‘<p>following is our settings section</p>';
}

这个调用将在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 ‘<input name=”eg_setting_name” id=”gv_thumbnails_insert_into_excerpt” type=”checkbox” value=”1″ ‘ . checked( 1, get_option(‘eg_setting_name’, false) ) . ‘ /> 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))
关于这个函数，可以参考下面这两种等价的写法
<input type=’checkbox’ name=’options[postlink]’ value=’1′ <?php if ( 1 == $options[‘postlink’] ) echo ‘checked=”checked”‘; ?> />

<input type=”checkbox” name=”options[postlink]” value=”1″ <?php checked( $options[‘postlink’], 1 ); ?> />

后面可以跟第三个可选参数，含义为
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函数，他用来从数据库中获得一个参数的值，通常用法为
 <?php echo get_option( ‘option name’, $default ); ?>
其中’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 <?php

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 <input>

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 '<p>Intro text for our settings section</p>';

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 '<input name="eg_setting_name" id="gv_thumbnails_insert_into_excerpt" type="checkbox" value="1" ' . checked( 1, get_option('eg_setting_name', false) ) . ' /> Explanation text';

52 }

53?>

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

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