TBS手册2――翻译

块的部分:

拥有相同名称的不同块将被视为一个相同块的不同部分.
部分可以用来:
- 轮流显示 (普通部分),
- 显示空数据 (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]==1]

序列显示 (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 1 Rec 2 Rec 3 Rec 4

Rec 5 Rec 6 Rec 7 Rec 8

Rec 9 ... ... ...

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 0. It can either be placed inside the main block with the normal secondary block, or alone inside another serial block. The "empty" secondary block is optional.

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 (1 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',10,17) ;

Result of the merge:

|<

<

11

12

13

14

15

16

17

18

19

20

>

>|

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 = 10).
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 = 1).

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]==1] Status 1

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

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.
[ 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 [ 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==1) { // 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]=0; 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]=1] [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]=1] Light is ON.

[onload_ligth;block=tr;when [var.light]=0] 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]=0] 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	显示头一页(始终为 1).
nav.prev	显示上一页.
nav.next	显示下一页.
nav.last	显示最终一页 (-1 假如末知).
参数	概要
currpage	指定部分那是显示仅是当前页.Indicates a section that is displayed only for the current page.
endpoint	假如当前页为头页或尾页时返回空字串.
navpos	指定导航条为当前页数Indicates how the navigation bar is positioned compared to the current page number.
navsize	指定要显示第几页.
pagemin	指定第几页开始显示(即从第几页开始计数).

特殊的字段和块:

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