主题	描述
• 简介
基本原理
安装
小示例
• PHP 方面
• 开始
方法 LoadTemplate()	从文件加载模板内容
方法 MergeBlock()	将部分数据源合并入模板
方法 Show()	自动处理和显示结果
• 高级
方法 CacheAction()	为合并结果激活缓存系统
方法 GetBlockSource()	返回定义块的源数据
方法 MergeField()	把一个特定的字段和一个值合并(用一个值替换掉原模板里的值,后译)
方法 MergeNavigationBar()	合并入导航栏
方法MergeSpecial()	合并自动字段, PHP 变量, 和其它...
特性 Render	改变合并的结尾选项
特性 Source	返回这个结果的当然内容
特性 TplVars	返回模板变量
添加一个数据源类型	生成一个 TBS 认可的新数据库类型
面向对象编程 (OOP)	使 TBS 友好支持 OOP
• HTML 方面
• TBS 字段
定义和语法
参数
Var 字段
特定 Var 字段
• TBS 块
定义和语法
参数
闭合的块
连续显示 (应用于栏)
动态查询 / 子块
显示导航条(分页?)
• 混合
自动的字段和块
子模板
有条件的显示汇总
• 概要
TBS 字段的参数
TBS 块的参数
分页导航的字段和参数
特殊的字段名和块名

加载一个模板以便替换和处理.
文件全部内容将被保存于TBS 对象源中.

语法:

$TBS->LoadTemplate(string File{, string HtmlCharSet})

参数	描述
File	使用本地或绝对路径加载文件.
HtmlCharSet	可选. 指定Indicates the character encoding (charset) to use for Html conversion of the data when they will be merged. It should be the same as the charset of the template. The default value is '' (empty string) which is equivalent to 'ISO-8859-1' (Latin 1). 假如模板使用一个特殊的字符集,那么你需要给这个字符集指出html值. 在 Html 页面中, 字符集往往放在文件的开头处, 属于<Meta>标签的'content' 部分. TBS 支持PHP 函数 htmlentities() 所支持的所有字符集. 例如: 'BIG5' (繁体中文) 或'EUCJP' (日文).

不转换Html:
假如你使用False 做为 HtmlCharSet 的参数, 当合并数据时将不进行转码.

使用函数:
假如你使用了尚未被 PHP 支持的字符集, 你可以指出自定义函数来完成Html 转换. 在这里, 参数 HtmlCharSet 使用语法 '=用户自定义函数名'.
用户自定义函数必需包含一个字符串参数[像这样abc($string="");], 并能返回一个转换后的字串.

在当前模板末添加文件:
你可以使用'+'代替字符集将文件添加在当前模板文件后,字符集参数与第一个模板一样.

从一个数据源合并一个或几个 TBS 块 .
返回最后显示的记录数(从1开始计数[而不是0]).

TinyButStrong 天生就支持的几个数据源类型:
Php 数据: 一个数组, 字串, 数字.
数据库: MySQL ; PostgreSQL ; SQLite.
当然,你也可以自己添加数据源类型: '添加数据源类型'.

要使用'By Page'模式, 参见下述.

语法: int $TBS->MergeBlock(string BlockName, mixed Source{, string Query}{, int PageSize, int PageNum}{, int RecCount})

参数	描述
BlockName	指定合并时TBS 块 名. 一个数据源可以复制为几个块,只要使用逗号分隔块名.
Source	指定合并时的数据源. 根据数据源类型,显示下表中可能出现的值.
Query	可选. 指定返回合并记录的 SQL 声明.(原文:Indicates the SQL statement which returns the records to merge.) 根据数据源类型,显示下表中可能出现的值.
PageSize	可选. 此参数仅在定义分页模式后才可用. 指定一页显示多少条记录.
PageNum	可选. 此参数仅在定义分页模式后才可用. 指定显示哪一页. 第一页是 1. 如果指定为-1 将显示最后一页.
RecCount	可选. 此参数仅在定义分页模式 后才可用. 他允许调整MergeBlock()方法返回的数字结果.(原文:It allows to adjust the calculation of the number of records returned by the MergeBlock() method.) RecCount 方法 MergeBlock() 的返回值 0 : 默认值. 此方法返回最后记录数显示在需要的页面上.(原文:The method returns the number of the last record displayed in the required page.) -1 : 此方法读取返回的所有记录一直到最后的总数,然而, 仅在被要求的页面上显示记录. >0 : 方法返回的RecCount 值. 然后, 假如RecCount这个值超过自定值,它将返回需要页面的最后记录数.(原文:it will return the number of the last record in the required page if it's higher than .) 使用此参数为了计算和保存记录总数. 例子: if (isset($_POST['nbr_rec'])) {   $nbr_rec = $_POST['nbr_rec'] ; } else {   $nbr_rec = -1 ; } $nbr_rec = $TBS->MergeBlock('blk1',$cnx_id,'select * from t_country',$p_size,$p_num,$nbr_rec);

从相同的数据中同时合并多个块:

统计记录数:

数据源类型	Source	Query
Text (*)	关键字 'text'	A text
Number (*)	关键字'num'	A number or a special array (see below)
Clear (*)	关键字'clear'	-
Conditional (*)	关键字'cond'	-
PHP Array (*)	一个PHP数组	-
	关键字'array'	A Php Array
	关键字'array'	A string that represents an array contained or nested in a PHP global variable (see below)
MySQL	一个 MySql 连接标识符或关键字 'mysql'	An SQL statement
	一个 MySql 结果标识符	-
PostgreSQL	一个 PostgreSql 连接标识符	An SQL statement
	一个 PostgreSql 结果标识符	-
SQLite	一个 SQLite 连接标识符	An SQLite statement
	一个 SQLite 结果标识符	-
custom	A keyword, an object or a resource identifier not mentioned in this table. See the chapter 'adding a data source type'.	An SQL statement or something else.

(*) 参见以下章节的解释.



分页模式:

结束合并.

Syntax: $TBS->Show({int Render})

Show 方法将执行以下操作:
- 合并 Var 字段,
- 合并 [onshow] 字段,
- 显示结果(原文:can be cancelled by Render property),
- 结束脚本 (可以使用Render特性取消).

Render 特性允许调整 Show() 方法的行为.
参数Render 同样允许调整Show() 方法但仅能调用一次.

调用TinyButStrong缓存系统的一个动作. 此缓存系统允许你手动或自动操作,将合并结果备份在一个被称为"缓存" 文件的临时文件. CacheAction() 依据调用动作的成功或失败返回 true 或 false.

语法: bool $TBS->CacheAction(string CacheId {, int Action/MaxAge}{, string Dir})

参数	描述
CacheId	缓存文件的Unic id. 必需是一个字符, 它将被做为文件名使用.
Action/MaxAge	让action执行的操作. 必需是 TinyButStrong's 定义的值. 参见下表了解更多可用指令的细节. 默认值为 3600 ,与之对应的是1小时内自动备份(译不准,原文:wich correspond to an automatic backup with a max age of 1 hour)
Dir	可选. 指定缓存文件保存的路径. 默认为执行脚本的目录 即./

管理缓存文件:
缓存系统使你可以创建,加载,更新或者删除以 CacheId 标识的缓存文件. 根据设定的缓存文件最大寿命，也可以让系统自动操作 缓存文件.

显示缓存:
假如你开始使用"显示缓存", 那么合并后的结果将在第一次使用Show() 方法时自动保存在缓存文件. 显示结果之后就记录这个步骤.
请注意 Show() 方法默认情况下会导致程序结束.假如想在"显示缓存"后继续一些操作, 那么你需要设置 Render 特性以避免程序在不应该的时候意外停止.

下面列出了 Action/MaxAge 参数可能用到的一些值, 它可以是 TinyButStrong 预定义的常数或者一个正整数.

动作	描述
x >=0 (正数)	最大寿命自动模式(Automatic Mode with max-age): - 假如缓存文件存在并创建时间少于 x 秒, 那么将加载文件并执行 Show() 方法. 假如设置了Render 特性,程序将在显示结果后结束, 否则 CacheAction() 返回 true. - 假如缓存文件不存在或者文件创建时间超过 x 秒以前, 那么 "显示缓存" 已开始 (上述). 该程序继续正常 CacheAction() 返回 false.
TBS_CACHENOW	保存当前合并结果到与 CacheId 相对应的缓存文件. CacheAction() 返回 false.
TBS_CACHELOAD	以 CacheId 加载对应的缓存文件. 假如缓存文件存在并加载成功 CacheAction() 返回 true , 否则返回 false.
TBS_DELETE	删除 CacheId 相对应的缓存文件. 你可以删除一个目录下的所有缓存文件,你只要指定 CacheId 为 '*'. CacheAction() 返回 false.
TBS_CACHEONSHOW	开始从 CacheId 相对应的缓存文件 "显示缓存" CacheAction() 返回 false.
TBS_CANCEL	取消 "显示缓存" 无论是什么 CacheId. CacheAction() 返回 false.
TBS_CACHEGETAGE	返回缓存文件寿命秒数.文件不存在则返回 false.
TBS_CACHEGETNAME	返回与 CacheId 相对应的缓存文件名. 即使文件不存在也返回.
TBS_CACHEISONSHOW	假如 "显示缓存" 可用,返回 true , 否则, 返回 false.

返回 TBS 块的数据源.
只返回定义块的第一部分, 除非 Sections 参数设定为 True.
如果没有找到块, 方法将返回 False.

语法: string $TBS->GetBlockSource(string BlockName {, boolean Sections})

参数	描述
BlockName	搜索的块名.
Sections	可选. 默认值为 False. 如果参数设置为 True 方法将返回一个包含指定块所有部分定义的数组. 第一个部分将被返回到数组里的 item [1].

此方法能让你获得块的来源信息以便手动控制合并过程.
在此之后, 假如你想用文本替代块, 你可以用 MergeBlock() 方法里的 'text' 参数.

使用一个固定值或调用用户函数替换一个或多个TBS Fields.
每个有指定 BaseName 的 TBS fields 将被合并.

语法: $TBS->MergeField(string BaseName, mixed X {, boolean FunctionMode})

参数	描述
BaseName	TBS Fields的基础名. 比如 'account'.
X	需要显示的值或代表一个用户函数的字串.
FunctionMode	指定显示值由一个用户函数给出. 默认值为 false. 假如参数设为 true, X 必须为用户函数名的字串. 此函数必须存在且拥有以下描述的语法.

与一个值合并:

X 可以是数字, 字串, 数组或一个对象. 如果是数组或对象, TBS Fields 名必须有像Var Fields 这样的后缀.

示例:

与用户函数合并:

TBS 在模板里搜索每个field调用此函数.
此函数必须拥有以下的语法:
当函数被调用, 参数 $Subname 拥有一个 field's 名的前缀 (如: 一个 field 名 'ml.title', $Subname 将拥有值'title'). 还有可选参数$PrmLst 含有一个相关联的数组和 field's 参数. 此函数必须返回合并的值.

示例:

显示一个基于指定 TBS block 和 TBS fields的导航栏.
关于如何建立一个导航栏的细节, 请参阅 '显示一个导航栏(Display a navigation bar)'.

语法: $TBS->MergeNavigationBar(string NavName, mix Options, int PageNum [, int RecCount, int PageSize])

参数	描述
NavName	导航栏的名字. 注意: 你可以通过使用逗号分隔多个名字以同时合并多个导航栏.
Options	可以让你参强制运行一此导航栏选项. 这些选项同样可以定义在模板的块参数中. 但假如你将这此选项也放在 MergeNavigationBar(),他们也将被强制运行. 此参数可为空 ('', 0 或者 null), 也可是一个数字或数组. 假如是一个数字, 表示显示的页数. 假如是一个数组, 表示包含如下项: 键 值 'navsize' 导航栏显示的页数. (默认 = 10). 'navpos' Position of the navigation bar compared to the active page number. 使用下列一个键值: - 'step' (默认) to have the bar progressing by step. - 'centred' to center the bar on the active page number. 'navdel' 当只有一页或者没有页面显示时,需要删除的 TBS 块. 这个 TBS 块必须属于导航栏. 假如有多个页面显示,那么只有 TBS 定义的块被删除. 'pagemin' 第一页 (默认 = 1).(设置什么值为第一页?--esayr注)
PageNum	当前显示的页面数值. 第一页为1. 要表示最后一页可以使用-1.
RecCount	可选. 默认值为 -1. 设置记录总数. 但当你不知道这个数字时,请将它设为-1. 此参数仅用来计算导航栏的最后一页的值.
PageSize	可选. 默认值为1. 表示每页的记录数. 它要配合 RecCount 使用,来计算导航栏的最后一页的值.

示例:

$TBS->MergeNavigationBar('nav','',$page,$rec_nbr,$page_size);

替换指定类型的 blocks 和 fields.语法: $TBS->MergeSpecial(string Type)

Type 参数必须是以下的其中一个:

值	描述
'var'	替换所有Var fields.
'onload'	替换所有onload fields.
'onshow'	替换所有onshow fields.

备注:
默认情况下, Show() 方法会在显示合并结果前替换掉所有特殊的 fields 和 blocks. 这就是 MergeSpecial() 方法很少在程序中被用到的原因.

表明合并在哪结束.
它的值必须是以下常量的组合.
默认值为 (TBS_OUTPUT + TBS_EXIT).

语法: int $TBS->Render

特性 Render 可以改变 方法 Show() 和 方法 CacheAction() 的行为.

常量	描述
TBS_NOTHING	表明在合并结束前不进行任何动作.
TBS_OUTPUT	表明让TBS使用PHP的echo命令将合并结果显示出来.
TBS_EXIT	表明脚本在合并结束后退出.

获取或设定合并过程中应用的 HTML 源.
调用LoadTemplate() 方法后, 这个特性将包含模板的 HTML 源.
此特性方便你在代码里读取和修改合并结果.

语法: string $TBS->Source

包含对应于当前模板的模板变量数组.

语法: array $TBS->TplVars

你可以使用参数tplvars在一个或多个onload automatic fields 定义模板变量.
当调用LoadTemplate()方法时,所有tplvars后的参数将被添加到 TplVars 特性里.
备注:
- 参数tplvars 仅工作于 onload automatic fields 里.
- 在一个模板里你可以多次使用参数tplvars.

你可以添加TinyButStrong自身不支持的其它数据源类型.
要实现这点,你需要用特定的声明编写三个函数(或方法), 然后对应添加的类型来命名.
你只需要将他们放在你自己的应用或者一个外部PHP文件上,而不必将函数添加到TBS源文件中.
你可以在TinyButStrong 的 站点 上找到附加的数据源类型.

你有两个选择,要么写函数要么写类.
如果你写函数, 他们必须使用一个特定于你使用数据源的 TBS 标识符来命名他们 (往下看).
如果你要写一个类的方法, 那么方法名必须是tbsdb_open, tbsdb_fetch 和 tbsdb_close.

TBS 标识符 (适用于用户函数):

The $Source argument that you pass to the MergeBlock() method has a specific TBS identifier that you must use for the function naming. The type of the $Source argument must not yet be supported in native by TinyButStrong, otherwise the functions will be ignored.
The TBS identifier may be arranged by TBS to make it fit for a function name.

示例:

函数或方法的声明:

添加到你程序里的三个函数必须遵循以下语法:
如果你决定写一个函数, 那么请用关键词'customdb' 替换掉成数据源类型里的 TBS 标识符. 如果你想写成一个类, 请将函数的名字改为tbsdb_open, tbsdb_fetch 和 tbsdb_close.


function tbsdb_customdb_open(&$Source,&$Query) {...}
这个函数必须打开一个必须的查询(query)然后返回一个记录标识符.
如果返回的是错误, 函数将返回一个False 值,并显示相应的信息.

参数	描述
$Source	与传递到 MergeBlock() 方法的参数相同.
$Query	与传递到 MergeBlock() 方法的参数相同.

示例:

function tbsdb_customdb_fetch(&$Rs{,$RecNum}) {...}
这个函数必须返回一个包含columns' 名和值并与现有记录相关联的数组.当没有记录时,函数不得不返回一个 False 值.

参数	描述
$Rs	从tbsdb_customdb_open() 函数返回的记录集标识符.
$RecNum	可选. 预期的记录数. 第一个是数字 1.

示例:
如果你的数据源需要知道预期的记录数, 你可以添加 $RecNum 参数到你的函数声明. 除此之外, 这个参数是可选的,因为所有记录都会被按顺序的调用.

function tbsdb_customdb_close(&$Rs) {...}
这个函数不得不关闭或释放记录标识符.
它不一定需要返回一个值.

参数	描述
$Rs	从tbsdb_customdb_open() 函数返回的记录集标识符.

示例:

如果你是个 OOP 开发者, 你可能更喜欢 TBS 工作于对象方法而不是全局函数, 以及对象特性而非全局变量.

现在, 你首先要直接或间接的将 ObjectRef 特性指向一个存在的对象.
示例:
接着, 你仅需要在所有TBS函数名前加上字符'~' 特性指出一个 ObjectRef 方法而非全局函数. 像对应的全局函数需要的一样,在类里编写的代码必须拥有相同的语法.
比如普通的 Var Fields, OOP 语法支持由点分隔开的子实体 (数组项, 特性, 方法).

Var Fields 可以把 ObjectRef 对象指向给方法, 同时也指向给它的特性.

下列是支持'~' 前缀的特征:

特征	示例
Var Fields	[var.~prop1] ... [var.~.key1.prop1] ... [var.~meth1] ... [var.~prop2.subprop]
Parameter ondata	[blk1.column1;block=tr;ondata=~meth_ondt]
Parameter onformat	[blk1.column2;onformat=~meth_onfrm]
MergeField() method	$TBS->MergeField('fldname','~meth_MrgFld',true);
Custom Data Functions (*)	$TBS->MergeBlock('blk1','~mydb','SELECT * FROM t_table');
Custom Html conversion function	$TBS->LoadTemplate('mytemplate.htm','=~meth_htmlconv');

(*) 三个方法,而不是三个函数, 必须用给出的关键词定义.
举例说关键词'~mydb', 方法必须命名为 mydb_open(), mydb_fetch() 和 mydb_close().
示例 (适用于 ezSQL):

A TBS Field is a TBS tag which has to be replaced by a single data item.
It has a name which enables you to identify it and parameters can be supplied in order to change the display behaviour.

Syntax: HTML ... [FieldName;params] ... HTML

Element	Description
FieldName	The name of the Field. Warning: names that begin with var. , onload and onshow are reserved. They are respectively used for Var fields, and Automatic fields.
params	Optional. One or more parameters from the list below and separated with ';'. Some parameters can be set to a value using the equal sign '='. Example: frm=0.00 If the value contains spaces or semicolons, you can use single quotes. Example: frm='0 000.00'. It is possible to embed TBS fields. It means you can write this: [var.v1; if [var.v2]=1]. But: - for Var fields, you have to make sure that v2 will be merged before v1. - for block fields, you have to make sure that column v2 is before column v1.

Parameter	Description
htmlconv=val	Enables you to force or prevent the conversion of the data item to Html text. The value val can be one of the following keywords: yes: (default value) Force the conversion to Html including new lines. no: Prevent the conversion to Html. Useful to modify Javascript code or to modify the Html source. nobr: Force the conversion to Html but new lines (useful for <pre> tags for example). wsp: Preserve white spaces (useful for spaces at the beginning of lines). esc: No Html conversion and double the single quote characters ('). js: Convert the data item to a string that can be inserted between JavaScript text delimiters. look: Convert the data item to Html only if no Html entities are found inside the data item. You can specify several values using seperator '+'. Example : htmlconv=yes+js
. (dot)	If the data item is empty, then an unbreakable space is displayed. Useful for cells in tables.
ifempty=val	If the data item is empty, then it is replaced with the specified value.
magnet=tag	Assign a magnet Html tag to the TBS field. A magnet tag is kept as is when the field has a value, and is deleted when the field is null or empty string. Example: (<a href="[var.link;magnet=a]">click here</a>) Result for $link='www.tbs.com': (<a href="www.tbs.com">click here</a>) Result for $link='': () By default, the magnet Html tag should be a pair of opening-closing tags (like <a></a>) which first tag is placed before the TBS fields. But this can be changed using parameter mtype (see below). Remark: the parameters if then else are processed before parameter magnet.
mtype=val	To be used with parameter magnet. Define the magnet type. Value Magnet behavior when field is null or empty string m*m That's the default value. Delete the pair of tags that surrounds the TBS field. Everything that is between them is deleted also. The field can be put inside one of the tags. Example: (<a href="[var.link;magnet=a]">click here</a>) Result for $link='www.tbs.com': (<a href="www.tbs.com">click here</a>) Result for $link='': () m+m Delete the pair of tags that surrounds the TBS field, but keeping everything else that is between the tags. Example: (<a href="mailto:[blk.email;magnet=a;mtype=m+m]">[blk.name]</a>) Result for $email='me@tbs.com': (<a href="mailto:me@tbs.com">MyName</a>) Result for $email='': (MyName) m* Delete the single tag that is before the field, and everything that is between the tag and the field. Example 1: <img href="[var.link;magnet=img;mtype=m*]"> Example 2: <br> [var.address;magnet=br] *m Delete the single tag that is after the field, and everything that is between the tag and the field. Example: [var.address;magnet=br;mtype=*m]<br>
selected	This parameter enables you to select an item for a List, Radio buttons or Checkboxes placed into a Html form. You have to ensure that items are created (merged) before the merge. Html List: Use the parameter selected without setting a value to it. The TBS Field has to be placed within the list of values. When the TBS field is merged it is deleted, but the item which has the same value as the field will be selected. If the value is not found, a new item is added.   Example: BostonWashingtonNew York[town_id;selected] which will be after the merge: BostonWashingtonNew York Radio buttons and Checkboxes: Use the parameter selected with setting a value to it which is the name of the Radio buttons or Checkboxes to process. The TBS Field has to be placed within the form. When the TBS field is merged it is deleted, but the item which has the same value as the field will be selected.   Example: Boston [town_id;selected=r_test] Washington New York which will be after the merge: Boston Washington New York In this example, the Radio button captioned 'Washington ' has been selected because the name of the Radio button tag is ''r_test' and its value is 2, and the TBS tag named 'town_id' has been merged with the value 2. Multi-selection: For Lists, Radio buttons or Checkboxes, you can make a multi-selection by giving a Php array as the value of the TBS field. Bounds: By default the bounds for searching items to select are html tags <select> for List , and <form> for Radio buttons and Checkboxes. But you can change them using parameter selbounds (see below).
selbounds=tag	To be used with parameter selected. It enables you to change the search zone for items to select by indicating a Html tag type. By default, this value is select for a List, and form for Radio buttons and Checkboxes. Example: [town_id;selected=r_test;selbounds=div] In this example, items to select will be searched between <div> and </div> tags that surround the TBS field.
comm	This parameter enables you to widen the bounds of the TBS Field up to the bounds of the commentary Html tag which surround it. <!-- [myfield;comm] this is an example--> is strictly identical to [myfield] This is particularly useful for the template designing when you are using a Visual HTML Editor (such as Dreamweaver or FrontPage).
noerr	Avoid some of the TBS Error messages. When a message can be cancelled, it is mentioned in the message.
file=filename	Replace the field with the contents of the file. Filename can be a string or an expression built with Var fields that returns the file path. How to use this parameter is detailed in the chapter Subtemplates.
script=filename	Execute the Php script just before replacing the locator. Filename can be a string or an expression built with Var fields that returns the file path. * Take care that in your script variables are not global but local. This is because the script is called from a TBS method. In order to define or reach global variables in your script, you have to use the Php instruction global or the array $GLOBAL. * TBS gives to you predefined local variables that can be used in your script: - $CurrVal refers to the current value of the field. It can be modified. - $CurrPrm refers to the array of field's parameters. - $this refers to the current TBS instance. (See parameter subtpl for good usage) * Parameter script is sensible to the if parameter. If there is a parameter if in the field, then the script is executed only if the condition is verified. See chapter 'Subtemplates' for more details about how to use this parameter in subtemplate mode.
subtpl	To be used with the parameter script or parameter onformat. Activate the subtemplate mode during the script or function execution. See chapter 'Subtemplates' for more details.
once	To be used with the parameter script. Cancel the script execution if it has previously been called.
getob	This parameter is deprecated because it can be replaced with parameter subtpl. To be used with the parameter script. Indicates that the text displayed using the echo() command in the Php script replaces the value of the TBS Field.
if expr1=expr2	Display the data item only if the condition is verified, otherwise display nothing unless parameter then or else are used. Supported operators are: = or == equal != not equal +- greater than +=- greater than or equal to -+ less than -=+ less than or equal to Both expr1 and expr2 must be string or numerical expressions. You can use the keyword [val] inside the expressions to represent the data item. The expressions may contain TBS fields, but you have to make sure that they are merged before the containing field. See parameters then and else for some examples.
then val1	If the parameter if is defined and its condition is verified, then the data item is replaced with val1. Example:  [var.image;if [val]='';then 'image0.gif']
else val2	If the parameter if is defined and its condition is not verified, then the data item is replaced with val2. Example:  [var.error_id;if [val]=0;then 'no error';else 'error found']
onformat=fct_name	Indicates the name of a user Php function that will be executed before the merge of the field. The function fct_name must have the following syntax:   function fct_name($FieldName,&$CurrVal,{&$CurrPrm,{&$TBS}}) { ... }   Argument Description   $FieldName Gives the name of the current field (read only).   $CurrVal Refers to the value of the current field (read/write ; don't forget the & character in the statement).   $CurrPrm Optional. Refers to the array of parameters for the current field (Don't forget the & character in the statement).   $TBS Optional. Refers to the current TBS instance. (Don't forget the & character in the statement). Use this argument with lot of care. It is provided for the subtemplate mode. See chapter 'Subtemplates' for more details about how to use this arguments in subtemplate mode.
protect=val	Enables you to protect or unprotect the data item to be merged by replacing the characters '[' with their corresponding Html code '&#91;'. The value val can be one of the following keywords:   yes: (default value) data item is protected.   no: data item is not protected. By default, all data merged with a template is protected except if it's a file inclusion. It is strongly recommended to protect data when it comes from free enter like on a forum for example.
max=val	Indicates the maximum number of characters to display. Beyond this limit, the data item is cut and an ellipsis (...) is added at the bottom.
frm=format	Specify a format to display a data item of type date/time or numeric. For a numeric item, it is possible to use a conditional format which changes depending on the sign of the value. Date-time format: It is a VisualBasic like format. The following keywords are recognized: d, dd, ddd, dddd: number of the day, number of the day in two digits, short name of the day, full name of the day. Use parameter locale to display locale names. xx displays st, nd, rd or th depending to the number of the day. m, mm, mmm, mmmm: number of the month, number of the month in two digits, short name of the month, full name of the month. Use parameter locale to display locale names. yy, yyyy: year in two digits, full year. hh, nn, ss: hour, minutes, seconds in two digits. Other characters are kept. It is possible to protect the strings inside by putting them between single or double quotes. Examples:  [fld;frm=mm/dd/yyyy] will display 12/21/2002  [fld;frm='yyyy-mm-dd hh:nn:ss'] will display 2002-12-21 15:45:03 Numeric format: To define the decimal part, use an expression like '0x0...' where 'x' is the decimal separator , and '0...' is a continuation of zeros corresponding to the number of decimals. If there is no decimal, use the format '0.' (with a dot). To define a thousand separator, use an expression like '0z000x...' where 'z' is the thousand separator. If there is no decimal, use the format '0z000.' (with a dot). If the format contains the character '%', then the value to display will be multiplied by 100. The character '%' is displayed too. The numerical format may contain other strings. But only the expression with one or more zeroes placed to the right will be taken as a format, other characters will be kept. Examples: Value Field Display 2456.1426 [fld;frm='0.000'] 2456.143   [fld;frm='$ 0,000.00'] $ 2,456.14   [fld;frm='$ 0,000.'] 2,456 0.2537 [fld;frm='0.00 %'] 25.37%   [fld;frm='coef 0.00'] coef 0.25 Conditional formats: You have the possibility to define up to 4 conditional formats when the value is respectively positive, negative, zero or null (or empty string). Conditional formats must be separated by a '|' character. Each conditional format is optional. Examples: Value Field Display 2456.1426 [chp;frm='+0.00|-(0.00)|*|empty'] +2456.14 -156.333 [chp;frm='+0.00|-(0.00)|*|empty'] -(156.33) 0 [chp;frm='+0.00|-(0.00)|*|empty'] * null [chp;frm='+0.00|-(0.00)|*|empty'] empty -8.75 [chp;frm='+0.00|-(0.00)'] -(8.75)
locale	To be used with the parameter frm. Indicates that the format specified with frm must display locale day and month's names. Locale informations can be set using the PHP function setlocale().
tplvars	Enables you to define variables in the template that you can retrieve in the Php programm using TplVars property. Works only with onload automatic fields.

Var field 是一个显示PHP变量的TBS区域.
它的名字必须有一个关键词'var.' 后面跟着变量的名字.
标准TBS区域和参数同样适用于Var fields.

例如 [var.php_version] 将被 "4.2.3" 替代.

用户变量和预定义变量可以被合并,但是必须是全局变量.源变量(Resource)将被忽略

你可以利用点'.'指定项来合并一个数组变量.
例如: [var.myarray.item]

同样你也可以靠它来合并一个对象变量.
例如: [var.myobject.property]


Var fields 会在什么时候被合并?
Var fields 将在使用方法 Show() 时被合并,意思就是在显示合并结果前. 但你可以在任何时候使用 MergeSpecial() 方法来强制合并.

安全: 如何限制 Var fields 在模板中使用?

当你创建TBS对象时,可以定义一个允许变量前缀来限制 Var fields.

一个特殊的 Var field 是TinyButStrong 系统中显示数据的 TBS Field .
它必须以 'var..' 开头, 后面跟一个下面列出的关键词.
TBS区域的参数同样适用于特殊Var区域.

例子: Date of the day : [var..now;frm='mm-dd-yyyy']

名称	描述
var..now	服务器当前时间.
var..version	TinyButStrong当前版本号.
var..script_name	当前执行的PHP文件名.
var..template_name	最后加载的模板文件名. 它来自于 LoadTemplate() 方法.
var..template_date	最后加载的模板文件的创建时间.
var..template_path	最后加载的模板文件的路径. 来自于 LoadTemplate() 方法.
var..tplvars.*	此值用在 TplVars 特性项中. ('*' 必须是数组中存在项的键值)

特殊 Var fields 与普通 Var fields一样. 在调用 Show() 方法后合并, 意思就是在显示合并结果前. 但你可以在任何时候使用 MergeSpecial() 方法来强制合并.

一个 TBS 块允许你从记录源显示数据.
合并数据和块的流程由方法 MergeBlock() 完成.

合并时, TBS 块的重复次数对应记录数;同时相关联的TBS fields 被 columns 值代替.
一个 TBS field 关联到 Block1 以及显示 ColumnA 的值必须命名为 Block1.ColumnA
例如: [Block1.ColumnA;frm='mm-dd-yyyy']

两个拥有相同名称的块将被视为一个块的两个部分 (参见 sections of blocks).


共有三种定义 TBS 块的语法:

元素	描述
BlockName	TBS 块名.
block=begin	指定块首.
block=end	指定块尾.
block= tag_name	指定块被一对配对的HTML标签包含 <tag_name...>....</tag_name...> . HTML标签内容都属于块的内容. - row 可以使用它来指定表格的行.   block=row 等同于 block=tr. - opt 可以使用它来指定HTML列表中的项.   block=opt 等同于block=option.
params	可选. 一个或多个下列参数. 用 ';' 隔开.

'absolute' 语法很少会被使用到,因为TBS标签通常被放置在两个HTML标签之间.. 另一方面,它便于应用在文本编辑器上.

'关联' 语法使你可以仅使用一个TBS标签即可指定块.此外,没有必要去隐藏TBS标签,因为他们将在显示时被删除.这是相当实用的语法

'简化' 语法非常简单.它使你可以仅使用一个TBS标签来定义一个TBS块和 TBS Field . 这是最主流最实用的语法.

你可以使用 '关联' 或 'absolute' 语法来完成 Html 标准的自定义标签.
例如:
<custom_tag>Hello [blk1.column1;block=custom_tag], how are you?</custom_tag>

参数	描述
extend=n extend=tag1,tag2,...	为块定义更多的扩展标签.这个参数仅适用于关联语法或简化语法中.比如:它让你可以定义在一个两行表格上的块. 语法 1: 使用数字 n (正负都行) 为块定义 n 个下一对扩展标签. 标签名与参数 block 相同. 如果 n 为负数, 那么块将被反扩展,即扩展到前一对标签. 语法 2: 使用一个标签列表 为块定义下一对扩展标签. 标签为列表提供 .
encaps=num	指定参数 block 对应HTML标签的TBS标签的封装等级.默认值为 1. 例如: [block1.field1;block=tr;encaps=2] [block1.field2] 上例中, 蓝色行在合并时将被复制,因为 'encaps=2'. 如果 'encaps=1' 或者参数没值, 那么在合并时被复制的将是桃红色行.
comm	这个参数使你能加宽TBS标签的范围到包含它的HTML注释标签里. <!-- [block1;block=tr;comm] 这是个例子--> 等同于 [block1;block=tr] 此参数非常适用于使用可视编辑器进行模板设计.
nodata	指定一个仅当没有数据合并时才显示的部分. 例如: [block1.field1;block=tr] [block1.field2] [block1;block=tr;nodata]There is no data. 更多信息, 参见 'Sections of blocks'章节.
headergrp=colname	指定一个每次 colname 值变动时显示的 header 部分. colname 必须是一个由数据源返回的有效 column 名. 你可以使用不同columns定义若干 headergrp 部分. 放置次序 headergrp 部分在块可以修改结果. 更多部分, 请参见 'Sections of blocks'.
footergrp=colname	指定一个每次 colname 值变动时显示的footer部分. 参见 headergrp.
splittergrp=colname	指定一个每次 colname 值变动时显示的splitter部分. 参见 headergrp.
parentgrp=colname	指定一个每次 colname 值变动时显示的parent部分. 不同于其它的部分,一个 parentgrp 部分允许普通部分存在与其内.这是一个可以同时定义header 和 footer 部分的方法.
serial	指定块为连续主块. 更多信息, 参见章节 'serial display (in columns)'.
p1=val1	用于动态查询. 所有在 MergeBlock() 方法形成的字串 '%p1%' 将被值 val1 代替. 了解更多, 参见章节 'dynamic queries / sub-blocks'.
ondata=fct_name	指定在块合并时需要执行的用户函数.函数会在每次获取数据源的时候被调用.你可以使用参数在记录合并前编辑.函数必须使用如下语法:   function fct_name($BlockName,&$CurrRec,$RecNum) { ... } 参数 描述 $BlockName 返回调用函数的块名 (只读). $CurrRec 返回相关联包含当前记录的数组 (读/写 ; 别忘记函数以&开头 ). 假如你将变量设置为 False, 它将会停止合并,如同停止的地方就是记录集结尾. $RecNum 返回当前记录的数据(只读, 第一个记录是1). 例子: function f_add_column($BlockName,&$CurrRec,$RecNum) {   $CurrRec['len'] = strlen($CurrRec['text']); }
onsection=fct_name	小心使用此参数,因为有可能它将不再被将来的版本所支持. 它被用作兼容性用途,所以你应该使用更快的 ondata 参数. onsection 与 ondata 一样工作, 除了他的用户函数将在合并时每次去调用. So if your block contains header sections or conditional sections, then the function may be called several times for the same record. 函数语法:   function fct_name($BlockName,&$CurrRec,&$DetailSrc,$RecNum) { ... } 参数 $DetailSrc 返回当前部分源 (读/写 ; 别忘记函数以&开头 ).. 假如此值为 '', 它将取消显示此记录.
when expr1=expr2	标记此部分为条件部分,当条件被核实,一个条件部分才会被显示. 支持如下算式: = or == 等于 != 不等 +- 大于 +=- 大于或等于 -+ 小于 -=+ 小于或等于 expr1 和 expr2 必须是一个字串或数值表达式. 表达式可以为一个包含 Var fields 的automatic block,或者为已合并块的链接 fields.
default	如果在有条件显示部分中没有满足的条件,将显示此部分.
several	如果在有条件显示部分有多个满足的条件,将显示此部分. 原文:Indicates that several conditional sections of the block can be displayed if several conditions are true. By default, conditional sections are exclusive.

拥有相同名称的不同块将被视为一个相同块的不同部分.
部分可以用来:
- 轮流显示 (普通部分),
- 显示空数据 (NoData 部分),
- 当每次一个column 更改,显示一个 header (分组部分).

普通部分:

当你定义若干普通部分时,他们会被每个记录轮流使用.

NoData部分:

NoData 部分仅用在数据源没有任何记录时.一个块中只能有一个 NoData 部分. NoData 部分由参数 nodata 定义.


分组部分:

每当记录集中 column's 值变化时,分组部分才得以显示.你可以使用参数 headergrp, footergrp, splittergrp, 和 parentgrp 来定义heaser. 参见 block's parameters 了解更多细节.

The serial display enables you to display several records inside a block. For this, you have to use a main block and secondary blocks.


The main block and its secondary blocks are merged using only one call to the MergeBock() method. The main block must be defined using the parameter serial. The secondary blocks must be nested into the main block. The secondary block's names must be the name of the main block followed by "_" and a number indicating display order.


You can specify a special secondary block that will be used to replace unused secondary blocks (without records). This "Empty" secondary block must have the index 0. It can either be placed inside the main block with the normal secondary block, or alone inside another serial block. The "empty" secondary block is optional.


Remark:
The serial display also works with sections of block and dynamic queries.

It is possible to use the MergeBlock() method with a dynamic query.
In your template, you have to define a block by adding the parameters p1, p2, p3,... with their values.
The query given to the MergeBlock() method has to contain marks such as %p1%, %p2%, %p3%, ... in order to welcome the values of the parameters p1, p2, p3,... .

Each section of the block to be merged that contains a parameter p1 will be computed as a separate block for which the dynamic query is re-executed. The sections of the block that have no parameter p1 are combined with the previous section with a parameter p1.



Dynamic queries enable you to easily build a system of a main-block with sub-blocks. Here is how you can do it:
- Create a main block, and then a sub-block inside the main block.
- Link them by adding to the sub-block a parameter p1 whose value is a field from the main block.
- At the PHP side, merge the main block first, and then the sub-block.


Remarks:
- The parameter htmlconv=esc enables you to pass protected string values to the query.
- The dynamic queries also work with sections of block and serial display.

TinyButStrong is able to display a navigation bar using the MergeNavigationBar() method.
It is quite similar to merging a block using MergeBlock() except that there are page numbers instead of data, and you can use specific fields to display extra info, and options to arrange the navigation bar.

Blocks and fields:

Use a normal TBS block to display the page numbers.
This block will be merged with a virtual data source having as much records as pages to display, and with the following columns:
page is the only value that changes and its linked field must be placed inside the block. Others columns have always the same value and can be placed inside the block as well as outside the block.
Those fields support the parameter endpoint. It will replace the value of the field with an empty string ('') when the active page is equal to first page or last page. This enables you to manage display exceptions with parameter magnet for example.
The block can contain a special section to display the active page differently.
This section is defined using parameter currpage on the block definition.

onload and onshow are reserved names for TBS fields and blocks that are automatically merged when the template is loaded by the LoadTemplate() method and when the result is shown by the Show() method.

Automatic fields are merged with an empty value. They accept all TBS field's parameters.
They are useful for subtemplate and template variables.

Automatic blocks are not merged with data. They can have only conditional sections.


See conditional sections for more details.

There are two ways to instert subtemplates in your main template.

Primary insertion using parameter file:

This is the best way to simply insert a part contained in another file, like usually done for headers and footers.

The value given to parameter file must be the name of a file existing on the server. You can use an expression with Var Fields and the [val] keyword which represent the value of the field.

Examples:

Contents of the file is inserted at the place of the field, without no Html conversion and no TBS protection.
[onload] tags contained in the file are not processed at the insertion. [onshow] tags and Var fields will be merged on the Show() method because they became part of the main template.

The subtemplate can contain any TBS fields, including Var fields and blocks to be merged. If you intend to merge data with a block defined into a subtemplate, then it's suggested to use parameter file in an [onload] field in order to ensure that the subtemplate is inserted before you call MergeBlock().

Contents of the subtemplate can be a full HTML page, because TinyButStrong will search for <body> tags and retain only Html part between those two tags if they're found. This enables you to work with WYSIWYG subtemplates. If your main concern is high speed merging, you can avoid this feature by explicitly defining parameter htmlconv=no in the TBS field.

Parameter file is processed before other field's parameters, and the contents of the file will make the current value of the field. Take this in account if you want to use other parameters in the TBS field.

TinyButStrong 为字段和块的有条件的显示提供几个工具.

有条件的显示字段

在任何 TBS 字段里你可以使用以下参数控制字段是否显示, 以下是所有参数.


有条件的显示代码部分

You can use conditional sections any TBS block. A conditional section is a normal section which has a parameter when defining a condition, or parameter default. At the block's merging, each when condition of conditional sections is evaluated until one is verified. As soon as one when condition is verified, its conditional section is kept and other conditional sections are deleted. If no when condition is verified, then the default section is displayed if it exists.
By default conditional sections are exclusive inside a block. It means only one conditional section of a block can be displayed. But this can be changed using parameter several. See below for more details.


有条件的显示部分应用于自动块:

自动块 are not merged with data ; that's why they cannot have normal sections and linked fields. Automatic blocks can have only conditional sections. Conditions are evaluated only once, and they be expressions containing Var fields.


Non-exclusive conditional sections:

If you want a block to have non-exclusive conditional sections, you can use parameter several on the first conditional section. With this parameter, all conditions are evaluated and each true condition makes its section to be displayed.

参数	概要
htmlconv	Html 字段值转换模式.
. (点)	假如值为空, 将显示一个不能破损的间隔.
ifempty	假如值为空, 将显示其它值.
magnet	假如值为空, 将删除周围的标签.
mtype	配合 magnet 使用.
if	假如条件为真, 将改变它的值.
then	配合 if 使用.
else	配合 if 使用.
onformat	执行PHP函数来改变合并的字段.
max	限制字符数字.
frm	应用一个时间或者数字格式.
locale	配合 frm 使用. 显示本地时间的天数和月名.
protect	为字符 '[' 开启保护模式.
selected	在 Html 列表中选择一条项目.
selbounds	配合 selected 使用. 改变搜索项目默认范围.
comm	扩展这个区域一直到注释标签(原文:Extends the field's bounds up to the Commentary tag that surround it.)
noerr	消除一些 TBS 错误信息.
file	指定文件内容.(即:载入一个模板文件)
script	(指定)执行PHP脚本.
subtpl	配合 script 或者 onformat 使用. 运行 TBS 实例到子模板模式.
once	配合 script 使用. 防止脚本从几处执行.(可能是说,只允许自己一个 script )
getob	不推荐. 配合 script 使用. 重新得到文本传送给 echo 和 puts them to the 字段空间.

参数	概要
block	定义块的范围.
extend	扩展块的范围至几个连续的 Html 标签.
encaps	扩展块的范围至几个压缩的 Html 标签.(原文:Extends the block's bounds upon several encapsulated Html tags.)
comm	扩展块的范围至几个压缩的 Html 标签.Extends the block's bounds up to the Commentary tag that surround it.
nodata	当数据源里有nodata时表明这个部分不显示.
headergrp	当一个列的值改变,表明显示一个header 部分.(估计有误,原文如下:Indicates a header section that is displayed when the value of a column changes.)
footergrp	Indicates a footer section that is displayed when the value of a column changes.
splittergrp	Indicates a splitter section that is displayed when the value of a column changes.
parentgrp	Indicates a parent section that is displayed when the value of a column changes.
serial	表明包含几个记录的连续部分(原文:Indicates a section that contains a series of several records.)
p1	发送一个参数到源数据动态查询.
ondata	执行一个 PHP 函数来修改记录当它来自这个数据源(原文:Executes a Php user function to modify the record when it has just been taken from the data source.)
onsection	执行 Php 函数以达到改变当前合并的块.
tplvars	只能配合 onload 字段使用. 定义模板变量.
when	配合onload 或 onshow 使用. 当条件正确时显示此部分.
default	配合onload 或 onshow 使用. 当都不符合条件时才显示此默认块.
several	配合 when 使用. 指定组里的几个块可以显示.

字段	概要
nav.page	显示(总)页数.
nav.curr	显示当前页数.
nav.first	显示头一页(始终为 1).
nav.prev	显示上一页.
nav.next	显示下一页.
nav.last	显示最终一页 (-1 假如末知).
参数	概要
currpage	指定部分那是显示仅是当前页.Indicates a section that is displayed only for the current page.
endpoint	假如当前页为头页或尾页时返回空字串.
navpos	指定导航条为当前页数Indicates how the navigation bar is positioned compared to the current page number.
navsize	指定要显示第几页.
pagemin	指定第几页开始显示(即从第几页开始计数).

名称	概要
val	关键词 [val] 可以放在字段参数内表示本字段的值.
var.*	显示 Php 变量.
var..*	显示关于 TinyButStrong 的系统信息.
#	块的虚拟列名. 它显示返回记录数.
$	块的虚拟列名. 它显示源PHP数组的记录值.
onload	自动字段或者块, 模板加载时合并.
onshow	自动字段或者块, 模板显示时合并.