目录
[隐藏]

wordpress widget API

wordpress自带了一些小工具,可以让你自由的拖动到侧边栏,并支持自由排序。但毕竟自带的小工具不多,而且功能有限,那么我们能不能添加我们自己的小工具呢?当然可以。

自从wordpress升级到2.8之后,提供了一个WP_Widget类,我们只需要扩展WP_Widget类,就可以自定义我们自己的小工具(widget)。如果你想深入了解该类,请查看wp-includeswidgets.php。

前几天我制作了一个在侧边栏显示随机文章的小工具,今天我就以此为例来详细的解说一下小工具的制作过程。如果你有一定的html和php知识,将很容易理解,如果没有,直接套用就行了。

新建一个php文件,文件名你可以根据自己的需要自己定义,我们在这里就使用random-posts.php。编辑该文件,输入<?php   ?>。接下来我们所有的代码都是添加在<?php和?>之间。

添加插件信息

在进入正题之前,我们先对插件作一个简单的描述。按照wordpress的要求,在文件的开始处添加下面这样的注释

<?php
/*
 * Plugin Name: 随机文章 小工具
 * Version: 1.0
 * Plugin URI: http://domety.com/archives/141
 * Description: 这是一个显示随机文章的小工具(widget),可以设置随机文章的数量,指定文章分类目录。
 * Author: DDBug
 * Author URI: http://domety.com/
 */

其中的Plugin Name(插件名称)、Version(版本号)、Plugin URI(插件地址)、Description(简介)、Author(作者)、Author URI(作者主页) 是固定不变的,你可以修改后面的内容。这些内容将显示在插件列表中,如下图所示

wordpress widget API

自定义小工具类

接下来开始制作我们的小工具,由定义一个WP_Widget的扩展类开始。类名由我们自己定义,这里我用类名是RandomPostsWidget

class RandomPostsWidget extends WP_Widget
{
     /*
     ** 构造函数
     ** 声明一个数组$widget_ops,用来保存类名和描述,以便在控制面板正确显示工具信息
     ** $control_ops 是可选参数,用来定义小工具在控制面板显示的宽度和高度
     ** 最后是关键的一步,调用WP_Widget来初始化我们的小工具
     */
     function RandomPostsWidget(){
     $widget_ops = array('classname'=>'widget_random_posts','description'=>'随机显示你博客中的文章');
     $control_ops = array('width'=>250,'height'=>300);
     $this->WP_Widget(false,'随机文章',$widget_ops,$control_ops);
     }

    ...... 省略了其它函数,将在下面说明

}

在我们的构造函数RandomPostsWidget()中定义了两个数组变量$widget_ops和$control_pos,然后传递给$this->WP_Widget()进行初始化。

WP_Widget的第一个参数是$id_base,我们一般设置成false即可

第二个参数指定小工具显示的名称,第三个参数指定类名和小工具的描述,这两个参数结合在一起的效果如下

wordpress widget API

第四个参数定义小工具的宽度和高度,一般可以不用定义。它影响的效果是当你把小工具拖到侧边栏时的宽度和高度。

一般的用法是传递前面三个参数就可以了。

三个重要函数

接下来是定义类的另外三个重要函数form、update、widget。

form函数一般是用来显示小工具的选项设置表单,表单的内容根据需要自己定义。这个随机文章小工具可以让用户自定义4个内容:
模块标题,默认为“随机文章”
显示文章数量,默认为10篇
分类目录ID,默认为0,即显示所有分类下的文章
CSS样式class名,默认为randomPosts

先看一下显示效果

wordpress widget API

再看一下函数定义代码

function form($instance){
  $instance = wp_parse_args((array)$instance,array('title'=>'随机文章','showPosts'=>10,'cat'=>0,'class'=>'randomPosts'));
  $title = htmlspecialchars($instance['title']);
  $showPosts = htmlspecialchars($instance['showPosts']);
  $cat = htmlspecialchars($instance['cat']);
  $class = htmlspecialchars($instance['class']);
  echo '<p style="text-align:left;"><label for="'.$this->get_field_name('title').'">标题:<input style="width:200px;" id="'.$this->get_field_id('title').'" name="'.$this->get_field_name('title').'" type="text" value="'.$title.'" /></label></p>';
  echo '<p style="text-align:left;"><label for="'.$this->get_field_name('showPosts').'">文章数量:<input style="width:200px;" id="'.$this->get_field_id('showPosts').'" name="'.$this->get_field_name('showPosts').'" type="text" value="'.$showPosts.'" /></label></p>';
  echo '<p style="text-align:left;"><label for="'.$this->get_field_name('cat').'">分类ID:<input style="width:200px" id="'.$this->get_field_id('cat').'" name="'.$this->get_field_name('cat').'" type="text" value="'.$cat.'" /></label></p>';
  echo '<p style="text-align:left;"><label for="'.$this->get_field_name('class').'">class:<input style="width:200px" id="'.$this->get_field_id('class').'" name="'.$this->get_field_name('class').'" type="text" value="'.$class.'" /></label></p>';
 }

注意代码中我们用到的4个$instance数组的key:title、showPosts、cat 和 class。这些key名可以自己定义,但在前后的使用过程中要保持一致。另外wordpress提供了两函数get_field_name 和get_field_id来保证表单内每一项设置都保存到相应的数组Key中。

update函数用于更新保存的设置。其实这个函数可以不定义,不过为了提高安全性,我们一般用此函数进行字符串的过滤

function update($new_instance,$old_instance){
  $instance = $old_instance;
  $instance['title'] = strip_tags(stripslashes($new_instance['title']));
  $instance['showPosts'] = strip_tags(stripslashes($new_instance['showPosts']));
  $instance['cat'] = strip_tags(stripslashes($new_instance['cat']));
  $instance['class'] = strip_tags(stripslashes($new_instance['class']));

  return $instance;
 }

如果不定义此函数,默认返回的将是$new_instance,即在小工具选项中所做的更改。你应该注意到,我们使用了strip_tags和stripslashes这两个php函数来过滤掉用户输入的不合法的字符。

widget函数定义小工具在页面中的显示方式

function widget($args,$instance){
  extract($args);
  $title = apply_filters('widget_title',empty($instance['title']) ? '&nbsp;' : $instance['title']);
  $showPosts = empty($instance['showPosts']) ? 10 : $instance['showPosts'];
  $cat = empty($instance['cat']) ? 0 : $instance['cat'];
  $class = empty($instance['class']) ? 'randomPosts' : $instance['class'];

  echo $before_widget;
  echo $before_title . $title . $after_title;
  the_rand_posts("showPosts=$showPosts&cat='$cat'&class='$class'");
  echo $after_widget;
 }

首先使用了extract函数把数组中的keys转换成变量,比如下面用到 的$before_widget、$before_title、$after_title、$after_widget,这些变量不同的主题模块有不同的 值,我将在定义侧边栏中进行介绍。然后从$instance中取出保存的各个key的值,再通过调用我自定义的the_rand_posts函数来显示随 机文章的标题列表。效果如下

wordpress widget API

附the_rand_posts函数定义代码

function the_rand_posts($args = ''){
 $default = array('showPosts'=>10,
  'cat'=>'0',
  'class'=>'randomPosts');
 $r = wp_parse_args($args,$default);
 extract($r);
 $rand_query = new WP_Query("cat=$cat&showposts=$showPosts&orderby=rand");
 if($rand_query->have_posts()){
  echo '<ul>';
  while($rand_query->have_posts()){
   $rand_query->the_post();
   echo '<li><a href="'.get_permalink().'">'.get_the_title().'</a></li>';
  }/*End while($rand_query->have_posts())*/
  echo '</ul>';
 }/*End if($rand_query->have_posts())*/
}

到这里,我们的小工具类RandomPostsWidget已经定义完成了。接下来再完成最后一步,注册该小工具类,就完成了随机文章小工具的制作。

注册小工具

这是我们制作小工具的最后一步,把上面我们定义的小工具类RandomPostsWidget注册。以下这些代码要添加到上面的类定义之外

} // RandomPostsWidget 类定义结束

/*
** 注册小工具
*/
function RandomPostsInit(){
 register_widget('RandomPostsWidget');
}

add_action('widgets_init','RandomPostsInit');

我们定义了一个RandomPostsInit函数,调用wordpress的register_widget来注册我们的类 RandomPostsWidget。最后通过add_action把我们定义的函数RandomPostsInit加入到wordpress的 widgets_init函数中。这样就完成了我们的小工具注册工作,也最终完成了小工具的制作流程。

有关该小工具的源代码下载以及安装和使用方法,可以参看http://domety.com/archives/141

via:http://domety.com/archives/143/