为何使用它?    示例    下载    手册    支持    论坛    推荐    秀出你的站点  http://phpv.net/TBS_Manual.htm#html_automatic

网站:    http://www.tinybutstrong.com/index.php?lang=fr

作者:    skrol29@freesurf.fr, Pirjo

Date:    --

*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*

TinyButStrong

version 2.05

*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*

高亮显示新版本功能

2.02  2.05

应用于PHP4..6或更高版本的专业和易用模板引擎

译者：esayr & !oEL | 本页最后更新：--

允许自由使用、分发、转载，但必须保留译者署名；详见：声明。

目录:

主题    描述

• 简介

    基本原理

    安装

    小示例

• 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 显示合并的结果.

安装:

.    复制文件 tbs_class.php 到你网站的目录文件夹.

.    在PHP程序的开头,加入下面这一行:

  include_once('tbs_class.php');

  $TBS = new clsTinyButStrong ;

备注: 如果 TBS 文件 tbs_class.php 在不同的目录, 你需要指定它的路径.

说明和技术细节:

TinyButStrong 是PHP写的一个库, 你可以将它做为一个组件引入自己的 PHP 程序里. 技术用语来说, TinyButStrong 是一个 PHP '类' ; 类名就叫 clsTinyButStrong.

在你的PHP文件头部添加的变量 $TBS 让你能够把模板合并到你的 PHP 程序中. 技术用语来说, 变量 $TBS 是 clsTinyButStrong 类的实例.

小示例:

例 :

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>

示例 :

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 ).

假如模板使用一个特殊的字符集,那么你需要给这个字符集指出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    可选. 此参数仅在定义分页模式后才可用.

指定显示哪一页. 第一页是 .

如果指定为- 将显示最后一页.

RecCount    可选. 此参数仅在定义分页模式 后才可用.

他允许调整MergeBlock()方法返回的数字结果.(原文:It allows to adjust the calculation of the number of records returned by the MergeBlock() method.)

RecCount    方法 MergeBlock() 的返回值

 :    默认值. 此方法返回最后记录数显示在需要的页面上.(原文:The method returns the number of the last record displayed in the required page.)

- :    此方法读取返回的所有记录一直到最后的总数,然而, 仅在被要求的页面上显示记录.

> :    方法返回的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 = - ;

}

$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或  (假如 Query 是一个空的字串string)其它链接域将不被处理.

Number

数据源参数必须设定为'num'.

参数 Query 可以是一个数字或者数组.

arg Query    返回记录集

Number:    数字必须大于等于0. 返回记录集由数列 'val' 从1至指定数字组成.

Array:    这个数组须由 'min', 'max' 和 'step'组成.

返回记录集将由数列 'val' 从 'min'到'max'的值组成.

示例: array('min'->,'max'->) 将显示从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.$]

支持的数组结构:

数组的项可以有两种: .有关联键值的简单值 .数组值本身就是与键值关联的简单值.

:

示例:    ['key1']=>value1

['key2']=>value2

...

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

:

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

[] => (['column1']=>value1- ; ['column2']=>value2- ; ...)

[] => (['column1']=>value1- ; ['column2']=>value2- ; ...)

...

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

分页模式:

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

重要备注: 

尽管分页模式非常简单实用, 但它并末对读取大量数据记录作优化处理. 假如你使用它后感觉页面显示很慢或者你的数据库负载很大, 那么你可能需要考虑使用数据库系统自带的限制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 >=

(正数)    最大寿命自动模式(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 [].

此方法能让你获得块的来源信息以便手动控制合并过程.

在此之后, 假如你想用文本替代块, 你可以用 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'=>,'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(),他们也将被强制运行.

此参数可为空 ('',  或者 null), 也可是一个数字或数组.

假如是一个数字, 表示显示的页数.

假如是一个数组, 表示包含如下项:

键    值

'navsize'    导航栏显示的页数. (默认 = ).

'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'    第一页 (默认 = ).(设置什么值为第一页?--esayr注)

PageNum    当前显示的页面数值.

第一页为1. 要表示最后一页可以使用-.

RecCount    可选. 默认值为 -.

设置记录总数. 但当你不知道这个数字时,请将它设为-. 此参数仅用来计算导航栏的最后一页的值.

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    可选. 预期的记录数. 第一个是数字 .

示例:

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-) ;

    if (is_array($x)) {

      return $x ;

    } else {

      return false ;

    }

  }

  function mydb_close(&$db) {

    // not needed

  }

}

HTML 方面:

You design your template by placing TBS tags in the places where data items should appear.

There are two types of TBS tags: Fields and Blocks.

A TBS Field is a TBS tag which has to be replaced by a single data item. It is possible to specify a display format and also other parameters. The syntax for TBS Fields is described below.

A TBS Block is an area which has to be repeated. It is defined using one or two TBS fields.

Most often, it is the row of an HTML table. The syntax for TBS Blocks is described below.

TBS Fields:

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]=]. 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.

Field's parameters:

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 : <img href="[var.link;magnet=img;mtype=m*]">

Example : <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]=;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 '['. 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 //

 [fld;frm='yyyy-mm-dd hh:nn:ss'] will display -- ::

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 . 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']    $ ,456.14

     [fld;frm='$ 0,000.']    ,

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  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)

    [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 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() 方法来强制合并.

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,...    为块定义更多的扩展标签.这个参数仅适用于关联语法或简化语法中.比如:它让你可以定义在一个两行表格上的块. 

语法 : 使用数字 n (正负都行)

为块定义 n 个下一对扩展标签.

标签名与参数 block 相同.

如果 n 为负数, 那么块将被反扩展,即扩展到前一对标签.

语法 : 使用一个标签列表

为块定义下一对扩展标签.

标签为列表提供 .

encaps=num    指定参数 block 对应HTML标签的TBS标签的封装等级.默认值为 .

例如:

[block1.field1;block=tr;encaps=]    [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 (分组部分).

普通部分:

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

例如:

[b1.caption;block=tr]

[b1.caption;block=tr]

上例中, 块名 'b1' 包含两个普通部分. 记录会轮流一个绿色背景和蓝色背景.

NoData部分:

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

例如:

[b1.caption;block=tr]

There is nothing. [b1;block=tr;nodata]

分组部分:

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

例如:

Year: [b1.year;block=tr;headergrp=year]

[b1.caption;block=tr]    [b1.amount]

条件部分:

条件部分的显示需要他们的条件被核实.显示条件由参数 when 定义. 当一个部分拥有这个参数,它就变成需要条件的部分. 参见 Conditional display了解更我细节.

例如:

[b1.name;block=tr]

[b1.address;block=tr;when [b1.add_ok]==]

序列显示 (in columns):

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

Example:

Rec

Rec

Rec

Rec

Rec

Rec

Rec

Rec

Rec

...

...

...

In this example, main blocks are the blue lines of the table, the secondary blocks are the pink cells.

Syntax:

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.

Example:

[bx;block=tr;serial][bx_1.txt;block=td]

[bx_2.txt;block=td]

[bx_3.txt;block=td]

[bx_4.txt;block=td]

The corresponding PHP is:

 $TBS->MergeBlock('bx',$cnx_id,'SELECT txt FROM t_info ORDER BY txt')

Empty secondary block:

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

Example:

[bx;block=tr;serial][bx_1.txt;block=td]

[bx_2.txt;block=td]

[bx_3.txt;block=td]

[bx_4.txt;block=td]

[bx;block=tr;serial][bx_0;block=td] No records found.

Remark:

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

Dynamic queries / sub-blocks:

Principles of the 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.

Example:

Country: France

[blk.town;block=tr;p1='france']    [blk.country]

Country: USA

[blk.town;block=tr;p1='us']    [blk.country]

Corresponding PHP code:

 $TBS->MergeBlock('blk',$cnx_id,"SELECT town,country FROM t_geo WHERE (country='%p1%')")

Result of the merge:

Country: France

Paris    france

Toulouse    france

Country: USA

Washington    us

Boston    us

Use with sub-blocks:

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.

Example:

Country: [main.country;block=table]

[sub.town;block=tr;p1=[main.cntr_id]]

Corresponding PHP code:

 $TBS->MergeBlock('main',$cnx_id,'SELECT country,cntr_id FROM t_country')

 $TBS->MergeBlock('sub',$cnx_id,'SELECT town FROM t_town WHERE (cntr_id=%p1%)') 

Result of the merge:

Country: France

Paris

Toulouse

Country: Germany

Berlin

Munich

Country: Spain

Madrid

Barcelona

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.

Display a navigation bar:

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:

Name    Description

page    Returns the number of a common page, reachable from the navigation bar.

curr    Returns the number of the active page.

first    Returns the number of the first page ( by default).

prev    Returns the number of the previous page.

next    Returns the number of the next page.

last    Returns the number of the last page if it's known, otherwise returns -1.

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.

Example:

<a href="script.php?page=[nav.first;endpoint;magnet=a;mtype=m+m]">Beginning</a>

In this example, the link will be deleted when the active page is the first page.

The block can contain a special section to display the active page differently.

This section is defined using parameter currpage on the block definition. 

Example:

Template:

|<    <    [nav.page;block=td]    [nav.page;block=td;currpage]    >    >|

Php code used:

  $TBS->MergeNavigationBar('nav',,) ;

Result of the merge:

|<    <                                            >    >|

Remark: this example doesn't display links.

Options

The block definition can contain parameters that are specific to the navigation bar.

Those options can also be defined as a parameter of the MergeNavigationBar() method.

Parameter    Description

navsize=num    Number of pages displayed in the navigation bar. (default = ).

navpos=keyword    Position of the navigation bar compared to the active page number. Use one of the following keywords:

- 'step' (by default) to have the bar progressing by step.

- 'centred' to center the bar on the active page number.

navdel=blockname    Name of a TBS block to delete when there is only one page or no page to display.

This TBS block must surroud the navigation bar. If there are several pages to display then only TBS definition tags of this bloc are deleted.

pagemin=num    Number of the first page (default = ).

Automatic fields and blocks:

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.

Example:

[onload;file=header.htm]

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

Examples:

[onload;block=tr;when [var.status]==] Status

[onload;block=tr;when [var.status]==] Status 

See conditional sections for more details.

Subtemplates:

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:

[onload;file=header.htm]

[onload;file=[var.file_header]]

[var.sub1;file=[val]]

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.

Insertion driven with Php code using parameter subtpl:

Parameter subtpl is useful to manage subtemplate insertion with Php code. Parameter subtpl is active only when used with a parameter script or onformat. It turns the current TBS instance in Subtemplate mode during the script or function execution and can act on a new template without deteriorating the main template.

The Subtemplate mode presents the following characteristics:

*    Php outputs are displayed at the field's place instead of being immediately sent to the client. For example, using the Php command echo() will insert a text in the main template instead of be directly output it. Using the Show() method will also insert the result of the sub-merge into the main template.

*    A reference to the TBS instance is provided by local variable $this or $TBS, whether you use parameter script or onformat. This variable be used for new submerges without deteriorating the main template. The Show() method won't stop any script execution during the Subtemplate mode like it does by default in normal mode.

When the script or the function ends, the TBS instance returns in normal mode with the main TBS template.

Example with parameter script:

HTML:    [var.file;script=specialbox.php;subtpl]

PHP script:    <?php

  echo('* Here include a subtemplate *');

  $this->LoadTemplate($CurrVal);

  $this->MergeBlock('blk1',$GLOBALS['conn_id'],'SELECT * FROM table1');

  $this->Show();

?>

Remarks:    $CurrVal is a local variable provided by TBS when using parameter script ; this variable is a reference to the value of the field currently merged. In the example above, $CurrVal has the value of the global variable $file. You can replace it, for example, by the name of the subtemplate to load (for example: 'mysubtpl.htm'). See parameter script for more information.

Example with parameter onformat:

HTML:    [var.user_mode;onformat=f_user_info;subtpl]

PHP user function:    function f_user_info($FieldName,&$CurrVal,&$CurrPrm,&$TBS) {

  if ($CurrVal==) { // User is logged in

    $TBS->LoadTemplate('user_info.htm');

    $TBS->MergeBlock('blk1',$GLOBALS['conn_id'],'SELECT * FROM table1');

    $TBS->Show();

  } else { // User not logged in

    echo('You are not logged in.');

  }

}

Remarks:    $CurrVal is a variable declared as an argument of the function. It's TBS that is in charge to call this function making $CurrVal referring to the value of the fields currently merged. In this example above, $CurrVal is equal to the global variable $user_mode. In the same way, variable $CurrPrm is a reference to the array of parameters of the field currently merged, and $TBS is a reference to the TinyButStrong instance currently used. See parameter onformat for more information.

有条件的显示汇总:

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

有条件的显示字段

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

参数    描述

. (点)    显示 Html 不可破损空间,假如字段值为空.

ifempty=value2    假如字段值为空,显示value2.

magnet=tag    假如字段值为空,删除一个或一对标签.

if condition

then value1

else value2    根据条件真或假显示 value1 或 value2 .

frm=format1|format2|format3|format4    改变数字格式或日期/时间格式.不管其值为 正,负,零或空..

示例:

[var.error_id;if [val]=;then '没有错误';else '发现错误']

有条件的显示代码部分 

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. 

有条件的显示正常块的代码部分:

Normal blocks are those that you merge with data using the MergeBlock() method. Normal blocks can have conditional sections. Conditions are evaluated for each record of the data source, and they can be expressions containing linked fields or Var fields. 

示例:

Name: [b1.Name;block=tr]    正常部分

Address:

[b1.add_line1;block=tr;when [b1.address]=]

[b1.add_line2]

[b1.add_zip] - [b1.add_town]

有条件的显示部分

No address.[b1;block=tr;default]    有条件的显示部分

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

自动块 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. 

示例:

[onload_ligth;block=tr;when [var.light]=] Light is ON.

[onload_ligth;block=tr;when [var.light]=] Light is OFF.

[onload_ligth;block=tr;default] Light is ?

This block will be automatically merged when the template is loaded.

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.

示例:

[onload_err;block=tr;when [var.email]='';several] Your email is empty.

[onload_err;block=tr;when [var.name]=] Your name is empty.

[onload_err;block=tr;default] All is ok.

概要:

TBS 字段参数:

参数    概要

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 字段空间.

TBS 块参数:

参数    概要

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    显示头一页(始终为 ).

nav.prev    显示上一页.

nav.next    显示下一页.

nav.last    显示最终一页 (- 假如末知).

参数    概要

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    自动字段或者块, 模板显示时合并.

.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:

TBS 手册 --phpv 翻译的更多相关文章

  1. Spring Security 5.0.x 参考手册 【翻译自官方GIT-2018.06.12】

    源码请移步至:https://github.com/aquariuspj/spring-security/tree/translator/docs/manual/src/docs/asciidoc 版 ...

  2. tmux手册中文翻译

    man tmux可以看到最详细的tmux介绍,本文翻译自tmux手册. tmux全名叫"terminal multiplexer",终端多路复用器. tmux的命令格式为: tmu ...

  3. 【译】x86程序员手册00 - 翻译起因

    从上一次学习MIT的操作系统课程又过去了一年.上次学习并没有坚持下去.想来虽有种种原因,其还在自身无法坚持罢了.故此次再鼓起勇气重新学习,发现课程都已由2014改版为2016了.但大部分内容并没有改变 ...

  4. Matalb中英双语手册-年少无知翻译版本

    更新: 20171207: 这是大学期间参加数模翻译的手册 正文: 愚人节快乐,突然发现自己在博客园的一篇文章.摘取如下: MATLAB 语言是一种工程语言,语法很像 VB 和 C,比 R 语言容易学 ...

  5. ld 脚本浅析-LD手册粗糙翻译

    本文乃转载, 我在其基础上做了少量修改. 原作者的E-mail是zhanglei@sict.ac.cn. 完成于2005.11.5-2005.11.8 0. Contents 1. 概论2. 基本概念 ...

  6. ZooKeeper开发手册中文翻译（转）

    本文Github地址:https://github.com/sundiontheway/zookeeper-guide-cn 本文假设你已经具有一定分布式计算的基础知识.你将在第一部分看到以下内容: ...

  7. ZooKeeper开发手册中文翻译

    本文假设你已经具有一定分布式计算的基础知识.你将在第一部分看到以下内容: ZooKeeper数据模型 ZooKeeper Sessions ZooKeeper Watches 一致性保证(Consis ...

  8. getopt() getopt_long()函数手册[中文翻译]

    getopt()函数 getopt_long函数 函数原型(function prototype) #include <unistd.h> int getopt(int argc, cha ...

  9. Angular开发者手册重点翻译之指令（一）

    创建自定义的指令 这个文章将解释什么需要在自己的angularjs应用中创建自己的指令,以及如何实现它. 什么是指令 在高的层面上讲,指令是DOM元素中的标记(例如一个属性,一个节点名,注释或者CSS ...

随机推荐

  1. 【带修莫队】【权值分块】bzoj3196 Tyvj 1730 二逼平衡树

    这题用了三种算法写: 分块+二分:O(n*sqrt(n*log(n)) 函数式权值分块:O(n*sqrt(n)) 带修莫队+权值分块:O(n5/3) 结果……复杂度越高的实际上跑得越快……最后这个竟然 ...

  2. JQurey中getJSON方法错误回调方法

    1.使用try...catch实现 2.换$.ajax 3.JQuery 1.5+可以这样使用: $.getJSON("example.json", function() { al ...

  3. Nginx用为缓存服务器

    Nginx 缓存组成 共享内存 数据定位 存储键和缓存对象的元数据 磁盘空间: 存储数据   nginx做为反向代理时,能够将来自upstream的响应缓存至本地,并在后续的客户端请求同样内容时直接从 ...

  4. Array.apply 方法的使用

    Array.apply(null, {length: 5}) length为特殊字段,意思是生成一个长度为5的数组,由于没赋值,所以都是undefined; 如果要赋值,可以这样 console.lo ...

  5. $apply用法注意

    Angular为我们提供了一些接口绑定JavaScript代码和数据,而绑定数据改变和更新angular则是使用$apply方法实现的. $apply 进行数据变化检查的实际上是$digest函数,但 ...

  6. Centos7.4 建站系统和软件版本搭配

    一.系统和软件版本搭配 版本: 1.1.2 类型: 建站系统 适用于: Centos7.4 64bit 集成软件版本: nginx_versi=1.12.2 PHP=7.1.13 (已提供提供Zend ...

  7. （原创）sklearn中 F1-micro 与 F1-macro区别和计算原理

    最近在使用sklearn做分类时候,用到metrics中的评价函数,其中有一个非常重要的评价函数是F1值,(关于这个值的原理自行google或者百度) 在sklearn中的计算F1的函数为 f1_sc ...

  8. 深入理解CommonJS！

    CommonJS 一开始大家都认为JS是辣鸡,没什么用,官方定义的API只能构建基于浏览器的应用程序,CommonJS就按耐不住了,CommonJS API定义很多普通应用程序(主要指非浏览器的应用) ...

  9. Python下opencv使用笔记（二）（简单几何图像绘制）

    简单几何图像一般包含点.直线.矩阵.圆.椭圆.多边形等等.首先认识一下opencv对像素点的定义. 图像的一个像素点有1或者3个值.对灰度图像有一个灰度值,对彩色图像有3个值组成一个像素值.他们表现出 ...

  10. linux上MySQL改动password的各种方法，yc整理

    MySQL改动password的各种方法 整理了下面四种在MySQL中改动rootpassword的方法,可能对大家有所帮助! 方法1: 用SET PASSWORD命令 mysql -uroot my ...