TBS手册——翻译

最新推荐文章于 2024-05-02 14:26:53 发布

weixin_33777877

最新推荐文章于 2024-05-02 14:26:53 发布

阅读量279

点赞数

文章标签： php 数据库 javascript ViewUI

原文链接：http://blog.51cto.com/caixia/414502

版权

主题	描述

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

简介:

TinyButStrong (TBS) 是一个PHP类,它能让你开发系统时能干净分离PHP脚本和HTML文件. 使用 TBS, HTML 页面是由模板合并数据后动态生成的. 这被称为模板引擎.

这个TBS的名字来源于本工具目前虽然只有8个函数,但却非常强大. 它允许您合并PHP变量,或者 MySQL, PostgreSQL, SQLite到HTML页面里.

TBS 设计成你可以轻松的使用任何可视化 HTML 编辑软件 (像 Dreamweaver 和 FrontPage)开发 HTML 模板页. 你习惯于使用文本方式编辑HTML文件?没问题,TBS 同样能够让你创建 JavaScript 动态脚本.

正如它的名字一样, TBS 易用, 强大且快速. 它完全是 °~° 免费的°~°.

基本原理:

在HTML方面:
你设计页面时不需要包含任何PHP脚本和流程. 在页面里你只要将TBS 标签放在你想显示动态数据的地方. 这个页面称为 '模板'.
有两种类型的标签: '字段' 显示动态的数据项目, '块' 则定义一个区域, 主要为了从数据源显示记录.

在PHP方面:
使用 TBS 的实例对象管理你的HTML模板. 在文档末, TBS 显示合并的结果.

安装:

1.	复制文件 tbs_class.php 到你网站的目录文件夹.
2.	在PHP程序的开头,加入下面这一行: include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; 备注: 如果 TBS 文件 tbs_class.php 在不同的目录, 你需要指定它的路径.

说明和技术细节:
TinyButStrong 是PHP写的一个库, 你可以将它做为一个组件引入自己的 PHP 程序里. 技术用语来说, TinyButStrong 是一个 PHP '类' ; 类名就叫 clsTinyButStrong.
在你的PHP文件头部添加的变量 $TBS 让你能够把模板合并到你的 PHP 程序中. 技术用语来说, 变量 $TBS 是 clsTinyButStrong 类的实例.

小示例:

例 1:

Html 模板	Php 程序	结果
<html> <body> [var.message] </body> </html>	<? include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate('template.htm') ; $message = 'Hello' ; $TBS->Show() ; ?>	<html> <body> Hello </body> </html>

示例 2:

Html 模板	Php 程序	结果
<table> <tr><td>[blk.val;block=tr]</td></tr> </table>	<? include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate('template.htm') ; $list = array('X','Y','Z') ; $TBS->MergeBlock('blk',$list) ; $TBS->Show() ; ?>	<table> <tr><td>X</td></tr> <tr><td>Y</td></tr> <tr><td>Z</td></tr> </table>

PHP 方面:

模板和 PHP 程序的合并需要使用一个对象变量即 clsTinyButStrong 类.
声明示例: $TBS = new clsTinyButStrong ;
这个对象允许你加载模板, 以便合并入数据, 然后显示结果.

PHP代码示例:

include_once( 'tbs_class.php');
$TBS = new clsTinyButStrong ;
$TBS->LoadTemplate( 'template.htm') ;
$TBS->MergeBlock( 'ctry','mysql','SELECT * FROM t_country') ;
$TBS->Show() ;

下面列出 TinyButStrong 对象的属性和方法:

方法 LoadTemplate():

加载一个模板以便替换和处理.
文件全部内容将被保存于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="");], 并能返回一个转换后的字串.

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

方法 MergeBlock():

从一个数据源合并一个或几个 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);

块与返回之间的连结:

方法MergeBlock() 在模板内搜索你指定的TBS块名,然后, 然后块将根据数据源内记录的次数反复显示.
为了显示一个数据记录,你需要使用一个 TBS 链接域. 要链接到一个TBS域,这个TBS域的名字应试是这样构成的: 块名.记录集键名(或者行名) 有点像这样 [block1.field1] . 另外,TBS 链接域必须在指定的块内.

示例:

块名是: block1
从查询返回行: field1, field2, field3
连接 TBS 字段: [block1.field1], [block1.field2], [block1.field3]

假如在模板内没有找到定义的块, MergeBlock() 方法将合并首个记录尽管所有连接字段在模板内可找到.

你同样可以定义更多高级的块. 想了解更多, 参见 TBS Blocks章节.

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

你可以在 BlockName 参数中标示多个块以便同时合并他们,每个块间需要一个逗号分割. 这样一来, 查询(query)只被执行一次,返回块的记录将被缓冲.
示例 :
$TBS->MergeBlock('block1,block2,block3','mysql','SELECT * FROM MyTable');

统计记录数:

要显示记录数, 你需要使用一个链接到virtual column ' #' 的TBS域.
如果你把这个域放在块外, 它将显示记录总数.
示例: [block1.#]

如果数据源是一个PHP数组, virtual column ' $' 将显示它的键值.
示例: [block1.$]

数据源类型与资源&请求参数对照表:

数据源类型	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	一个 MySql 结果标识符	-
PostgreSQL	一个 PostgreSql 连接标识符	An SQL statement
PostgreSQL	一个 PostgreSql 结果标识符	-
SQLite	一个 SQLite 连接标识符	An SQLite statement
SQLite	一个 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.

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

Php 数据源:

Text

数据源参数必须设定为 'text'.
整个块被文本 (必须为字串string) 替代为 Query 参数. 除了 ' #' 返回 1或 0 (假如 Query 是一个空的字串string)其它链接域将不被处理.

Number

数据源参数必须设定为 'num'.
参数 Query 可以是一个数字或者数组.

arg Query	返回记录集
Number:	数字必须大于等于0. 返回记录集由数列 'val' 从1至指定数字组成.
Array:	这个数组须由 'min', 'max' 和 'step'组成. 返回记录集将由数列 'val' 从 'min'到'max'的值组成. 示例: array('min'->101,'max'->150) 将显示从101至150的50个块.

Clear

数据源参数必须设定为 'clear'.
所有块和部分都将删除,与合并一个空数组效果一样.

Conditional

数据源参数必须设定为 'cond'.
块将被视为有条件的显示块加载(onload) 和显示(onshow). 这个块不与数组合并, 所有它不能出现任何 TBS 链接域. 每个块都需要一个参数 when 或 default. 参阅有条件的显示块了解更多细节.

Array

数据源参数必须为一个PHP数组或设定为 'array'. 假如你用关键词 'array', 那么查询(Query) 参数必须是一个PHP数组或者一个代表数组的字串包含或者嵌套在一个全局变量里.

字串语法: 'globvar[item1][item2]...'

'globvar' 是一个全局变量 $globvar 的名字,且必须是一个数组.
'item1' 和 'item2' 是$globvar 项的键值或者它的子项名.
示例:

$TBS->MergeBlock('block1','array','days[mon]');
将把 'block1' 和 $day['mon'] 数组合并.

你也可以不使用项名.
示例:

$TBS->MergeBlock('block1','array','days');

使用字串代表数组有两个优势:
-> 项可以直接从数组而不是复制的项中读取,这样可以提高性能.
-> 你可以使用动态的查询.

显示当前记录的键值:
欠可以使用virtual column ' $' 来显示当前记录的键值. 这在你使用动态查询与子块(dynamic queries and sub-blocks) 时将派上大用场.
示例: [block1.$]

支持的数组结构:
数组的项可以有两种: 1.有关联键值的简单值 2.数组值本身就是与键值关联的简单值.

1:

示例:	['key1']=>value1 ['key2']=>value2 ...

返回的记录集由包含键值的数列 'key' 和一个包含值的数列 'val' 组成.

2:

示例:	[0] => (['column1']=>value1-0 ; ['column2']=>value2-0 ; ...) [1] => (['column1']=>value1-1 ; ['column2']=>value2-1 ; ...) [2] => (['column1']=>value1-2 ; ['column2']=>value2-2 ; ...) ...

返回的记录集由数列 'column1', 'column2',... 与他们关联的值组成.

分页模式:

当你赋一个非零参数给 PageSize 时,分页模式将被激活. 数据的显示将被所指定的 PageNum 限制. 假如 PageNum 的值为 -1, 那么将显示最后一页.

重要备注:

尽管分页模式非常简单实用, 但它并末对读取大量数据记录作优化处理. 假如你使用它后感觉页面显示很慢或者你的数据库负载很大, 那么你可能需要考虑使用数据库系统自带的限制query数功能(假如有的话).
比如: 在 MySQL 里你可以使用 LIMIT 子句.

说明: 考虑到各种不同的 SQL 语法, TinyButStrong 无法修改一个可以返回定量记录集的查询(query). 例如, 它不能将一个 LIMIT 子句添加进一个 MySQL 查询(query).
这就是为什么 TinyButStrong 必须访问原始查询(query), 然后忽略之前的页面设置从头开始一个个地读取记录.尤其是在页数很多时显示速度将会非常慢, 当页面被选定,TinyButStrong 就会不顾记录集结尾地释放查询(query)

方法 Show():

结束合并.

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

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

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

方法 CacheAction():

调用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.

方法 GetBlockSource():

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

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

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

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

方法 MergeField():

使用一个固定值或调用用户函数替换一个或多个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->MergeField( 'account',array( 'id'=> 55, 'name'=> 'Bob'));

本例中, fields [account.id] 和 [account.name] 将被合并.

与用户函数合并:

TBS 在模板里搜索每个field调用此函数.
此函数必须拥有以下的语法:

function fct_user( $Subname [, $PrmLst]) {...}

当函数被调用, 参数 $Subname 拥有一个 field's 名的前缀 (如: 一个 field 名 'ml.title', $Subname 将拥有值 'title'). 还有可选参数 $PrmLst 含有一个相关联的数组和 field's 参数. 此函数必须返回合并的值.

示例:

$TBS->MergeField( 'ml', 'm_multilanguage', true);
...
function m_multilanguage( $Subname) {
  global $lang_id;
   $rs = mysql_query( "SELECT text_$lang_id AS txt FROM t_language WHERE key='$Subname");
   $rec = mysql_fetch_array( $rs);
  return $rec[ 'txt'] ;
}

在此例中, 一个像 [ml.title] 的 field 将和 m_multilanguage('title')返回值合并.

方法 MergeNavigationBar():

显示一个基于指定 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);

方法 MergeSpecial():

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

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

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

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

特性 Render:

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

语法: int $TBS->Render

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

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

特性 Source:

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

语法: string $TBS->Source

特性 TplVars:

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

语法: array $TBS->TplVars

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

示例:
[ onload; tplvars; template_version= '1.12.27'; template_date= '2004-10-26']
这个 TBS 标签将创建等同于以下PHP代码的项:
$TBS->TplVars['template_version'] = '1.12.27';
$TBS->TplVars['template_date'] = '2004-10-26';

备注:
- 参数 tplvars 仅工作于 onload automatic fields 里.
- 在一个模板里你可以多次使用参数 tplvars.

添加一个数据源类型:

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

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

示例:
class clsTest {
  function tbsdb_open(...) {...}
  function tbsdb_fetch(...) {...}
  function 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.

If $Source is an object, then the TBS identifier is the name of Php class.
If $Source is a resource, then the TBS identifier is the resource type.
If $Source is a string, then the TBS identifier is this string.

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.

示例:

如果 $Source 是一个Sybase链接 (resource type = 'sybase-db link'), 那么TBS 标识符就是 'sybase_db'.

函数或方法的声明:

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

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

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

示例:

function tbsdb_sybase_db_open(&$Source,&$Query) {
return sybase_query($Query,$Source) ;
}

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

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

示例:

function tbsdb_sybase_db_fetch(&$Rs) {
return sybase_fetch_assoc($Rs) ;
}

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

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

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

示例:

function tbsdb_sybase_db_close(&$Rs) {
return sybase_free_result($Rs) ;

面向对象编程:

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

现在, 你首先要直接或间接的将 ObjectRef 特性指向一个存在的对象.
示例:

$TBS->ObjectRef = &$MyObject; // Use '&' to define the property by reference.
或:
$TBS->ObjectRef['key1'] = &$MyObject; // Indirect reference

接着, 你仅需要在所有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):

class mydb Extends db {
   function mydb_open(& $source,& $query) {
     $this->get_results( $query) ;
    return $this ;
  }
   function mydb_fetch(& $db, $num) {
     $x = $this->get_row( null,ARRAY_A, $num-1) ;
    if (is_array( $x)) {
      return $x ;
    } else {
      return false ;
    }
  }
   function mydb_close(& $db) {
    // not needed
  }
}

Var fields:

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

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

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

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

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

内嵌 Var Fields
放在 file, script, if, when (TinyButStrong2.02后还支持 then 和 else) 里的内嵌 Var Fields总是能被处理,其它情况下, 你需要确定这个内嵌区域是否已合并. 其它内嵌 Var Field 将被忽略.

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

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

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

例子 :
  $TBS = new clsTinyButStrong('','x1_');
在这个例子里, 只有拥有前缀 'x1_' PHP全局变量可以放在模板里. 而其它的Var fields 将在合并时产生一个错误信息.
  [ var. x1_title] 将合并存在的 $x1_title.
  [ var. x2_title] 将产生一个错误信息.

NB: 在上面例子中第一个参数 '' 被用来定义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 与普通 Var fields一样. 在调用 Show() 方法后合并, 意思就是在显示合并结果前. 但你可以在任何时候使用 MergeSpecial() 方法来强制合并.

Var fields:

特殊的 Var fields:

名称	描述
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 与普通 Var fields一样. 在调用 Show() 方法后合并, 意思就是在显示合并结果前. 但你可以在任何时候使用 MergeSpecial() 方法来强制合并.

TBS 块:

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

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

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

块的语法:

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

外部语法:

使用两个 TBS 标签. 一个放块前一个放块后.

例如:
HTML...[ BlockName; block= begin ;params] ...HTML...[ BlockName; block= end] ...HTML

用于块定义的 TBS 标签将在合并时被删除.

关联语法:

块被一对配对的HTML标签定义. 只需要一个TBS标签.

例如:
HTML...<tag_name...>...[ BlockName; block= tag_name;params] ...</tag_name...>...HTML

用于块定义的TBS标签必须在HTML标签里.
这个 TBS 标签也将在合并时被删除.

简化语法:

一个相关联的TBS field 被用来定义块(参见上面的关联语法).

例如:
HTML...<tag_name...>...[ BlockName. ColumnName; block= tag_name;params] ...</tag_name...>...HTML

用于块定义的TBS 标签必须在HTML标签之间.
但它不一定是在块中首位的 TBS field.

元素	描述
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]
此参数非常适用于使用可视编辑器进行模板设计.

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.

转载于:https://blog.51cto.com/caixia/414502