Widgets API

这是WordPress Widget（小工具）API（应用程序接口）的技术性文档，目标读者包括WordPress主题开发人员、插件开发人员以及所有希望开发单机widget的用户。文档假设读者对PHP脚本语言有基本了解。

widget是一个可在调用时利用echo命令将字符串数据输出到STDOUT上的PHP函数。要将这样的PHP函数转换成WordPress Widget，需要用一个PHP回调（PHP文档中的一个准型(Pseudo-Type)）将这些PHP函数注册为WordPress Widget。WordPress widget API函数会负责注册该PHP回调。

WordPress widget API位于 wp-includes/widgets.php中。

函数引用

侧边栏函数

• is_active_sidebar
• register_sidebars
• register_sidebar
• unregister_sidebar
• is_dynamic_sidebar
• dynamic_sidebar
• register_sidebar_widget
• unregister_sidebar_widget
• wp_register_sidebar_widget
• wp_unregister_sidebar_widget
• wp_get_sidebars_widgets
• wp_set_sidebars_widgets

Widget函数

• is_active_widget
• the_widget
• register_widget
• unregister_widget
• register_widget_control
• unregister_widget_control
• wp_register_widget_control
• wp_unregister_widget_control
• wp_convert_widget_settings
• wp_get_widget_defaults
• wp_widget_description

注意：不推荐使用以"wp_"开始的函数，因为这些函数可能会随着新版本的发布而有所变化。这也是我们用 register_sidebar_widget()代替wp_register_sidebar_widget()的原因。

定义侧边栏

下面这些函数可以使侧边栏在主题中正常显示。

注册多个侧边栏

register_sidebars( $count, $args );  

注册一个或多个侧边栏以供当前主题使用。大多数主题都只有一个侧边栏。因此count参数不是必需参数，且默认值为1。

$args参数将被传递给register_sidebar()并遵循其格式，但参数名除外，若count参数值为双数，$args参数名将与sprintf()合作，在每个侧边栏中插入或添加一个唯一数字。

例如，以下代码会生成两个分别名为"Foobar 1"与 "Foobar 2"的侧边栏。

register_sidebars(2, array('name'=>'Foobar %d'));  

注册一个侧边栏

register_sidebar( $args );  

可选的args参数是一个关联数组，该关联数组将作为第一个参数被传递给所有已激活的widget回调。（若传递的是字符串而非数组，该参数将被parse_str()遍历，从而生成一个关联数组。）传递指定主题的HTML标签以包裹widget与其标题，这是参数的基本用法。下面是参数默认值：

'before_widget' => '<li id="%1$s" class="widget %2$s">',
'after_widget' => "</li>n",
'before_title' => '<h2 class="widgettitle">',
'after_title' => "</h2>n"

只有在你希望为侧边栏赋予独有名称时，如"Right Sidebar"与"Left Sidebar"，或侧边栏需要被特别标记时，才有必要使用register_sidebar函数而不是register_sidebars函数。侧边栏名称只出现在管理面板中，但也会被用作一个保存侧边栏排列的索引。因此，如果有另一个主题使用相同的侧边栏名称，那么侧边栏就可以再利用并重写它们的排列。

before/after参数的默认值适用于可生成带有“h2”标题的列表型侧边栏的主题。我们推荐所有主题都采用这种侧边栏，以这种方式构建的主题可以轻松注册侧边栏而无需担心before/after标签。如果主题由于某些原因无法以这种方式构建，那么注册侧边栏时一定要指定before/after标签。推荐逐字复制id和class属性，以使内部sprintf调用得以运行，CSS样式也能够被应用到单个widget上。

在主题上显示侧边栏

dynamic_sidebar( $sidebar );  

该函数按顺序逐个调用已启用的widget，从而输出侧边栏的框架。如果你有不止一个侧边栏，你需要向该函数指明你希望输出的侧边栏名称或编号。若显示成功，该函数返回TRUE，若失败则返回FALSE。

用返回的值决定是否显示静态侧边栏。这可保证即使在未激活widgets插件的情况下，主题也能够正常显示。下面是对该函数推荐用法，附带一个可避免致命错误的测试。

<ul id="sidebar">
<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
<li>{static sidebar item 1}</li>
<li>{static sidebar item 2}</li>
<?php endif; ?>
</ul>

如果按编号注册侧边栏，那么检索时应该按编号检索。如果按名称注册侧边栏，检索时也应按名称检索。

开发Widgets

在WordPress 2.8及更高版本中开发widgets

自WordPress 2.8起，widget开发开始变得简单起来。要创建一个widget，你只需要扩展标准widget类和它的一些函数。

在标准类中，也可以找到用以开发widget的函数的信息。

默认用法

class My_Widget extends WP_Widget {
function My_Widget() {
// widget actual processes
}

function form($instance) {
// outputs the options form on admin
}

function update($new_instance, $old_instance) {
// processes widget options to be saved
}

function widget($args, $instance) {
// outputs the content of the widget
}

}
register_widget('My_Widget');

示例

下面的代码示例可生成一个名为FooWidget的widget工具，该widget具有一个可更改显示名称的设置表单。

/**
* FooWidget Class
*/
class FooWidget extends WP_Widget {
/** constructor */
function FooWidget() {
parent::WP_Widget(false, $name = 'FooWidget');
}

/** @see WP_Widget::widget */
function widget($args, $instance) {
extract( $args );
$title = apply_filters('widget_title', $instance['title']);
?>
<?php echo $before_widget; ?>
<?php if ( $title )
echo $before_title . $title . $after_title; ?>
Hello, World!
<?php echo $after_widget; ?>
<?php
}

/** @see WP_Widget::update */
function update($new_instance, $old_instance) {
return $new_instance;
}

/** @see WP_Widget::form */
function form($instance) {
$title = esc_attr($instance['title']);
?>
<p><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" /></label></p>
<?php
}

} // class FooWidget

然后可以在widgets_init钩子（hook）中注册这个示例widget：

// register FooWidget widget  
add_action('widgets_init', create_function('', 'return register_widget("FooWidget");'));  

OK，现在你就拥有一个通用widget了，不需要再对它做特别修改。

更多信息请看WordPress 2.8的版本信息。

开发新widget

Google Search Widget （曾经是 original widget plugin 插件的一部分，该插件已停用）文件的每个部分都做了注释，你可以考虑用它作为widget的开发教程。此外还有一些注意事项：

• 加载插件时不要执行任何代码。请使用plugins_loaded钩子，否则会因为未定义函数而导致致命错误。
• 用register_sidebar_widget($name, $callback) 将widget添加到管理界面。
• 将以下模板作为示范：

function widget_myuniquewidget($args) {
extract($args);
?>
<?php echo $before_widget; ?>
<?php echo $before_title
. 'My Unique Widget'
. $after_title; ?>
Hello, World!
<?php echo $after_widget; ?>
<?php
}
register_sidebar_widget('My Unique Widget',
'widget_myuniquewidget');

重要提示：如果要在插件中使用上述模板，应将其包裹在：

function widget_myuniquewidget_register() {
–the above goes here–
register_sidebar_widget('My Unique Widget','widget_myuniquewidget');}
add_action('init', widget_myuniquewidget_register);

中。

• 不要忽略$before_widget, $after_widget, $before_title与$after_title。出于对不同主题兼容性的考虑，这些参数都是必要的。
• 谨慎命名widget及其函数。widget名称字符串和函数名称字符串都会被用作HTML属性，不要在一个HTML文档中出现两个相同的id。
• 在内部进行本地化，以保留HTML的id属性。如果你希望自己的widget名称以文本域定位，请传递array($name, $textdomain)来代替 $name。
• 要容纳多个widget（如文本widget和RSS widget），你可以传递一个名称为array($name_as_sprintf_pattern, $textdomain, $replacement)的更新值。参见源代码。
• 你可以以多种方式使用上文中提到的变量，在某些情况下甚至可以忽略它们。比如有些widget可能不需要标题。有些widget会多次使用 $before_widget 与 $after_widget，也可能会将变量作为参数，告诉另一个模板标签怎样格式化输出内容。
• 也可以使用下列语句在管理界面中添加配置页面。你的回调会被用在主表单中，因此不能包含任何<form>标签或表单提交按钮。

        register_widget_control($name, $callback [, $width [, $height ]] );  

• 给你的表单元素命名空间，不要让它们与其它widgets冲突
• 每个widget都必须有一个独一无二的名称。你可以提供一个回调，注册另一个相同名称的widget来代替某个已经注册的widget。
• 将register_sidebar_widget()或 register_widget_control()的其它任何参数传递给回调。以文本widget和RSS widget为例。
• 给注册函数传递空字符串，可以“取消”widget的注册
• 可能有些没有记录的函数。推荐你查看源代码，了解我们怎样用这些函数制作标准widget。
• 在Classic和Default主题（这两个WordPress自带主题都使用ul/li/h2构造）之外选择几个主题测试widget。
• 发布自己的widget前请确认其安全性
• 如果你希望自己开发的widget出现在WordPress.com上，可以给widgets@wordpress.com发送邮件，在邮件里注明widget的链接（不接受附件），有人会审核的。

我还能用widget做些什么？

• 开发一个主题，里面含有一个特别的widget，和其它主题区分开来
• 这个做法怎么样：用一个WordPress Loop循环来显示边注
• 注册一个替代widget，缓冲原始widget，并在一定程度上改变原始widget
• 记住，“侧边栏”只是对列表的一个称呼，它可以以垂直方式显示，也可以以水平方式显示。
• 同样要记住的是，“widget”只是对一段配置型代码段的称呼。widget可以是隐藏的，也可以放在显要的位置上。
• 在脚本中使用widget的id和class属性，使侧边栏更有生机
• 用script.aculo.us 或dbx（WordPress内置）工具使得widget可拖拽或者甚至可分解
• 记住，widget控制台API只是为了方便。你可以设置自己的管理界面。
• 给用户提供技术支持，从用户那里获取对widget的反馈信息。在你的widget控制台下方给出你的email地址或者网站。
• 给widgets@wordpress.com发送邮件，在邮件里注明你的widget的链接，如果经过审核，你的widget会被发布在WordPress.com上供所有WordPress用户使用。

Widget——一次性或多次性

可以对widget进行编码，让它只出现一次或者出现多次。只要你遵守一些操作规则，WordPress会自动帮你多次显示widget。

分类：中文手册