TinyButStrong模板手册3

lhaiweng

面向对象编程:
如果你是个 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
  }
}
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]=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.
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  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:
(click here)
Result for $link='www.tbs.com': (click here)
Result for $link='': ()By default, the magnet Html tag should be a pair of opening-closing tags (like ) 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:
(click here)
Result for $link='www.tbs.com': (click here)
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:
([blk.name])
Result for $email='me@tbs.com': (MyName)
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:
Example 2:
[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]


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 for List , and 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 and 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
Subtemplate
s.
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 '['. 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 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......[BlockName;block=tag_name;params]......HTML用于块定义的TBS标签必须在HTML标签里.
这个 TBS 标签也将在合并时被删除.
简化语法:
一个相关联的TBS field 被用来定义块(参见上面的关联语法).
例如:
HTML......[BlockName.ColumnName;block=tag_name;params]......HTML用于块定义的TBS 标签必须在HTML标签之间.
但它不一定是在块中首位的 TBS field.
元素
描述
BlockName
TBS 块名.
block=begin
指定块首.
block=end
指定块尾.
block= tag_name
指定块被一对配对的HTML标签包含 .... . HTML标签内容都属于块的内容.
- row 可以使用它来指定表格的行.
  block=row 等同于 block=tr.
- opt 可以使用它来指定HTML列表中的项.
  block=opt 等同于block=option.
params
可选. 一个或多个下列参数. 用 ';' 隔开.
使用何种语法?
'absolute' 语法很少会被使用到,因为TBS标签通常被放置在两个HTML标签之间.. 另一方面,它便于应用在文本编辑器上.
'关联' 语法使你可以仅使用一个TBS标签即可指定块.此外,没有必要去隐藏TBS标签,因为他们将在显示时被删除.这是相当实用的语法
'简化' 语法非常简单.它使你可以仅使用一个TBS标签来定义一个TBS块和 TBS Field . 这是最主流最实用的语法.
提示:你可以使用 '关联' 或 'absolute' 语法来完成 Html 标准的自定义标签.
例如:
Hello [blk1.column1;block=custom_tag], how are you?

块的参数:
参数
描述
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.
块的部分:


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