wordpress自带了一些小工具,可以让你自由的拖动到侧边栏,并支持自由排序。但毕竟自带的小工具不多,而且功能有限,那么我们能不能添加我们自己的小工具呢?当然可以。
自从wordpress升级到2.8之后,提供了一个WP_Widget类,我们只需要扩展WP_Widget类,就可以自定义我们自己的小工具(widget)。如果你想深入了解该类,请查看wp-includes\widgets.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(作者主页) 是固定不变的,你可以修改后面的内容。这些内容将显示在插件列表中,如下图所示
自定义小工具类
接下来开始制作我们的小工具,由定义一个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即可
第二个参数指定小工具显示的名称,第三个参数指定类名和小工具的描述,这两个参数结合在一起的效果如下
第四个参数定义小工具的宽度和高度,一般可以不用定义。它影响的效果是当你把小工具拖到侧边栏时的宽度和高度。
一般的用法是传递前面三个参数就可以了。
三个重要函数
接下来是定义类的另外三个重要函数form、update、widget。
form函数一般是用来显示小工具的选项设置表单,表单的内容根据需要自己定义。这个随机文章小工具可以让用户自定义4个内容:
模块标题,默认为“随机文章”
显示文章数量,默认为10篇
分类目录ID,默认为0,即显示所有分类下的文章
CSS样式class名,默认为randomPosts
先看一下显示效果
再看一下函数定义代码
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']) ? ' ' : $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函数来显示随机文章的标题列表。效果如下
附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