Destoon标签(tag)调用手册
发表：DESTOON模板堂(dtmoban.com)
发表时间：2015-02-04
什么是标签调用？
标签调用是根据调用条件(condition)从数据表(table)读取调用数量(pagesize)条数据，并按排序方式(order)排序，最终通过标签模板的布局输出数据。
可以看出，标签的工作分两个部分，一是读取数据，二是显示数据。
标签函数原型
标签函数保存于 include/tag.func.php
例如传递 table=destoon&pagesize=10&hello=world
系统相当于得到：
$table = 'destoon';
$pagesize = 10;
$hello = 'world';
三个变量
$expires 表示标签缓存过期时间
>0 缓存$expires秒；0 - 系统默认标签缓存时间；-1 - 不缓存；-2 - 缓存SQL结果；
一般情况保持默认不需要传递。
数据读取过程
例如以下标签：
通常情况下不需要写table=xxx，应该写moduleid=模块ID，系统会自动对应模块的表
数据显示过程
1、通过标签模板显示
传递&template=abc给标签函数，例如：
如果标签模板存放于其他目录，例如def，则传递&dir=def&template=abc，系统将调用模板目录/def/abc.htm模板。
2、直接在模板里循环数据
以下为一个完整的示例：
第一种写法一般用于多次调用的数据，第二种写法一般用于只调用一次的数据。
常用参数及含义
moduleid
moduleid指模块ID，可在后台模块管理里查询。对于直接调用模块的数据，设置正确的模块ID后，将不需要传递table参数，系统会自动获取。
例如传递moduleid=5，系统将识别为调用供应信息，自动设置table参数为sell。
一般情况下，除了扩展模块里的功能都需要通过moduleid来调用。
table
table指表名，可在后台数据库维护里查询。对于Destoon系统表，不需要加表的前缀；对于非Destoon系统表，需要填写完整的表名，且传递prefix参数。
例如对于Destoon系统表，传递table=announce，如果表前缀为DT_，系统将识别表名为 DT_announce。
对于非Destoon系统表，传递table=tb_abc&prefix=或者table=abc&prefix=tb_，系统将识别表名为 tb_abc。
fields
fields指查询的字段，默认为*。可以传递例如 fields=title,addtime，但是一般情况下无需传递，Destoon独有的标签缓存机制会自动缓存查询结果，不必担心效率问题。
condition
condition指查询的条件，如果不传递，则为1，代表任意条件的数据(此项需了解SQL语法)。Destoon所有模块遵循统一标准开发，所以很多条件是通用的。
例如 status=3表示正常通过的信息、status=3 and level=1表示级别为1的信息、status=3 and thumb<>''表示有标题图片的信息等。
order
order指数据的排序方法(此项需了解SQL语法)。
例如order=addtime desc表示按添加时间降序排列、order=itemid desc表示按itemid降序排列、order=rand()表示随机数据等。
pagesize
pagesize指调用数据的数量，如果不传递，默认为10。
template
template指指定的标签模板，如果不传递，默认为list，位于模板目录/tag/list.htm，如果传递为null，表示不应用标签模板。参见上述数据显示过程。
debug
debug参数用于调试标签，例如传递&debug=1，系统将输出标签构造成的SQL语句，以便验证标签写法是否正确，不需要调试的标签不用加此参数。
数据字典
参考：http://help.destoon.com/dict.php
其他常见用法举例
&和and的区别
&用来分割参数，and是sql语句wher后的读取条件，二者完全不同。
多表联合查询
例如查询会员名为destoon的会员和公司资料，可以使用：
{tag("table=DT_member m,DT_company c&prefix=&condition=m.userid=c.userid and m.username='destoon'&template=list-com")}
DT_member和DT_company是表的实际名称(包含表前缀)，prefix=表示系统不再自动在表名前加前缀。
通常通过传递moduleid可以实现大部分的调用，除非您确认熟悉联合查询，否则不推荐使用。
截至目前，系统默认模板里还没有一个功能需要用到联合查询。
控制标题长度
在标签里传递length参数，例如&length=20表示20个字符长度(一个汉字占2个字符)，一般情况建议用css隐藏多余字符(定义height和overflow:hidden)。
传递length参数，系统仅对title字段自动截取，如果需要截取其他字段，可用dsubstr函数。
例如 {dsubst($t[company], 20, '...')} 表示截取company字段为20个字符，截取后，结尾追加...
设置日期显示格式
可以在标签里传递datetype参数：
1 表示 年；
2 表示 月-日；
3 表示 年-月-日；
4 表示 月-日 时:分；
5 表示 年-月-日 时:分；
6 表示 年-月-日 时:分:秒
也可以在模板里直接使用date函数，例如{date('Y-m-d', $t[addtime])} 表示将时间转换为 年-月-日 格式
date函数的使用请参阅PHP手册。
调用某一分类的信息
在标签里传递catid参数，例如&catid=5表示调用分类ID为5的所有信息。
如果调用多个分类，用逗号分隔分类ID，例如 &catid=5,6,7表示调用分类ID为5、6、7的所有信息。
分类调用默认包含子分类的信息，如果不需要包含子分类，可设置&child=0参数。
例如&catid=5&child=0表示只调用分类ID为5的信息，不包括子分类的信息。
调用某一地区的信息
调用地区信息和上述调用分类信息的方法完全相同，将其中的catid换为areaid即可。
显示信息所在分类
<a href="{$MODULE[$moduleid][linkurl]}{$CATEGORY[$t[catid]][linkurl]}">{$CATEGORY[$t[catid]][catname]}</a>
注意：自V4.0，以上写法将不可用，需要在标签里传递&showcat=1参数，然后在模板里写<a href="{$t[caturl]}">{$t[catname]}</a>
控制列数
此项常用于图片的布局，可使用cols参数。
例如调用12张图片，一行显示4个，共3行，则传递&pagesize=12&cols=4
支持cols参数的标签模板限thumb-table.htm和list-table.htm
其中，thumb-table.htm显示图片列表，list-table.htm显示文字列表
如果新建支持cols的标签模板或直接循环$tags，可参考以上两个模板的写法
上述效果可以也可以通过CSS实现，无需使用表格，请自行书写
显示文章的简介
使用{$t[introduce]}变量，如果要截取字数，例如80字符，可使用{dsubst($t[introduce], 80, '...')}
标签调用是根据调用条件(condition)从数据表(table)读取调用数量(pagesize)条数据，并按排序方式(order)排序，最终通过标签模板的布局输出数据。
可以看出，标签的工作分两个部分，一是读取数据，二是显示数据。
标签函数原型
标签函数保存于 include/tag.func.php
tag($parameter, $expires = 0)
$parameter 表示传递给tag函数的字符串，系统自动将其转换为多个变量。例如传递 table=destoon&pagesize=10&hello=world
系统相当于得到：
$table = 'destoon';
$pagesize = 10;
$hello = 'world';
三个变量
$expires 表示标签缓存过期时间
>0 缓存$expires秒；0 - 系统默认标签缓存时间；-1 - 不缓存；-2 - 缓存SQL结果；
一般情况保持默认不需要传递。
数据读取过程
例如以下标签：
<!--{tag("moduleid=5&condition=status=3&order=addtime desc&pagesize=10")}-->
会被转换为如下的SQL语句：selec *
FROM DT_sell
wher status=3
ORDER BY addtime DESC
LIMIT 0,10
读出的数据会保存在 $tags 数组里FROM DT_sell
wher status=3
ORDER BY addtime DESC
LIMIT 0,10
通常情况下不需要写table=xxx，应该写moduleid=模块ID，系统会自动对应模块的表
数据显示过程
1、通过标签模板显示
传递&template=abc给标签函数，例如：
<!--{tag("moduleid=...&template=abc")}-->
默认的标签模板保存在模板目录/tag/目录里，例如&template=abc将调用模板目录/tag/abc.htm模板来显示数据。如果标签模板存放于其他目录，例如def，则传递&dir=def&template=abc，系统将调用模板目录/def/abc.htm模板。
2、直接在模板里循环数据
<!--{php $tags=tag("moduleid=...&template=null");}-->
此写法传递标签模板为null，并且直接返回数据给$tags数组，此时可以直接在模板里循环了。以下为一个完整的示例：
<!--{php $tags=tag("moduleid=...&template=null");}-->
{loop $tags $t}
...
{/loop}
{loop $tags $t}
...
{/loop}
第一种写法一般用于多次调用的数据，第二种写法一般用于只调用一次的数据。
常用参数及含义
moduleid
moduleid指模块ID，可在后台模块管理里查询。对于直接调用模块的数据，设置正确的模块ID后，将不需要传递table参数，系统会自动获取。
例如传递moduleid=5，系统将识别为调用供应信息，自动设置table参数为sell。
一般情况下，除了扩展模块里的功能都需要通过moduleid来调用。
table
table指表名，可在后台数据库维护里查询。对于Destoon系统表，不需要加表的前缀；对于非Destoon系统表，需要填写完整的表名，且传递prefix参数。
例如对于Destoon系统表，传递table=announce，如果表前缀为DT_，系统将识别表名为 DT_announce。
对于非Destoon系统表，传递table=tb_abc&prefix=或者table=abc&prefix=tb_，系统将识别表名为 tb_abc。
fields
fields指查询的字段，默认为*。可以传递例如 fields=title,addtime，但是一般情况下无需传递，Destoon独有的标签缓存机制会自动缓存查询结果，不必担心效率问题。
condition
condition指查询的条件，如果不传递，则为1，代表任意条件的数据(此项需了解SQL语法)。Destoon所有模块遵循统一标准开发，所以很多条件是通用的。
例如 status=3表示正常通过的信息、status=3 and level=1表示级别为1的信息、status=3 and thumb<>''表示有标题图片的信息等。
order
order指数据的排序方法(此项需了解SQL语法)。
例如order=addtime desc表示按添加时间降序排列、order=itemid desc表示按itemid降序排列、order=rand()表示随机数据等。
pagesize
pagesize指调用数据的数量，如果不传递，默认为10。
template
template指指定的标签模板，如果不传递，默认为list，位于模板目录/tag/list.htm，如果传递为null，表示不应用标签模板。参见上述数据显示过程。
debug
debug参数用于调试标签，例如传递&debug=1，系统将输出标签构造成的SQL语句，以便验证标签写法是否正确，不需要调试的标签不用加此参数。
数据字典
参考：http://help.destoon.com/dict.php
其他常见用法举例
&和and的区别
&用来分割参数，and是sql语句wher后的读取条件，二者完全不同。
多表联合查询
例如查询会员名为destoon的会员和公司资料，可以使用：
{tag("table=DT_member m,DT_company c&prefix=&condition=m.userid=c.userid and m.username='destoon'&template=list-com")}
DT_member和DT_company是表的实际名称(包含表前缀)，prefix=表示系统不再自动在表名前加前缀。
通常通过传递moduleid可以实现大部分的调用，除非您确认熟悉联合查询，否则不推荐使用。
截至目前，系统默认模板里还没有一个功能需要用到联合查询。
控制标题长度
在标签里传递length参数，例如&length=20表示20个字符长度(一个汉字占2个字符)，一般情况建议用css隐藏多余字符(定义height和overflow:hidden)。
传递length参数，系统仅对title字段自动截取，如果需要截取其他字段，可用dsubstr函数。
例如 {dsubst($t[company], 20, '...')} 表示截取company字段为20个字符，截取后，结尾追加...
设置日期显示格式
可以在标签里传递datetype参数：
1 表示 年；
2 表示 月-日；
3 表示 年-月-日；
4 表示 月-日 时:分；
5 表示 年-月-日 时:分；
6 表示 年-月-日 时:分:秒
也可以在模板里直接使用date函数，例如{date('Y-m-d', $t[addtime])} 表示将时间转换为 年-月-日 格式
date函数的使用请参阅PHP手册。
调用某一分类的信息
在标签里传递catid参数，例如&catid=5表示调用分类ID为5的所有信息。
如果调用多个分类，用逗号分隔分类ID，例如 &catid=5,6,7表示调用分类ID为5、6、7的所有信息。
分类调用默认包含子分类的信息，如果不需要包含子分类，可设置&child=0参数。
例如&catid=5&child=0表示只调用分类ID为5的信息，不包括子分类的信息。
调用某一地区的信息
调用地区信息和上述调用分类信息的方法完全相同，将其中的catid换为areaid即可。
显示信息所在分类
<a href="{$MODULE[$moduleid][linkurl]}{$CATEGORY[$t[catid]][linkurl]}">{$CATEGORY[$t[catid]][catname]}</a>
注意：自V4.0，以上写法将不可用，需要在标签里传递&showcat=1参数，然后在模板里写<a href="{$t[caturl]}">{$t[catname]}</a>
控制列数
此项常用于图片的布局，可使用cols参数。
例如调用12张图片，一行显示4个，共3行，则传递&pagesize=12&cols=4
支持cols参数的标签模板限thumb-table.htm和list-table.htm
其中，thumb-table.htm显示图片列表，list-table.htm显示文字列表
如果新建支持cols的标签模板或直接循环$tags，可参考以上两个模板的写法
上述效果可以也可以通过CSS实现，无需使用表格，请自行书写
显示文章的简介
使用{$t[introduce]}变量，如果要截取字数，例如80字符，可使用{dsubst($t[introduce], 80, '...')}
