README.widget

nForum widget 说明
========================================

简介
-------------------
nForum widget支持用户自定义主页的内容，用户在登录后单击左侧的“个性化首页设置”便可添加新的widget，每个widget可以修改标题，颜色，位置。首页的widget可以为2列或者3列(默认),可以在控制面板-用户自定义参数中设置。

实现
-------------------
nForum widget都实现了app/vendors/model/iwidget.php中的iWidget接口
iWidget接口包括的方法如下:
    public function wGetName();
    获取该widget名字，widget的名字是唯一的，大小写不敏感

    public function wGetTitle();
    获取该widget标题，该方法返回一个数组，包含标题文本和链接
    
    public function wGetList();
    获取该widget内容，该方法返回一个数组，数组结构在扩展说明中介绍

    public function wGetTime();
    获取该widget更新时间，该方法返回一个时间戳，用于widget缓存，关于缓存请阅读README.cache

widget被分为核心和扩展两类:
1.核心widget包括分区widget，版面widget和收藏夹widget,nForum已经实现了所以核心widget，其命名方式(即wGetName返回值)为CORE-NAME，其中CORE=board|section|favor，NAME为相应类别的值
2.扩展widget存在于app/vendors/widget文件夹内,其命名方式为nameWidget，其中name为此widget的名字(即wGetName返回值)，小写且唯一，包含此类的文件名默认为name.php；若一个文件包含多个widget类可以在配置文件中默认导入此文件。
由于系统需要，扩展widget命名不允许为time
启用widget需要在app/config/nforum.php中设置$config['widget']['ext']的值，其值是一个关联数组，表示不同扩展widget的类别，数组的值为一个新的数组，这个数组的第一个元素为此类别的名称，第二个元素为此类别widget的名称的数组，第三个元素(可选)是包含widget文件的位置。

呈现方式
-------------------
nforum wdiget的显示方式有两种：
1.直接输出。服务器会缓存各个widget的样式并记录生成时间。若widget内容修改，则自动更新缓存文件。
2.Ajax输出。用此方式，载入首页时并不带有widget内容而通过异步的Ajax调用获取widget内容。
通过设置app/config/nforum.php文件中的$config['widget']['persistent']决定widget输出方式，默认为直接输出。

扩展说明
-------------------
nForum 允许用户扩展新的widget，假设我们扩展一个名为test的widget，步骤如下：
1.在app/vendors/widget添加新的php文件，文件名为test.php
2.编辑test.php导入iwidget.php文件，App::import('vendor', 'model/iwidget');
3.编辑test.php添加类testWidget并继承WidgetAdapter类
4.完善testWidget类的wGetTitle，wGetList，wGetTime方法
5.在app/config/nforum.php文件中修改$config['widget']['ext']['1']数组的值，添加'test'

wGetList返回数组结构:
数组的结构形如A，定义如下
    A=array(array("t"=>"","v"=>A|B)+)|B
    B=array("s"=>STYLE,"v"=>array(C+))
    STYLE=w-free|w-list-line|w-list-float
    C=array("text"=>"", "url"=>"")

缓存策略
-------------------
参见源代码目录下的README.cache