Widget设计文档

组成系统的最基本元素

Widget是组成Typecho的最基本元素,除了已经抽象出来的类库外,其它几乎所有的功能都会通过Widget来完成.在实践中我们发现,在博客这种小型但很灵活的系统中实施一些大型框架的思想是不合适的,它会使系统灵活性降低并且维护成本增高.因此为了达到功能和抽象的统一,我们将系统中所有的功能单元都看作一个Widget,它们都继承自一个超类TypechoWidget.

Widget有两种调用方法.它们分别是

显式地初始化一个Widget实例.

class Foo extends Typecho_Widget
{
    public function test()
    {
        echo 'hello world';
    }
 
    public function render($a, $b)
    {
        echo $a + $b;
    }
}
 
$widget = new Foo();

使用工厂函数factory初始化Widget,并运行入口函数.
```
Typecho_API::factory('Foo', 6, 8);
//outputs: 14
```

在系统中,我们通常使用后者来实例化一个Widget → Typecho::widget函数将直接返回一个实例化的Widget对象.它的第一个参数是Widget的绝对名称,在Typecho系统中Widget有两个存放的地方,他们分别是./widget目录和./var/plugins目录.Widget与其文件名保持一致且区分大小写,比如一个Widget的名称为TestMe那么它的文件名就是TestMe.php.

Widget文件可以按目录存放,调用的时候用点分号分割目录.比如存放路径为./widget/contents/TestPost.php,调用方法就是

Typecho::widget('contents.TestPost');

在上面的解释中,我们提到widget函数的作用是实例化一个Widget并运行它的入口函数.Widget的入口函数是render,这是一个公开函数,子类在继承超类TypechoWidget时必须实现这一方法.因此widget函数后面的参数将传递给入口函数render,比如上例中的Typecho::widget('Foo',6,8),后面的两个参数将传递给Foo::render($a, $b).

何时调用

Widget通常在以下三个地方被调用.

默认组件.Typecho系统共有两个入口(前台和后台),在这两个入口初始化的时候分别会运行一些必要的默认组件,在index.php中有以下代码

Typecho::widget('Options')->to($options);    //初始化配置组件
Typecho::widget('Access')->to($access);      //初始化权限组件

在./admin/header.php中有以下代码

Typecho::widget('Options')->to($options);    //初始化配置组件
Typecho::widget('Access')->to($access);      //初始化权限组件
Typecho::widget('Menu')->to($menu);          //初始化菜单组件

这些Widget在系统初始化时被强制执行.

通过路由器默认执行的组件.路由器是系统的重要组成部分,前台的所有页面都会通过路由器来展现,路由器在默认组件执行之后被执行.我们可以在路由表中设置默认执行的组件,这样当页面被导向这条路由记录时,默认组件将被执行.下面是一个路由表的示例,你可以在./config.php中找到它的完整定义

/** 定义路由结构 **/
global $route;
 
$route = array(
    'index'         =>  array('/', 'index.php', NULL, NULL, array('contents.Posts')),   //最后的一个参数表示默认组件
    'index_page'    =>  array('/page/([0-9]+)[/]?', 'index.php', array('page'), '/page/%d', array('contents.Posts')),
    'post'          =>  array('/archives/([0-9]+)[/]?', 'post.php', array('cid'), '/archives/%d', array('contents.Post')),
    'rss'           =>  array('/feed[/]?', '../../xml/rss.php', NULL, '/rss', NULL),
    'do'            =>  array('/([_0-9a-zA-Z-]+)\.do?', array('DoWidget'), array('do'), '/%s.do'),
    'job'           =>  array('/([_0-9a-zA-Z-]+)\.job?', array('JobWidget'), array('job'), '/%s.job'),
    'login'         =>  array('/login[/]?', 'admin/login.php'),
    'admin'         =>  array('/admin[/]?', 'admin/index.php'),
    'page'          =>  array('/([_0-9a-zA-Z-]+)[/]?', 'page.php', array('slug'), '/%s', array('contents.Post')),
);

在最终页面中被执行的组件.最终页面也就是开发者最常接触到的模板之类的页面,我们通过widget函数来调用我们需要的组件.

<html>
<head>
<title><?php $options->title(); ?></title>
</head>
<body>
 
<div>
<!-- 第一种调用方法,调用公开方法生成列表 -->
<?php Typecho::widget('contents.Posts')->output('li', '_blank', 'list', true, 10, '[...]'); ?>
 
<!-- 第二种调用方法,调用集成方法生成列表 -->
<?php Typecho::widget('contents.Posts')->parse('<li><a href="{permalink}">{title}</a></li>'); ?>
 
<!-- 第三种调用方法,每行输出 -->
<?php Typecho::widget('contents.Posts')->to($posts); ?>
 
<?php while($posts->get()): ?>
 
    <h2><a href="<?php $posts->permalink(); ?>"><?php $posts->title(); ?></a></h2>
 
    <cite><?php $post->date('Y-m-d'); ?> | <?php $post->category(','); ?></cite>
 
    <div><?php $post->content('阅读更多...'); ?></div>
 
<?php endwhile; ?>
</div>
</body>
</html>

由于widget函数将直接返回实例化的组件(Widget)对象,因此我们可以通过返回值直接使用Widget的公开方法.其中一些比较特殊的方法将在后面被陆续介绍到.

一次执行规则

什么是一次执行规则

当一个组件被实例化以后,它将被保存在对象堆栈中,当我们第二次使用这一组件时,它将被直接从堆栈中取出然后返回.这一规则可以在保证组件唯一性的同时节约服务器资源.

如何调用已经被实例化的组件

一般来说我们通过函数widget调用一个组件时,它会返回一个实例化组件,你不必担心它是否是第一次被实例化.

to方法

to方法是一个非常有用的伪方法,它的作用在于把一个实例化的Widget赋到一个变量中.我们可以通过以下代码来展示

Typecho::widget('Foo')->to($foo);
$foo->test();

在上面的代码中我们通过to方法把实例化的Foo组件赋值给$foo.这样我们在后面的代码中可以用$foo变量来代表实例化的Foo对象,它等效于

$foo = Typecho::widget('Foo');

之所以不直接使用赋值语法,是因为赋值在模板中会经常用到,这一简写语法比较好理解,可以简化模板语法.to方法在超类TypechoWidget中被实现,通过继承TypechoWidget可以自动具备这一方法.

push以及相关方法

每个Widget都有一个内部队列,用于存储多行数据,这个堆栈的数据存取方法在超类TypechoWidget中被实现，我们通过继承超类获得对队列的操作能力。每次执行push方法，都将把一行数据压入队列，并移动队列的指针。数据压入完毕后，我们可以通过get方法移动指针，并且通过直接访问组建的内部属性获得某行的具体数据，我们通过如下代码来展示这一过程

class Foo extends TypechoWidget
{
    public function render()
    {
        //定义三行数据
        $row1 = array('name' => 'Mike', 'age' => 17, 'sex' => 'man');
        $row2 = array('name' => 'Lucy', 'age' => 27, 'sex' => 'woman');
        $row3 = array('name' => 'Clark', 'age' => 23, 'sex' => 'man');
 
        //按顺序压入队列
        $this->push($row1);
        $this->push($row2);
        $this->push($row3);
 
        //从队列中取出相应值
        while($this->get())
        {
            echo "My name is " . $this->name . ", I'm " . $this->age . " years old, I am a " . $this->sex . ".\r\n";
        }
    }
}
 
/***
输出:
My name is Mike, I'm 17 years old, I am a man.
My name is Lucy, I'm 27 years old, I am a woman.
My name is Clark, I'm 23 years old, I am a man.
***/

parse方法

parse方法实际上是对队列内数据输出的改善，以方便用户在html视图模板页面中显示列表，你不需要使用while之类的循环语法，直接指定一个列表模板即可，此函数会按照模板直接输出列表。因此我们可以对上面的例子做一点改进，用更少的代码达到同样的效果。

class Foo extends TypechoWidget
{
    public function render()
    {
        //定义三行数据
        $row1 = array('name' => 'Mike', 'age' => 17, 'sex' => 'man');
        $row2 = array('name' => 'Lucy', 'age' => 27, 'sex' => 'woman');
        $row3 = array('name' => 'Clark', 'age' => 23, 'sex' => 'man');
 
        //按顺序压入队列
        $this->push($row1);
        $this->push($row2);
        $this->push($row3);
 
        //使用parse输出
        $this->parse("My name is {name}, I'm {age} years old, I am a {sex}.");
    }
}
 
/***
输出:
My name is Mike, I'm 17 years old, I am a man.
My name is Lucy, I'm 27 years old, I am a woman.
My name is Clark, I'm 23 years old, I am a man.
***/

alt方法

在视图中输出widget列表内容时,可能产生如下隔行输出不同风格的需求.

<ul>
<li class="style-one">hello world</li>
<li class="style-two">hello china</li>
<li class="style-one">hello earth</li>
<li class="style-two">hello moon</li>
</ul>

注意以上代码中class的内容,也就是以2为界的循环输出.我们可以通过调用alt方法达到目的.

<?php Typecho::widget('Hello')->to($hello); ?>
 
<?php while($hello->get()): ?>
<li class="<?php $hello->alt('style-one', 'style-two'); ?>"><?php $hello->word(); ?></li>
<?php endwhile; ?>

我们在上述代码中使用了alt方法，alt方法接受不定数目的参数，也就是说你可以给它传递任意个数的参数，它将按照你传递参数的个数循环输出这些参数。

目录

组成系统的最基本元素

什么是Widget

如何调用Widget