DedeCMS二次开发手册.doc

DedeCMS V5.3二次开发手册

一、模板篇
1.1、主要模板文件与功能说明
DedeCMS系统的模板是非固定的，用户可以在新建栏目时可以自行选择栏目模板，官方仅提供最基本的默认模板，即是内置系统模型的各个模板，由于DedeCMS支持自定义频道模型，用户自定义新频道模型后，还需要按该模型的字段设计一套新的模板，此外，DedeCMS也支持使用风格的形式使用模板，默认风格是 default，它表示系统默认使用 {cmspath}/templets/default 这个文件夹的模板，如果你下载了一套新的模板，你可以不必要删除 default 原有的文件，把下载的模板文件夹命名你想要的风格名称，如 style2 等，然后在后台修改了默认的模板风格名称为 style2 ，那系统将使用{cmspath}/templets/style2 这文件当作默认模板，但是若你手工指定了栏目模板的位置，则后台参数风格的定义无效。
一、概念，设计和使用模板，必须要理解下面几个概念
1、板块（封面）模板：
指网站主页或比较重要的栏目封面频道使用的模板，一般用“index_识别ID.htm”命名，此外，用户单独定义的单个页面或自定义标记，也可选是否支持板块模板标记，如果支持，系统会用板块模板标记引擎去解析后才输出内容或生成特定的文件。
2、列表模板：
指网站某个栏目的所有文章列表的模板，一般用 “list_识别ID.htm” 命名。
3、档案模板：
表示文档查看页的模板，如文章模板，一般用 “article_识别ID.htm” 命名。
4、其它模板：
一般系统常规包含的模板有：主页模板、搜索模板、ＲＳＳ、ＪＳ编译功能模板等，此外用户也可以自定义一个模板创建为任意文件。
二、 命名，DedeCMS模板默认命名规则如下
1、模板保存位置：
模板目录：{cmspath} /templets/样式名称（英文，默认为default，其中system为系统底层模板，plus为插件使用的模板）/具体功能模板文件｝
2、 模板文件命名规范：
（１）index_识别ID.htm：　表示板块（栏目封面）模板；
（２）list_识别ID.htm：　表示栏目列表模板；
（３）article_识别ID.htm：　表示内容查看页（文档模板，包括专题查看页）；
（４）search.htm： 搜索结果列表模板；
（５）index.htm： 主页模板；
注解：[识别ID]可以在“频道模型管理”的地方获得，当然，你也可以在“频道模型管理”的地方确定某个频道的模板命名。
例：list_image.htm 表示是就是内容类型为图片集的栏目默认列表模板。
article_article.htm 表示的是文章查看页模板。
三、其它模板说明
1、默认底层模板
位置： {cmspath}/templets/system
功能：在没有指定标记的默认底层模板的时候，系统将自动调用这个文件夹的相应文件作为底层模板。
2、插件目录模板
位置： {cmspath}/templets/plus
功能：评论、友情链接、RSS地图等模板。
3、会员后台模板
位置： {cmspath}/member/templets
功能：会员后台的模板。
四、二次开发
在V5.3中已经将标签开发分离出来，您可以通过后台[模板]-[标签代码管理]，点击“新增加一个新的标签”来创建一个自己的标签，标签文件名为：标签名.lib.php
接口函数定义为：function lib_标签名(&$ctag,&$refObj)，返回值是结果字符串
修改标签时为了防止出错，您也可以修改它的名称(同时修改文件名和函数名)，这样等同继承了原来标签的代码建立一个新的标签。

1.2、模板标签语法简介
织梦的模板标签类似于XML格式，所有的模板都含有定界符，默认情况下是{dede:*}和{/dede:*}，“*”代表模板标记名称。
一般情况下{dede:*}和{/dede:*}是成对出现的，例如：
例1-1：
1 {dede:arclist flag='h' limit='0,1'}<br />
2 <h2><a href="[field:arcurl/]">[field:title/]</a></h2><br />
3 <p>[field:description/]...<a href="[field:arcurl/]">[查看全文]</a></p><br />
4 {/dede:arclist}

上面的{dede:arclist}和{/dede:arclist}成对出现在模板文件中，并且在两个标签当中包含了底层模板(innertext)。
底层模板（Innertext），底层模板实际上就是对于有多条记录的模板输出，用户手工去指定单个记录的样式。
标签还有一类出现形式是{dede:*/}，通常以这种形式出现都是输出变量、或者不含底层模板的内容。
例如：1-2
{dede:global.cfg_webname/}
{dede:arclist flag='h' limit='0,1'/}
如果用户没有指定单个记录的样式，系统部分标签都含有默认的底层模板，具体可以查看{cmapath}/templets/system/文件夹下面的文件，这里面都是系统的底层模板文件。

注释
织梦标签的模板注释非常灵活，可以通过标签后面的commet属性进行赋值。
例1-3：

1 {dede:arclist flag='h' limit='0,1' commet='调用头条的第一篇内容'}<br />
2 <h2><a href="[field:arcurl commet="这是文章链接标签"/]">[field:titlecommet="这是文章标题标签"/]</a></h2><br />
3 <p>[field:description commet="这是摘要标签"/]...<a href="[field:arcurl commet="这是文章链接标签"/]">[查看全文]</a></p><br />
4 {/dede:arclist}

在模板引擎将上述标签解析为html的时候，commet的内容是被忽略掉不去解析的，用户在阅读模板标记的时候可以更好的理解标签的意义。
函数
每一个织梦的标签都可以使用自定义函数对其进行扩展，自定义函数内容主要用于对当前标签输出内容进行处理。
例1-4：
{dede:标记名称function='youfunction("参数一","参数二","@me")'/}
其中 @me 用于表示当前标记的值，其它参数由你的函数决定是否存在，例如：
{dede:field.pubdate function='strftime("%Y-%m-%d %H:%M:%S","@me")'/}

属性
模板标签的属性，决定了模板标记输出的形式，例如arclist标签主要功能是列出文档列表，但列出什么内容、按照什么方式进行排序等取决于模板标签的属性。
在织梦的模板标签说明中含有各个模板的标签属性可以详细查阅。
可以查看例1-1中的flag='h' limit='0,1'，这里flag和limit是标签的相关属性，通过手册可以查阅属性的介绍。
如果模板标签如果没有列出属性，系统有默认属性值，用户可以参考模板标签说明查看默认属性。
编程
织梦模板很方便的一个地方就是支持简单的模板编程。
格式为：
1 {dede:tagname runphp='yes'}<br />
2 $aaa = @me;<br />
3 @me = "123456";<br />
4 {/dede:tagname}
@me 表示这个标记本身的值，因此标记内编程是不能使用echo之类的语句的，只能把所有返回值传递给@me。
此外由于程序代码占用了底层模板InnerText的内容，因此需编程的标记只能使用默认的InnerText。

二、 代码篇
2.1、common.func.php 公用函数
获得当前的脚本网址
function GetCurUrl()

返回格林威治标准时间
function MyDate($format='Y-m-d H:i:s',$timest=0)

把全角数字转为半角
function GetAlabNum($fnum)

把含HTML的内容转为纯text
function Html2Text($str,$r=0)

把文本转HTML
function Text2Html($txt)

输出Ajax头
function AjaxHead()

中文截取2，单字节截取模式
function cn_substr($str,$slen,$startdd=0)

把标准时间转为Unix时间戳
function GetMkTime($dtime)

获得一个 0000-00-00 00:00:00 标准格式的时间
function GetDateTimeMk($mktime)

获得一个 0000-00-00 标准格式的日期
function GetDateMk($mktime)

获得用户IP
function GetIP()

获取拼音以gbk编码为准
function GetPinyin($str,$ishead=0,$isclose=1)

dedecms通用消息提示框
function ShowMsg($msg,$gourl,$onlymsg=0,$limittime=0)

保存一个cookie
function PutCookie($key,$value,$kptime=0,$pa="/")

删除一个cookie
function DropCookie($key)

获取cookie
function GetCookie($key)

获取验证码
function GetCkVdValue()

过滤前台用户输入的文本内容
// $rptype = 0 表示仅替换 html标记
// $rptype = 1 表示替换 html标记同时去除连续空白字符
// $rptype = 2 表示替换 html标记同时去除所有空白字符
// $rptype = -1 表示仅替换 html危险的标记
function HtmlReplace($str,$rptype=0)

获得某文档的所有tag
function GetTags($aid)

过滤用于搜索的字符串
function FilterSearch($keyword)

处理禁用HTML但允许换行的内容
function TrimMsg($msg)

获取单篇文档信息
function GetOneArchive($aid)

2.2、dedesql.class.php 数据库类
系统会自动载入 dedesql.class.php 文件，并用
$dsql = $db = new DedeSql(false);
进行初始化数据库连接，因此在工程所有文件中均不需要单独初始化这个类，可直接用 $dsql 或 $db 进行操作，为了防止错误，操作完后不必关闭数据库。

常用的方法：
1、执行一个非查询类型的SQL语句，如 insert 、create 、update 等
$rs = $db->ExecuteNoneQuery($sql);
返回值为是否执行成功。

2、执行一个非查询类型的SQL语句，并返回成功记录数
$rs = $db->ExecuteNoneQuery2($sql);

与上面相比，它返回的是影响的记录数，而不是布尔值

3、返回单个记录
$arr = $db->GetOne($sql);

$dsql 如果不带 limit ，系统会自动加上 limit 0,1

4、执行条件查询语句
1 $db->SetQuery($dsql);
2 $db->Execute();
3 while($arr = $db->GetArray())
4 {
5 }

可以简化为：
6 $db->Execute('me',$dsql);
7 while($arr = $db->GetArray())
8 {
9 }

'me' 为记录集游标，用于区分不同的查询，如：
10 $db->Execute('me',$dsql);
11 while($arr = $db->GetArray())
12 {
13 $db->Execute('2',$dsql2);
14 while($arr2 = $db->GetArray())
15 {
16
17 }
18 }

像这种情况必须指定一个值区分默认的'me'参数，否则会出错

$db->GetArray($rsid,$acctype) 参数
$rsid="me"
$acctype=MYSQL_ASSOC

在查询游标中读取数据还可以用
$db->GetObject($rsid="me");

返回的结果是用类结构表示的值。

5、获取上一个插入的自动递增主键id值
$db->GetLastID();

6、获得查询的总记录数
$db->GetTotalRow($rsid="me")

7、获得MySql的版本号
$db->GetVersion($isformat=true)
默认的情况下会转换成 x.xx 形式浮点数

8、析放某查询的资源

$db->FreeResult($rsid="me");

9、在数据库中是否存在某数据表
$db->IsTable($tbname)

10、重新选择要操作的数据库
$db->SelectDB($dbname);

11、获得数据库连接标识
$db->linkID
获得这个连接标识后，可以直接用mysql相关函数进行数据库操作
在非不得已的情况，项目中一般不使用这个变量。

2.3、datalistcp.class.php 动态分页类
类文件
include/datalistcp.class.php

适用范围：数据量不大的数据分页
使用方法：
1 $dl = new DataListCP();
2 $dl->pageSize = 25; //设定每页显示记录数（默认25条）
3 $dl->SetParameter($key,$value); //设定get字符串的变量

//这两句的顺序不能更换
4 $dl->SetTemplate($tplfile);?//载入模板
5 $dl->SetSource($sql);?//设定查询SQL
6
7 $dl->Display();?//显示

模板
8 {dede:datalist}<br />
9 <li>{field.fieldname1/} - {field.fieldname2/} ...</li><br />
10 {/dede:datalist}<br />
11 <br />
12 {tag:pagelist listitem="info,index,end,pre,next,pageno" listsize="5"/}

listitem、listsize 是可选属性
如果需要自定义 datalist 相关属性，可以继续本类来创建一个新类，只需改变 GetArcList($atts,$refObj='',$fields=array()) 方法即可。
2.4、dedetag.class.php 静态模板类
类文件
include/dedetag.class.php

这个文件是dedecms V5.3及之前版本使用的主要的模板类，它是解析式模板类，并非编译式的（区别是前者通过获得标签位置进行内容替换，后者是直接解析式PHP代码，二次执行）

一、模板语法
织梦模板引擎是一种使用XML名字空间形式的模板解析器，使用织梦解析器解析模板的最大好处是可以轻松的制定标记的属性，感觉上就像在用HTML一样，使模板代码十分直观灵活，新版的织梦模板引擎不单能实现模板的解析还能分析模板里错误的标记。
1、织梦模板引擎的代码样式有如下几种形式：
{dede:标记名称 属性='值'/}
{dede:标记名称 属性='值'}{/dede:标记名称}
{dede:标记名称 属性='值'}自定义样式模板(InnerText){/dede:标记名称}
提示：
如果使用带底层模板的标记，必须严格用{dede:标记名称 属性='值'}{/dede:标记名称} 这种格式，否则会报错。
2、织梦模板引擎内置有多个系统标记，这些系统标记在任何场合都是能直接使用的。
(1) global 标记，表示获取一个外部变量，除了数据库密码之外，能调用系统的任何配置参数，形式为：
{dede:global name='变量名称'}{/dede:global}
或
{dede:global name='变量名称'/}
其中变量名称不能加 $ 符号，如变量 $cfg_cmspath ，应该写成 {dede:global name='cfg_cmspath'/} 。
(2) foreach 用来输出一个数组，形式为：
{dede:foreach array='数组名称'}[field:key/] [field:value/]{/dede:foreach}
(3) include 引入一个文件，形式为：
{dede:include file='文件名称' ismake='是否为dede板块模板(yes/no)'/}
对文件的搜索路径为顺序为：绝对路径、include文件夹，CMS安装目录，CMS主模板目录
3、织梦标记允许在任何标记中使用函数对得到的值进行处理，形式为：
{dede:标记名称 属性='值' function='youfunction("参数一","参数二","@me")'/}
其中 @me 用于表示当前标记的值，其它参数由你的函数决定是否存在，例如：
{dede:field name='pubdate' function='strftime("%Y-%m-%d %H:%M:%S","@me")'/}

4、织梦标记允许有限的编程扩展。
格式为：
{dede:tagname runphp='yes'}
$aaa = @me;
@me = "123456";
{/dede:tagname}
@me 表示这个标记本身的值，因此标记内编程是不能使用echo之类的语句的，只能把所有返回值传递给@me。
此外由于程序代码占用了底层模板InnerText的内容，因此需编程的标记只能使用默认的InnerText。
二、解析方式
在 dedetag.class.php 里面有四个类
class DedeAttribute 属性结构表述
class DedeAttributeParse 属性解析器
class DedeTag 标签结构表述
class DedeTagParse 标签解析器
使用解析类解析模板时一般经过下面的步骤
1、初始化：
$dtp = new DedeTagParse();
2、载入模板/模板字符串：
$dtp->LoadTemplate(模板文件（绝对路径）); //会生成缓存，第二次不需解析模板
或$dtp->LoadSource(字符串);
3、给标签赋值
foreach($dtp->CTags as $tid=>$ctag) {
//判断ctag的名称和属性，并给赋不同的值，通常用函数处理
if($ctag->GetName=='mytag') $dtp->Assign($tid, mytagvalue($ctag) ); }
在上面例子中，直接把名称为 mytag的标签转交给 mytagvalue 函数处理，mytagvalue 里判断$ctag的各个属性，返回不同内容即可。
在 V5.3版本中，通常除了field、list等专用标签之外，凡arc.*开头的类解析的文件，标签都是对应该 include/taglib 的源码的，这个由系统进行了自动的映射。
4、显示或保存为HTML
$dtp->display();
或
$dtp->SaveTo(静态文件名);
对于二次开发人员而言，不大需要知道dedecms模板具体解析方式，不过应该十分清楚CTag这个类的结构，从而判断标签不同属性进行处理。
1 class DedeTag
2 {
3 var $IsReplace=FALSE; //标记是否已被替代，供解析器使用
4 var $TagName=""; //标记名称
5 var $InnerText=""; //标记之间的文本
6 var $StartPos=0; //标记起始位置
7 var $EndPos=0; //标记结束位置
8 var $CAttribute=""; //标记属性描述,即是class DedeAttribute
9 var $TagValue=""; //标记的值
10 var $TagID = 0;
11
12 //获取标记的名称和值
13 function GetName()
14 {
15 return strtolower($this->TagName);
16 }
17
18 function GetValue()
19 {
20 return $this->TagValue;
21 }
22
23 //下面两个成员函数仅是为了兼容旧版
24 function GetTagName()
25 {
26 return strtolower($this->TagName);
27 }
28
29 function GetTagValue()
30 {
31 return $this->TagValue;
32 }
33
34 //获取标记的指定属性
35 function IsAttribute($str)
36 {
37 return $this->CAttribute->IsAttribute($str);
38 }
39
40 function GetAttribute($str)
41 {
42 return $this->CAttribute->GetAtt($str);
43 }
44
45 function GetAtt($str)
46 {
47 return $this->CAttribute->GetAtt($str);
48 }
49
50 function GetInnerText()
51 {
52 return $this->InnerText;
53 }
54 }

2.5、dedetemplate.class.php 动态模板类
核心类文件
include/dedetemplate.class.php
用途：用于非核心模块的动态页面或列表页的模板解析，如：member/content_list.php ，通常是在 datalistcp.class.php 中使用，这个类在动态运行的情况下，由于本身是把模板编译成PHP的，因此性能上会优级于旧的解析类，这个方法将在未来版本中作为通用的方式。

一、使用方法：

$tpl = new DedeTemplate(
模板对象实例名称，通常是'tpl',
[模板存放目录（生成缓存时会存放在这个目录）,
include语法默认引用目录]
);
通常情况下参数二和参数三是不必要的，如：
$tpl = new DedeTemplate('tpl');

如果在类文件中调用，应该加上设置：
$this->tpl->SetObject($this);
在一些块调用中默认将使用当前类的成员函数。

$tpl->LoadTemplate(模板的物理路径);

如果模板中带有 {dede:config name='' value=''/}
可以在载入模板后，通过 $tpl->GetConfig($name) 获得这些变量的值。

显示页面或保存页面为文件
$tpl->Display();
$tpl->SaveTo(物理绝对路径的文件名);

二、模板标记语法

1、标记通用特性
(1) 短标记
{dede:tagname.name/}
等同于
{dede:tagname name='' /}
(2) 块标记
{dede:tagname}
循环代码
{/dede:tagname}

2、标记的具体语法及对应的PHP代码
(1) 配置变量
{dede:config name='' value=''/}
配置变量可以在载入模板后通过 $tpl->GetConfig($name) 获得，仅作为配置，不在模板中显示。

(2) 短标记

{dede:global.name/} 外部变量 等同于 <?php echo $name; ?>
{dede:var.name/} var数组 等同于 <?php echo $_vars['name']; ?>
{dede:field.name/} field数组 等同于 <?php echo $fields['name']; ?>
{dede:cfg.name/} 系统配置变量 等同于 <?php echo $cfg_name; ?>

考虑到大多数情况下都会在函数或类中调用模板，因此 $_vars、$fields 数组必须声明为 global 数组，否则模板引擎无法获得它的值从而导致产生错误。

(3) 自由调用块标记
{tag:blockname bind='GetArcList' bindtype='class'}
循环代码
{/tag:blockname}

必要属性：
bind 数据源来源函数
bindtype 函数类型，默认是 class 可选为 sub
rstype 返回结果类型，默认是 array ，可选项为 string

自定义函数格式必须为 function(array $atts,object $refObj, array $fields);
在没有指定 bind 绑定的函数的情况下，默认指向 MakePublicTag($atts,$tpl->refObj,$fields) 统一管理，这个函数存放在 cls_dede_tplinc.php 。

(4) 固定块标记

[1] datalist
从绑定类成员函数GetArcList中获取数组并输出
{dede:datalist}
循环代码
{/dede:datalist}
遍历一个二给维数组，数据源是固定的，只适用用类调用。
等同于
{tag:blockname bind='GetArcList' bindtype='class' rstype='arrayu'}
循环代码
{/tag:blockname}

[2] label
从绑定函数中获取字符串值并输出
等同于 {tag:blockname bind='func' bindtype='sub' rstype='string'/}

[3] pagelist

从绑定类成员函数GetPageList中获取字符串值并输出
等同于 {tag:blockname bind='GetPageList' bindtype='class' rstype='string'/}

(5) include 语法
{dede:include file=''/}
{dede:include filename=''/}

(6) php 代码块
{dede:php
php 代码
/}
或
{dede:php}
php代码
{/dede:php}

(7) if 条件
仅支持 if ，else ，else 直接用{else}表示,但不支持{else if}这样的语法 ，一般建议模板中不要使用太复杂的条件语法，如果确实有需要，可以直接使用 php 语法。

{dede:if 条件} a-block {else} b-block {/dede:if}

条件中允许使用 var.name 、 global.name 、 field.name、cfg.name 表示相应的变量。

如：
{dede:if field.id>10 }
{/dede:if}

(8) 遍历一个 array 数组

{dede:array.name}
{dede:key/} = {dede:value/}
{/dede:array}

各种语法的具体编译后的代码，可查看 dede-template-class.php 的 function CompilerOneTag(&$cTag)。

块调用示例代码：
1、示例一
1 {tag:datalist timeformat=""}<br />
2 <tr><br />
3 <td class='col1'><br />
4 <div>?<a href='{tag:field.arcurl/}'>{tag:field.title/}</a></div><br />
5 <!--div class='descriptions'>&nbsp;&nbsp;&nbsp;&nbsp;{tag:field.description function="CnSubstr(@me,150)"/}...</div--><br />
6 </td><br />
7 <td class='col2'>{tag:field.formattime/}</td><br />
8 </tr><br />
9 {/tag:datalist}

编译后的代码
10 <?php
11 $atts = array();
12 $atts['tagname'] = 'datalist';
13 $atts['timeformat'] = '';
14 $blockValue = $this->refObj->GetArcList($atts,$this->refObj,$fields);
15 foreach( $blockValue as $key=>$fields )
16 {
17 ?>
18 <tr>
19 <td class='col1'>
20 <div>?<a href='<?php echo $fields['arcurl']; ?>'><?php echo $fields['title']; ?></a></div>
21 <!--div class='descriptions'>&nbsp;&nbsp;&nbsp;&nbsp;<?php echo CnSubstr($fields['description'],150); ?>...</div-->
22 </td>
23 <td class='col2'><?php echo $fields['formattime']; ?></td>
24 </tr>
25 <?php
26 }
27 ?>
28

2、示例二
29 {tag:article sort='new' titlelen='36' row='10'}<br />
30 <dd>[{tag:field.typename/}]<a href="{tag:field.arcurl/}">{tag:field.title function="CnSubstr(@me,24)"/}</a></dd><br />
31 {/tag:article}

编译后的代码
32 <?php
33 $atts = array();
34 $atts['tagname'] = 'article';
35 $atts['sort'] = 'new';
36 $atts['titlelen'] = '36';
37 $atts['row'] = '10';
38 $blockValue = MakePublicTag($atts,$this->refObj,$fields);
39 if(is_array($blockValue) && count($blockValue) > 0){
40 foreach( $blockValue as $key=>$fields )
41 {
42 ?>
43 <dd>[<?php echo $fields['typename']; ?>]<a href="<?php echo $fields['arcurl']; ?>"><?php echo CnSubstr($fields['title'],24); ?></a></dd>
44 <?php
45 }
46 }
47 ?>
48

三、 数据库篇
dede_archives|文档主表
字段
类型
整理
属性
Null
默认
额外
id
mediumint(8)

UNSIGNED
是
0
文档ID
typeid
smallint(8)

UNSIGNED
是
0
栏目ID
sortrank
in