登入WP后台时,可以发现画面的右上角有两个标签链接,分别是「显示选项」及「说明」。按下这两个链接,都会拉出一个小画面,分别显示与此页面相关的控制选项及说明页面。本篇文章先介绍其中的「说明」页面该如何定制,而显示选项(Screen Options)页面的定制方式其实也差不多。
为什么要定制「说明」和「显示选项」页面?
为什么您可能需要去定制「说明」页面呢?也许是因为您制作了新的插件(Plugin),而您的插件在后台提供了操作页面,这时如果您希望使用者在进行设定时能获得更详细的说明时,您就需要去定制说明页面。也有可能您不希望客户看到预设的说明页内容,您当然也可以把预设的内容「隐藏」起来。同样的,如果有一些进阶选项,您也可以放在显示选项页面里。
定制「说明」页面
要定制说明页面,只要增加一个contextual_help的filter就可以了:
add_filter('contextual_help', 'custom_help', 10, 3); function custom_help($contextual_help, $screen_id, $screen) { $contextual_help = '您好,欢迎使用WP!'; return $contextual_help; } |
先来个add_filter()的参数说明:
- add_filter的第一个参数是指我们要hook的function名称,是wp提供给我们的。
- 第二个参数是我们自定义的hook function,名称是自定义的,随后我们就会把希望做的事写进这个hook function中。
- 第三个参数值在此设为10,这是执行的优先顺序(priority),预设是10,数值愈小表示愈早执行。
- 第四个参数值是3,这表示hook function的参数个数,共有三个,因为contextual_help function的规格就是需要三个参数,所以在此我们必须设定为3。
您可以把上述代码贴进您目前使用的主题目录下的functions.php (如果没这个文件,自行新建就可以了),记得要放在 之间。贴完后保存,您可以发现,这时所有页面的「说明」页内容,全部变成「您好,欢迎使用WP!」了。 目前我们已经可以更改说明页的内容,但还不够好,因为我们想要针对某个页面,去做内容的定制,所以我们需要利用 $screen_id 这个参数。
针对特定后台的页面作定制
当我们自己新增自定义的后台页面时,我们通常会利用一些名字看起来像add page的hook,例如:一般的页面我们用add_menu_page,add_submenu_page来增加主选单及子选单页面,如果是新增管理页面,我们会用add_dashboard_page(控制台页面),add_options_page(设定页面)…等来增加选单页面。 而当我们使用这些hook时,它其实就会回传属于此页面的 hook id,而这个hook id就能拿来对应到 $screen_id 这个参数,以识别是否为此页。
举例说明,我们新增一个自定义的页面放在「设置」里,但我们要利用一个global变数存放它的hook id:
add_action('admin_menu', 'my_plugin_menu'); function my_plugin_menu() { global $my_plugin_hook; $my_plugin_hook = add_options_page('MyPlugin Opts', 'MyPlugin', 'mag_opts', 'my-uniq-idr', 'my_plugin_opts'); } |
接下来,我们回头调整一下定制说明页代码:
add_filter('contextual_help', 'custom_help', 10, 3); function custom_help($contextual_help, $screen_id, $screen) { global $my_plugin_hook; // 判断若目前画面的screen_id是我们的plugin hook id,就显示对应的说明内容 if ($screen_id == $my_plugin_hook) { $contextual_help = '您好,欢迎使用My Plugin!'; } return $contextual_help; } |
如此就能成功定制说明页面罗! 至于内置的管理页面,您可以透过输出$screen_id来判断该页面的id为何,例如我们在不是自定义页面的情况下,就在说明内容的最后一行输出$screen_id的内容:
add_filter('contextual_help', 'custom_help', 10, 3); function custom_help($contextual_help, $screen_id, $screen) { global $my_plugin_hook; // 判断若目前画面的screen_id是我们的plugin hook id,就显示对应的说明内容 if ($screen_id == $my_plugin_hook) { $contextual_help = '您好,欢迎使用My Plugin!'; } else { $contextual_help .= '<h3>您好,目前页面的screen_id为:'.$screen_id.'</h3>'; } return $contextual_help; } |
如此就能针对内置页面进行定制说明页的内容了。
耶?我们好像还漏了一个参数没有介绍,就是$screen。不过,我们先来看看定制「显示选项」页面的方式。
定制「显示选项」页面
我们只要利用screen_settings这个filter就能定制显示选项页面了:
add_filter('screen_settings', 'screen_options_demo', 10, 2); function screen_options_demo($current, $screen) { $current .= '<b>此页的screen id为:'.$screen->id.'</b>'; return $current; } |
您可以看到,这个filter的hook function也有一个$screen的参数,您可以用print_r($screen)来观察$screen这个物件的内容,您会发现$screen_id和$screen->id的内容是一样的,所以它跟说明页面的定制方式其实非常相似。
使用print_r,我们还能看到$screen->action,$screen->parent_file…等其他设定值也会一并传入,似乎是用来作POST资料之用,若有机会我们再深入介绍!