TinyButStrong模板手册1

lhaiweng

简介:
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 程序
结果


  [var.message]


'tbs_class.php');
$TBS = new clsTinyButStrong ;
$TBS->LoadTemplate('template.htm') ;
$message = 'Hello' ;
$TBS->Show() ;
?>

  Hello

示例 2:
Html 模板
Php 程序
结果

[blk.val;block=tr]

'tbs_class.php');
$TBS = new clsTinyButStrong ;
$TBS->LoadTemplate('template.htm') ;
$list = array('X','Y','Z') ;
$TBS->MergeBlock('blk',$list) ;
$TBS->Show() ;
?>
X
Y
Z
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 页面中, 字符集往往放在文件的开头处, 属于标签的'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 结果标识符
-
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.(*) 参见以下章节的解释.
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)


本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u1/50764/showart_406063.html