首页    >    中文手册    >   Widgets API

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

函数引用

侧边栏函数

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。

分类:中文手册

* 版权声明:作者WordPress啦! 转载请注明出处。

kadıköy escortbostancı escortataşehir escortbostancı escortmaltepe escortmaltepe escortanadolu yakası escortanadolu yakası escortataşehir escortbostancı escortistanbul escortkartal escortbostancı escortkartal escortkadıköy escortpendik escortpendik escortmaltepe escortataşehir escortmaltepe escortmaltepe escortanadolu yakası escortkadıköy escortataşehir escortkadıköy escortataşehir escortümraniye escortataşehir escortkartal escortescort bayankartal escortpendik escortkartal escortgöztepe escorttuzla escortkadıköy escortkartal escortkadıköy escortmaltepe escortkartal escortataşehir escortmaltepe escortbostancı escortkartal escortpendik escortkadıköy escortataköy escortavrupa yakası escortataköy escortbakırköy escortbeylikdüzü escorttaksim escorthalkalı escortetiler escortbodrum escortmalatya escortankara escortantalya escortmersin escortantalya escortHacklinkHacklinkshellwso shellwso shellgörüntülü sohbettipobetbahis siteleri