WordPress控制板小工具API

0条评论

WordPress 2.7引入了一个新的控制板 Widget(小工具)API,用户可以轻松在管理面板中添加各种小工具。使用控制板小工具API,应具备一定的PHP知识并熟悉WordPress插件API。对熟悉动作钩子(hook)和过滤器钩子的插件或主题开发人员来说,只要几分钟就可以熟练使用控制板widget API,并且可以通过widget API使自己开发的插件更具实用效果。

概述

相关函数

wp_add_dashboard_widget() 函数是用来添加控制板小工具的主要工具:

wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback = null)

  • $widget_id —— 新加入的小工具的标识性别名。该参数值用来作为小工具数组中的css类以及键值。
  • $widget_name ——新widget在标题部分显示的名称
  • $callback —— 新创建的函数名称,该函数用来显示widget的实际内容
  • $control_callback —— (可选)新创建的函数名称,该函数用以提交widget选项表并显示表单元素。

动作钩子

运行wp_add_dashboard_widget() 函数前需要连接到相应的动作钩子上(此处即wp_dashboard_setup)。wp_dashboard_setup连接到核心代码:

do_action( 'wp_dashboard_setup' );  

示例

添加一个widget

下面是一个非常简单的widget的大致轮廓:

// Create the function to output the contents of our Dashboard Widget

function example_dashboard_widget_function() {
// Display whatever it is you want to show
echo "Hello World, I'm a great Dashboard Widget";
}

// Create the function use in the action hook

function example_add_dashboard_widgets() {
wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');
}

// Hoook into the 'wp_dashboard_setup' action to register our other functions

add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' );

进阶:将widet显示在页面最上方

一般情况下,插件作者应该允许自己的用户通过拖放的方式将widget小工具放在控制板页面的任何位置。目前还没有简单的API可以预排序默认widget,这就意味着用户新加入的widget只能出现在widget列表的最下方。API不增加排序功能,这个问题就一直无法避免。

下面这个钩子函数示例尝试将新widget排列在默认widget上方。该函数手动更改metabox(此处metabox中的管理面板小工具都是同一种类型)的内部数组并将新widget显示在widget列表最上方。

function example_add_dashboard_widgets() {
wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');

// Globalize the metaboxes array, this holds all the widgets for wp-admin

global $wp_meta_boxes;

// Get the regular dashboard widgets array
// (which has our new widget already but at the end)

$normal_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];

// Backup and delete our new dashbaord widget from the end of the array

$example_widget_backup = array('example_dashboard_widget' => $normal_dashboard['example_dashboard_widget']);
unset($normal_dashboard['example_dashboard_widget']);

// Merge the two arrays together so our widget is at the beginning

$sorted_dashboard = array_merge($example_widget_backup, $normal_dashboard);

// Save the sorted array back into the original metaboxes

$wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
}

可惜的是,以上方法只适用于从来没有调整过widget列表顺序的用户。一旦用户修改了列表顺序,所做修改将优先于以上方法做出的排序,原有widget顶替新widget出现在列表最上方。

进阶:删除控制板widget

在某些情况下,尤其是在多作者博客上,删除管理界面上的widget小工具或许有一定帮助性。虽然说每个作者都可以在界面最上方的“选项设置”中关闭任何一个已有widget,但对不懂技术的作者来说,不显示这些widget或许更好。

要删除控制板小工具,需要在$wp_meta_box数组中手动取消对这些小工具的设置,也可以根据上文介绍的添加widget的方法在wp_dashboard_setup中进行类似操作。

下面是控制板上的所有metabox:

主栏

$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_recent_comments']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_plugins']

侧栏

$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_recent_drafts']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_secondary']

无论需要输出主栏或是侧栏的列表名,都可以使用以下代码(替换数组第二位的normal或core):

foreach (array_keys($wp_meta_boxes['dashboard']['normal']['core']) as $name){
echo ("<p>");
echo ($name);
echo("</p>");

}

下面的这个函数示例,通过消除quickpress与incomming_links小工具的数组选项来删除这两个小工具。

// Create the function to use in the action hook

function example_remove_dashboard_widgets() {
// Globalize the metaboxes array, this holds all the widgets for wp-admin

global $wp_meta_boxes;

// Remove the quickpress widget

unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']);

// Remove the incomming links widget

unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']);
}

// Hoook into the 'wp_dashboard_setup' action to register our function

add_action('wp_dashboard_setup', 'example_remove_dashboard_widgets' );

整合控制板中的RSS订阅

很多默认的控制板widge整合了对WordPress开发博客和插件资源的订阅。推荐需要在widget中进一步整合RSS订阅的用户看这里