如何定制WordPress后台的「说明」(Contextual Help)页面与「显示选项」(Screen Options)页面?

0

登入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资料之用,若有机会我们再深入介绍!

发表评论

您的邮箱不会公开,当您的评论有新的回复时,会通过您填写的邮箱向您发送评论内容。 必填字段 *

为何看不到我发布的评论?

正在提交, 请稍候...