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 2 field:title/ 3 field:description/.查看全文 4 /dede:arclist 上面的dede:arclist和/dede:arclist成对出现在模板文件中，并且在两个标签当中包含了底层模板(innertext)。底层模板（Innertext），底层模板实际上就是对于有多条记录的模板输出，用户手工去指定单个记录的样式。标签还有一类出现形式是dede:*/，通常以这种形式出现都是输出变量、或者不含底层模板的内容。例如：1-2dede:global.cfg_webname/dede:arclist flag=h limit=0,1/如果用户没有指定单个记录的样式，系统部分标签都含有默认的底层模板，具体可以查看cmapath/templets/system/文件夹下面的文件，这里面都是系统的底层模板文件。 注释织梦标签的模板注释非常灵活，可以通过标签后面的commet属性进行赋值。例1-3：1dede:arclist flag=h limit=0,1 commet=调用头条的第一篇内容 2field:titlecommet=这是文章标题标签/ 3field:description commet=这是摘要标签/.查看全文 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 2 $aaa = me; 3 me = 123456; 4 /dede:tagname me 表示这个标记本身的值，因此标记内编程是不能使用echo之类的语句的，只能把所有返回值传递给me。此外由于程序代码占用了底层模板InnerText的内容，因此需编程的标记只能使用默认的InnerText。 2、 代码篇2.1、common.func.php 公用函数获得当前的脚本网址function GetCurUrl()返回格林威治标准时间function MyDate($format=Y-m-d H:i:s,$timest=0)把全角数字转为半角function GetAlabNum($fnum)把含HTML的内容转为纯textfunction Html2Text($str,$r=0)把文本转HTMLfunction 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)获得用户IPfunction GetIP()获取拼音以gbk编码为准function GetPinyin($str,$ishead=0,$isclose=1)dedecms通用消息提示框function ShowMsg($msg,$gourl,$onlymsg=0,$limittime=0)保存一个cookiefunction PutCookie($key,$value,$kptime=0,$pa=/)删除一个cookiefunction DropCookie($key)获取cookiefunction GetCookie($key)获取验证码function GetCkVdValue()过滤前台用户输入的文本内容/ $rptype = 0 表示仅替换 html标记/ $rptype = 1 表示替换 html标记同时去除连续空白字符/ $rptype = 2 表示替换 html标记同时去除所有空白字符/ $rptype = -1 表示仅替换 html危险的标记function HtmlReplace($str,$rptype=0)获得某文档的所有tagfunction 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,14、执行条件查询语句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 9 field.fieldname1/ - field.fieldname2/ . 10 /dede:datalist 11 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:tagnameme 表示这个标记本身的值，因此标记内编程是不能使用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:/等同于dede:tagname name= /(2) 块标记dede:tagname循环代码/dede:tagname2、标记的具体语法及对应的PHP代码(1) 配置变量dede:config name= value=/配置变量可以在载入模板后通过 $tpl-GetConfig($name) 获得，仅作为配置，不在模板中显示。(2) 短标记dede:/ 外部变量 等同于 dede:/ var数组 等同于 dede:/ field数组 等同于 dede:/ 系统配置变量 等同于 考虑到大多数情况下都会在函数或类中调用模板，因此 $_vars、$fields 数组必须声明为 global 数组，否则模板引擎无法获得它的值从而导致产生错误。(3) 自由调用块标记tag:blockname bind=GetArcList bindtype=class循环代码/tag:blockname必要属性：bind 数据源来源函数bindtype 函数类型，默认是 class 可选为 subrstype 返回结果类型，默认是 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:blockname2 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:phpphp 代码/或dede:phpphp代码/dede:php(7) if 条件仅支持 if ，else ，else 直接用else表示,但不支持else if这样的语法 ，一般建议模板中不要使用太复杂的条件语法，如果确实有需要，可以直接使用 php 语法。dede:if 条件 a-block else b-block /dede:if条件中允许使用 、 、 、 表示相应的变量。如：dede:if field.id10 /dede:if(8) 遍历一个 array 数组dede: dede:key/ = dede:value/dede:array各种语法的具体编译后的代码，可查看 dede-template-class.php 的 function CompilerOneTag(&$cTag)。块调用示例代码：1、示例一1 tag:datalist timeformat= 2 3 4 ?tag:field.title/ 5     tag:field.description function=CnSubstr(me,150)/. 6 7 tag:field.formattime/ 8 9 /tag:datalist 编译后的代码10 refObj-GetArcList($atts,$this-refObj,$fields); 15 foreach( $blockValue as $key=$fields ) 16 17 ? 18 19 20 ?a href= 21     . 22 23 24 25 28 2、示例二29 tag:article sort=new titlelen=36 row=10 30 tag:field.typename/tag:field.title function=CnSubstr(me,24)/ 31 /tag:article 编译后的代码32 refObj,$fields); 39 if(is_array($blockValue) & count($blockValue) 0) 40 foreach( $blockValue as $key=$fields ) 41 42 ? 43 a href= 44 48 3、 数据库篇dede_archives|文档主表字段类型整理属性Null默认额外idmediumint(8) UNSIGNED是0文档IDtypeidsmallint(8) UNSIGNED是0栏目IDsortrankint(10) UNSIGNED是0时间排序flagset(c,h,p,f,s,j,a,b)utf8_general_ci 是NULL自定义属性值ismakesmallint(6) 是0是否审核channelsmallint(6) 是1所属模型IDarcranksmallint(6) 是0阅读权限clickmediumint(8) UNSIGNED是0点击数moneysmallint(6) 是0消费点数titlechar(60)utf8_general_ci 是 标题shorttitlechar(36)utf8_general_ci 是 简明标题colorchar(7)utf8_general_ci 是 颜色writerchar(20)utf8_general_ci 是 作者sourcechar(30)utf8_general_ci 是 文档来源litpicchar(60)utf8_general_ci 是 缩略图pubdateint(10) UNSIGNED是0时间senddateint(10) UNSIGNED是0时间midmediumint(8) UNSIGNED是0会员IDkeywordschar(30)utf8_general_ci 是 关键词templetchar(30)utf8_general_ci 是 lastpostint(10) UNSIGNED是0最后回复scoresmediumint(8) UNSIGNED是0阅读权限goodpostmediumint(8) UNSIGNED是0好评badpostmediumint(8) UNSIGNED是0差评notposttinyint(1) UNSIGNED是0评论选项（1：充许评论）useripchar(15)utf8_general_ci 是 IPredirecturlvarchar(255)utf8_general_ci 是 跳转地址descriptionvarchar(255)utf8_general_ci 是 摘要dede_addonarticle|文章附加表字段类型整理属性Null默认额外aidmediumint(8)UNSIGNED否0文档IDtypeidsmallint(5) UNSIGNED否0栏目IDbodymediumtextutf8_general_ci是NULL内容dede_addonimages|图片附加表字段类型整理属性Null默认额外aidmediumint(8) UNSIGNED否0文档IDtypeidsmallint(5) UNSIGNED否0栏目IDpagestylesmallint(6) 否1表现方式（多页多图显示、多页单图显示、多行多列显示）maxwidthsmallint(6) 否600图片宽度限制imgurlstextutf8_general_ci 是NULL图片内容（dede:pagestyle）rowsmallint(6) 否0多列式参数（行）colsmallint(6) 否0多列式参数（列）isrmsmallint(6) 否0特殊选项（下载远程图片、从ZIP压缩包中解压图片、网上复制图片）ddmaxwidthsmallint(6) 否200缩略图宽度限制pagepicnumsmallint(6) 否12每页图片数（单页多图显示需要设置此参数）dede_addonshop|商品附加表字段类型整理属性Null默认额外aidmediumint(8) UNSIGNED否0文档idtypeidsmallint(5) UNSIGNED否0栏目idbodymediumtextutf8_general_ci 是NULL商品内容pricefloat 否0价格truepricefloat 否0优惠价brandvarchar(250)utf8_general_ci 否 品牌unitsvarchar(250)utf8_general_ci 否 单位dede_addonsoft|软件附加表字段类型整理属性Null默认额外aidmediumint(8) UNSIGNED否0文档IDtypeidsmallint(5) UNSIGNED否0栏目IDfiletypevarchar(10)utf8_general_ci 否 文件类型（zip、rar）languagevarchar(10)utf8_general_ci 否 软件语言softtypevarchar(10)utf8_general_ci 否 软件类型（国产.）accreditvarchar(10)utf8_general_ci 否 授权方式（共享软件.）osvarchar(30)utf8_general_ci 否 运行环境（windows.）softrankmediumint(8) UNSIGNED否0软件等级（一星.）officialUrlvarchar(30)utf8_general_ci 否 官方网址officialDemovarcha