Widgets API

0条评论

这是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中。

函数引用

侧边栏函数

Widget函数

注意:不推荐使用以"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。