TBS Manual

Subject	Description

• Introduction
Basic principles
Installation
Mini examples
• PHP side
• To begin
method LoadTemplate()	load the contents of a template from a file
method MergeBlock()	merge a part of the template with a data source
method Show()	automatic processing and display of the result
• Advanced
method GetBlockSource()	returns the source of the definition of a block
method MergeField()	merge a specific field with a value
method PlugIn()	execute a plug-in's action
property NoErr	avoid error messages
property Render	to alter the merge ending option
property Source	returns the current contents of the result
property TplVars	returns template variables
Object Oriented Programming (OOP)	to make TBS OOP friendly
• HTML side
• TBS fields
Definition and syntax
Parameters
[var] fields
Onload [var] fields
Special [var] fields
• TBS blocks
Definition and syntaxes
Parameters
Sections of block
Serial display (in columns)
Dynamic queries / sub-blocks
• Miscellaneous
Automatic fields and blocks
Subtemplates
Conditional display overview
• Coding plug-ins
Database Plug-ins
Other plug-ins
• Summary
TBS Field's parameters
TBS Block's parameters
Names of Special Fields and Blocks

Loads a template for the merging process.
The complete contents of the file is stored in the Source property of the TBS object.
If the file is not found, then it will also be searched in the folder of the last loaded template (since TBS version 3.2.0).

Syntax: $TBS->LoadTemplate(string File{, string HtmlCharSet})

Argument	Description
File	Local or absolute path of the file to load.
HtmlCharSet	Optional. Indicates the character encoding (charset) to use for Html conversion of the data when they will be merged. It should be the same as the charset of the template. The default value is '' (empty string) which is equivalent to 'ISO-8859-1' (Latin 1). If your template uses a special charset, then indicate the Html value for this charset. In a Html page, the charset is placed at the beginning of the file, in the attribute 'content' of a <Meta> tag. The charsets supported by TBS are the charsets supported by the PHP function htmlentities(). For example: 'BIG5' (Chinese) or 'EUCJP' (Japanese).

No Html conversion:
If you use value False as the parameter HtmlCharSet, data will to not be converted when merged to the model.

User function:
If your charset is not yet supported by PHP, you can indicate a user function that will perform the Html conversion. For this, use the parameter HtmlCharSet with the syntax '=myfunction'.
Since TBS version 3.0, it's also possible to indicate a method of a class (see OOP).
The user function must take a string argument and return the converted string.

Adding the file at the end of the current template:
You can use the keyword '+' instead of the the charset to have the file added to the end of the current template. Charset parameter stay the same as for the first template.

Merges one or several TBS blocks with records coming from a data source.
by default, this method returns the number of merged records (more exactly, it is the number of the last record), but it can also return the full merged record set (see argument BlockName).

TinyButStrong supports several data source types in native:
Php data: an array, a string, a number.
Databases: MySQL ; PostgreSQL ; SQLite.
You can also add a new one: 'database plug-ins'.

Syntax: int $TBS->MergeBlock(string BlockName, mixed Source{, string Query})

Argument	Description
BlockName	Indicates the name of the TBS block to merge. You can merge several blocks with the same data by indicating their names separated by commas. If you add '' as a block name, then the method will return the full merged record set as a PHP array, instead of the number of records. Versioning: the keyword '' is supported since TBS version 3.0.
Source	Indicates the data source to merge. The table below shows the possible values according to the data source type.
Query	Optional. Indicates the SQL statement which returns the records to merge. The table below shows the possible values according to the data source type.

Link between the block and the records:

The MergeBlock() method searches in your template for the specified TBS block name. Then, the block is repeated as many times as there are records in the data source.
To display the data of a record, you have to use a linked TBS Field. A TBS Field is linked when the name of it is composed of the block's name followed by a dot and a column's or a key's name in the record set. A linked field must be inside the block.

Example:

Block's name: block1
Columns returned by the query: field1,field2,field3
Linked TBS Fields: [block1.field1], [block1.field2], [block1.field3]

If no block's definition is found in the template, then the MergeBlock() method will merge the first record with all linked fields found in the template.

You can also define more advanced blocks. For more information, refer to chapter TBS Blocks.

Merging several blocks with the same data:

You can merge several blocks with the same data by indicating their names separated by commas in the BlockName parameter. In this case, the query is opened only one time, and records are buffered to feed blocks.
Example: $TBS->MergeBlock('block1,block2,block3','mysql','SELECT * FROM MyTable');

Returning the full merged record set:

In some cases, it may be useful for you to retrieve the full record set after the merge. For that, you simply have to ad the keyword '*' in the list of block's names. Use this feature with care, because it save the merged data in the memory which can take resources.
Example: $data = $TBS->MergeBlock('bloc1,*','mysql','SELECT * FROM MaTable');

Counting the records:

To display the number of the record in the template, use a TBS Field linked to the virtual column '#'. If you put this field outside the block, it will display the total number of records.
Example: [block1.#]

The virtual column '$' will display the key of the current record if the data source is a Php array.
Example: [block1.$]

Resource and Request arguments according to the data source type:

Data Source Type	Source	Query
Text (*)	The keyword 'text'	A text
Number (*)	The keyword 'num'	A number or a special array (see below)
Clear (*)	The keyword 'clear'	-
Conditional (*)	The keyword 'cond'	-
PHP Array (*)	A Php array	-
	The keyword 'array'	A Php Array
	The keyword 'array'	A string that represents an array contained or nested in a PHP global variable (see below)
MySQL	A MySql connection identifier or the keyword 'mysql'	An SQL statement
MySQL	A MySql result identifier	-
PostgreSQL	A PostgreSql connection identifier	An SQL statement
PostgreSQL	A PostgreSql result identifier	-
SQLite	An SQLite connection identifier	An SQLite statement
SQLite	An SQLite result identifier	-
custom	A keyword, an object or a resource identifier not mentioned in this table. See the chapter 'database plug-ins'.	An SQL statement or something else.

(*) See explanations in the chapter below.

Php data sources:

Text

The argument Source has to be equal to 'text'.
The whole block is replaced by the text (it must be a string) given as the Query argument. No linked Fields are processed except '#' which returns 1, or 0 if Query is an empty string.
Example: $TBS->MergeBlock('b1','text','Hello, how are you?');

Number

The argument Source has to be equal to 'num'.
The argument Query can be either a number or an array.

arg Query	Returned Record Set
Number:	This number has to be positive or equal to zero. The returned Record Set consists of a column 'val' where the value goes from 1 to this number .
Array:	This array has to contain a key 'min' and a key 'max' and eventually a key 'step'. The returned Record Set consists of a column 'val' which goes from the 'min' value to the 'max' value.

Examples:

$TBS->MergeBlock('b1','num',12);
$TBS->MergeBlock('b2','num',array('min'=>20,'max'=>30));
$TBS->MergeBlock('b3','num',array('min'=>10,'max'=>20,'step'=>2));

Clear

The argument Source has to be the keyword 'clear'.
All blocks and sections are deleted. It is the same thing as merging with an empty array.
Example: $TBS->MergeBlock('b1','clear');

Conditional

The argument Source has to be the keyword'cond'.
The block is merged like it was a conditional blocks onload and onshow. The block is not merged with data, and so it must have no linked TBS field. Each block section needs a parameter when or a parameter default. See conditional blocks for more details.
Example: $TBS->MergeBlock('bz','cond');

Array

The argument Source has to be a PHP Array or the keyword 'array'. If you use the keyword 'array', then the argument Query has to be a Php Array or a string that represents an array contained or nested in a global variable.

String syntax: 'globvar[item1][item2]...'

'globvar' is the name of a global variable $globvar which must be an array.
'item1' and 'item2' are the keys of an item or a subitem of $globvar.
Example:

$TBS->MergeBlock('block1','array','days[mon]');
This will merge 'block1' with the value $day['mon'] assuming it is an array.

It is possible to represent variable's name without items.
Example:

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

There are two advantages in using a string to represent the array:
-> Items will be read directly in the Array (assigned by reference) instead of reading a copy of the items. This can improve the performance.
-> You can use dynamic queries.

Displaying the key of current record:
You can use the virtual column '$' which will display the key of the current record. This can be useful especially for dynamic queries and sub-blocks.
Example: [block1.$]

Structure of supported arrays:
Items of the specified Array can be of two kinds: simple values with associated keys (case 1), or array values for whom items are themselves simple values with associated keys (case 2).

Case 1:

Example:

['key1']=>value1
['key2']=>value2
...

The returned Record Set consists of a column 'key' containing the name of the key, and a column 'val' containing the value of the key.

Case 2:

Example:

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

The returned Record Set consists of the columns 'column1', 'column2',... with their associated values.

Terminates the merge.

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

The Show() method performs the following actions:
- Merge [var] fields,
- Merge [onshow] fields,
- Display the result (this action can be cancelled by Render property/argument),
- End the script (this action can be cancelled by Render property/argument).

The Render property/argument allows to adjust the behaviour of the Show() method. See the Render property for more information.

Returns the source of the TBS Block.
Only the definition of the first section of block will be returned, unless the Sections argument is set to True.
If no block is found, the method returns False.

Syntax: string $TBS->GetBlockSource(string BlockName {, boolean Sections}{, boolean DefTags})

Argument	Description
BlockName	The name of the block to search for.
Sections	Optional. The default value is False. If this parameter is set True the method returns an array that contains the definitions for all the sections of the named block. The first section is returned into the item [1] of the array.
DefTags	Optional. The default value isTrue. by default, the method GetBlockSource() returns the source of the block including its definition tags. If you'd like those tags to be deleted, then force the argument DefTags to False. If the block is defined with a simplified syntax then the definition tags will not be deleted anyway because they are also Field tags. Versioning: this argument is supported since TBS version 3.0.

This method enables you to get the source of a block in order to manually handle the merging.
After that, if you need to replace the block with text, you can use the MergeBlock() method with the 'text' parameter.

Replaces one or several TBS Fields with a fixed value or by calling a user function.
Since TBS version 3.0, it's also possible to indicate a method of a class (see OOP).
Each TBS fields having the specified base name will be merged.
It is also possible to merge the special [var], [onload] and [onshow] (see below).

Syntax: $TBS->MergeField(string BaseName, mixed X {, boolean FunctionMode})

Argument	Description
BaseName	Base name of the TBS Fields. For example 'account'.
X	The value to display (or a string that represent the name of a user function if the argument FunctionMode is set to true).
FunctionMode	Indicates that the value to display is calculated by a user function. The default value is false. If this argument is set to true, then X must be a text string giving the name of the user function. This function must exist and have the syntax described below.

Merging with a value:

X can be numeric, string, an array or an object. For an array or an object, names of TBS Fields must have suffixes like [var] Fields.

Example:

$TBS->MergeField('account',array('id'=>55,'name'=>'Bob'));

In this example, the fields [account.id] and [account.name] will be merged.

Merging with a user function:

TBS calls this function for each field found in the template.
This function must have the following syntax:

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

When the function is called, its argument $Subname has for value the suffix of the field's name (example: for a field named 'ml.title', $Subname will have the value 'title'). And the optional argument $PrmLst contains an associative array with the field's parameters. The function must return the value to be merged.

Example:

$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'] ;
}

In this example, a field such as [ml.title] will be merged with the value returned by m_multilanguage('title').

Merge special fields:

You can use the method MergeField() in order to force the merge of the special fields [var], [onload] and [onshow]. but in this case, only the first argument should be indicated.
Example: $TBS->MergeField('var');

Versioning: the merge of special fields is supported since TBS version 3.0. It replaces the old method MergeSpecial() which is not supported anymore.

Enables you to call a TBS plug-in's command, or to install a TBS plug-in.

Syntax: mixed $TBS->PlugIn(mixed arg1, mixed arg2, ...)

Remind: in order to have your TBS plug-in working, its PHP script must be included in your application before.
Example: include_once('tbs_plugin_xxx.php');
And aslo, every TBS plug-in should have a key as explained at Plug-ins.

Calling a plug-in's command:
Use the plug-in's key as the main argument. Next arguments are for the called plug-in's purpose.
Example:

$TBS->PlugIn(TBS_XXX,$arg1,arg2);

In this example, the plug-in identified by the key TBS_XXX is called.

Remarque : when you call a plug-in's command for the first time this plug-in is automatically installed on the TBS instance ($TBS).

Installing a plug-in:
Although some plug-ins are automatically installed, it can be useful in some other cases to make a manual installation. For this, use the constant TBS_INSTALL with the plug-in's key.
Example:

$TBS->PlugIn(TBS_INSTALL,TBS_XXX);

In this example, the plug-in identified by the key TBS_XXX is installed.

Remarks:
* A plug-in is installed relativelly to a TBS instance (a variable $TBS for example). If you are using a second TBS instance (for example $TBS2) then you will also need to install the plug-in on this instance.
* A plug-in is installed automatically when you call one of its commands using the method PlugIn() (se above).

Versioning: the method PlugIn() is supported since TBS version 3.0.

Enables you to avoid all TinyButStrong error messages for next operations. Default value is false. This property is dedicated to on line professional sites, because you will have no more indication about the good running of the merge. It is often more judicious to use parameter noerr which enables you to avoid messages concerning one particular TBS tag.

Syntax: boolean $TBS->NoErr

Example:

$TBS->NoErr = true; // no more error message displayed.

Versioning: property NoErr is supported since TBS version 3.0.

Indicates how the merging ends.
The value must be a combination of the following constants.
The default value is (TBS_OUTPUT + TBS_EXIT).

Syntax: int $TBS->Render

The Render property changes the behaviour the methods Show() and CacheAction().

Constant	Description
TBS_NOTHING	Indicates that none of the actions below are proceeded at the end of the merge.
TBS_OUTPUT	Indicates that the result of the merge must be displayed. TBS uses the Php command Echo.
TBS_EXIT	Indicates that we have to quit the script just after the end of the merge.

This property contains the source of the template currently merged. It is read/write.
When TinyButStrong processes a merging (when using the MergeBlock() method for example), the Source property is modified immedialty.

Syntax: string $TBS->Source

Notes:
- The LoadTemplate() method loads a file into the Source property and merges the [onload] fields automatically. Thus, Source may be different from the original template after LoadTemplate().
- The Show() method merges fields [onshow] and [var] before to display the result.

In order to load a template stored into a Php variable, you can code:

$TBS->Source = $my_template;
$TBS->MergeField('onload'); // force the merge of [onload] fields if any

In order to store the result at the end of the merging, you can code:

$TBS->Show(TBS_NOTHING) // terminate the merging without leaving the script nor to display the result
$result = $TBS->Source;

Contains the array of template variables corresponding to current template.

Syntax: array $TBS->TplVars

You can define template variables using one or several onload automatic fields with parameter tplvars. All parameters that follow parameter tplvars are added to the TplVars property when the LoadTemplate() method is called.

Example:
[onload;tplvars;template_version='1.12.27';template_date='2004-10-26']
This TBS tag will create two items equivalent to the PHP code:
$TBS->TplVars['template_version'] = '1.12.27';
$TBS->TplVars['template_date'] = '2004-10-26';

Remarks:
- Parameter tplvars works only with onload automatic fields.
- You can use parameter tplvars several times in the same template.

TinyButStrong integrate a technique to call methods or properties of objects that you've coded at the PHP side.

Calling methods of a class without created object:

The following TBS features support the call to the methods of a class without created object.

Feature	Example
Parameter ondata	[blk1.column1;block=tr;ondata=MyClass.methA]
Parameter onformat	[blk1.column2;onformat=MyClass.methB]
Method LoadTemplate()	$TBS->LoadTemplate('mytemplate.htm','=MyClass.methC');
Method MergeField()	$TBS->MergeField('myfield','MyClass.methD',true);

Remark: Methods call using this technique must respect the function syntax expected by the feature (see the description of the corresponding feature).

Calling created objects:

TBS has an ObjectRef property that is set to false by default, and that you can use to reference your objects already created. You can reference an object directly on the ObjectRef property, or you can reference some using PHP arrays.
Example:

$TBS->ObjectRef =& $MyObject1;
You can use an array if you have several objects reference:
$TBS->ObjectRef['item1'] =& $MyObject1;
$TBS->ObjectRef['item2'] =& $MyObject2;
You can use as many levels as you wish:
$TBS->ObjectRef['item3']['a'][0] =& $MyObject4;

Remarks:
* Think to use the assignment by reference using "=&" instead of "=", otherwise a copy of the object will be created.
* Since an object is referenced under ObjectRef, its sub objects will also be accessible by the TBS syntax.

• Using ObjectRef in [var] fields:
Use the symbol '~' to call what is referenced under ObjectRef.
For example:

The field		Will call
[var.~propA]		$TBS->ObjectRef->propA
[var.~propA.propB]		$TBS->ObjectRef->propA->propB
[var.~item2.propA]		$TBS->ObjectRef['item2']->propA
[var.~item2.methX]		$TBS->ObjectRef['item2']->methX()
[var.~item2.methY(a,b)]		$TBS->ObjectRef['item2']->methY('a','b')

Remark:
TBS proceeds to a coherence control, it will determine itself whether your [var] field definition is calling to ObjectRef via an array's item, an object's property or an object's method. Anyway, take care that your [var] field must call a value at the end, not an object.

• Using ObjectRef in other TBS features:
The following TBS features support the call to the methods of objects referenced under ObjectRef.

Feature	Example
Parameter ondata	[blk1.column1;block=tr;ondata=~item1.methA]
Parameter onformat	[blk1.column2;onformat=~item1.methB]
Method LoadTemplate()	$TBS->LoadTemplate('mytemplate.htm','=~item1.methC');
Method MergeField()	$TBS->MergeField('myfield','~item1.methD',true);
Method MergeBlock()	$TBS->MergeBlock('blk1','~mydb','SELECT * FROM t_table');

Remark: Methods call using this technique must respect the function syntax expected by the feature (see the description of the corresponding feature).

A TBS field is a TBS tag which has to be replaced by a single data item.
A TBS fields must have a name to identify it (which does not have to be unique) and can have parameters to modify the displayed value.

Syntax: HTML ... [FieldName{;param1}{;param2}{;param3}{...}] ... 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.
param1	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, semicolons or quotes, then you can use single quotes as delimiters. Example: frm='0 000.00' Use two single quotes to define a normal single quote character in a delimited string. Example: ifempty='hello that''s me' 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 <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 1: <img href="[var.link;magnet=img;mtype=m*]"> Example 2: <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>

comm

Widen the bounds of the TBS Field up to the bounds of the commentary Html tags which surround it, or up to another specified couple of Html tags.
Example:

xxx  yyy

or

xxx <div> [myfield;comm=div] here some comments </div> yyy

are strictly identical to:

xxx [myfield] yyy

This parameter is particularly useful for the template designing when you are using a Visual HTML Editor (such as Dreamweaver or FrontPage).

Versioning: Support for none commentary Html tags was added in TBS 3.0.

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.
See also: getbody script

getbody

To be used with parameter file or script. Indicates that not all the file contents is loaded but only the body part delimited with tags <body> and </body>. It is possible to precise another couple of tag using the syntax getbody=tag.
Example:

[onload;file=header.htm;getbody]

Versioning: parameter getbody is supported since TBS version 3.0. In previous versions, it was automatically processed when using parameter file. Now it becomes explicit.

script=filename

Execute the Php script just before replacing the TBS field.
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.

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
~=	match the regular expression (since TBS version 3.0)

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.
Since TBS version 3.0, it is also possible to define several couples of if/then in the same 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.
Since TBS version 3.0, it is also possible to define several couples of if/then in the same field.
Examples:

[var.image;if [val]='';then 'image0.gif']
[var.x;if [val]=1;then 'one';if [val]=2;then 'two';else 'more']

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.
Since TBS version 3.0, it's also possible to indicate a method of a class (see OOP).
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.

ope=action

Makes one or several operations on the value to merge. You can define several operations to be processed in order by separating them with coma (,).
Example:

[var.x;ope=add:-1,mod:10]

Supported operations are:

max:n	Limit the text string to a maximum of n characters. If the string is cut, then its end is replaced with dot lines '...'. Example: [var.caption;ope=max:10] Add parameter maxhtml to indicate that the value before merging can contain Html characters. Add parameter maxend to change the cuting symbol. Example: [var.caption;ope=max:10;maxhtml;maxend='+']
mod:n	Apply the modulo n to the value to merge. Example: [var.numlig;ope=mod:7]
add:n	Add the numeric n to the value to merge. Example: [var.number;ope=add:-1]
mul:n	Mutlyplies the value to merge by the numreic n.
div:n	Divises the value to merge by the numeric n.
list	If the value before merging is a Php Array, then its items are displayed separated with a coma (,). Example: [var.myarray;ope=list] Add parameter valsep in order to change the item separator. Example: [var.myarray;ope=list;valsep='+']

Versioning:
- Parameter ope is supported since TBS version 3.0. It replace parameter max which doesn't exist since this version.
- Multiple operations and 'mul" and "div" are supported since TBS version 3.2

frm=format

Specify a format to display for a data item which type is date/time or numeric. It is possible to use a conditional format which changes depending on the sign of the value. The format is considered as numeric type as soon as it contains the character 0, otherwise it is considered as date/time type.

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.
w	number of the day in the week (from 0 to 6)
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, rr, nn, ss:	hour-24, hour-12, minutes, seconds forced on two digits.
h, r	hour-24, hour-12
hm, ampm, AMPM :	12h format of the hour, "am" or "pm" signal , "AM" or "PM" signal.

Other characters are kept. It is possible to protect the strings inside by putting them between 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

Versioning:
- Keywords ampm and AMPM are supported since TBS version 3.0.
- Keyword hm was supported since TBS 3.0 and is deprecated since TBS version 3.2.
- Keywords rr, r, and h are supported since TBS version 3.2.

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

Example:
[chp;frm='dd mmmm yyyy';locale] will display 21 décembre 2002 if you have defined before setlocale(LC_TIME,'fr'); at the PHP side.

Remark:
* Parameter locale works only if local parameters have been configured on your server. If it's so, then the function setlocale() used with valid arguments will return the value true.
* For reasons due to PHP, the weyword xx for frm does not work with parameter locale.
* For reasons due to PHP, the weyword d fro frm works like dd with parameter locale.

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.

A [var] field is a TBS Field which displays a Php variable.
The name of it must be composed by the keyword 'var.' followed by the name of the Php variable.
The parameters for standard TBS Fields are available for [var] fields.

For example [var.x] will be replaced by the value of $x. User variables and the predefined variables can be merged only if they are global.

You can also merge array's items, object's properties or object's methods using a dot (".") as separator. Resource variables are ignored.
For example:

[var.arr.item1]	will display	$arr['item1']
[var.arr.item2.a.0]	will display	$arr['item2']['a'][0]
[var.obj.prop1]	will display	$obj->prop1
[var.obj.methA]	will display	$obj->methA()
[var.obj.methB(x,y)]	will display	$obj->methB('x','y')
[var.arr.item3.prop2.item4	will display	$arr['item3']->prop2['item4']

Versioning: methods with arguments inside [var] fields are supported since TBS version 3.0.

When are [var] fields merged?
[var] fields are merged when you are calling the Show() method. Except for parameters file, script, if, then, else and when. [var] placed inside one of those parameters will be merged when the parameter is processed.
Examples:

The field [var.x] will be merged during Show().
But in [onload;when [var.x]=1;block=div] it will be merged during LoadTemplate() because of the [onload] field.

You can also force the merge of [var] fields or other types at anytime using the MergeField() method.
Versioning: [var] fields are processed inside parameters "then" and "else" only since TBS version 2.02.

Embedded [var] Fields
The TBS tags which contain embedded [var] fields may not be merged as you could wish. You have to remember that [var] fields are merged only during Show() (except for few parameters named above).
Example:

[b1.name;block=tr;headergrp=[var.x]]
in this example, [var.x] will not be merged yet when you call $TBS->MergeBlock('b1',...)
The header group will then be badly defined.
You have to do one of the following :
- use a onload [var] field supported since TBS 3.2.0 : [b1.name;block=tr;headergrp=[onload.x]]
- call $TBS->MergeField('var') before $TBS->MergeBlock('b1',...)
- use a customized type of field [b1.name;block=tr;headergrp=[zzz]] merged using $TBS->MergeField('zzz',$x)

Security: how to limit [var] fields usage in templates?

You can limit the [var] fields usage by defining an Allowed Variable Prefix when you create the TinyButStrong object.

Example :
  $TBS = new clsTinyButStrong('','x1_');
In this example, only PHP global variables prefixed by 'x1_' are allowed in the template. Other [var] fields will produce an explicit error message when merging.
  [var.x1_title] will be merged if the global variable $x1_title exists.
  [var.x2_title] will produce an explicit error message.

NB: the first parameter '' de clsTinyButStrong() in the example above is used to define TBS tag delimiters. But this is not described in this manual.

An onload [var] field is like a [var] field but it will be merged during LoadTemplate() instead of during Show().
It is coded by using the prefix onload instead of var.

Example: [onload.x]

Onload [var] fields are very useful to optimize your template when a PHP variable has to be merged inside a block, or ensure that a PHP variable is merged when you call MergeBlock().

Please not that onload [var] fields are different from [onload] automatic blocks.

Versioning: onload [var] are supported since TBS version 3.2.0

A Special [var] field is a TBS Field which displays data provided by the TinyButStrong system.
The name of a Special [var] field has to begin with 'var..', followed by a keyword in the list below.
The parameters for standard TBS Fields are available for Special [var] fields.

Example: Date of the day : [var..now;frm='mm-dd-yyyy']

Name	Description
var..now	Date and hour of the server.
var..version	The version of TinyButStrong.
var..script_name	The name of the PHP file currently executing.
var..template_name	The name of the last loaded template file. It is the name given to the LoadTemplate() method.
var..template_date	The creation date of the last loaded template file.
var..template_path	The directory of the last loaded template file. It is the directory given to the LoadTemplate() method.
var..tplvars.*	The value of an item set in the TplVars property. ('*' must be the key of an existing item in the array)
var..cst.*	The value of a PHP constant. (* must be the name of an existing constant)
var..tbs_info	Information about TBS and installed plug-ins.

Versioning: special var fields "cst" and "tbs_info" are supported since TBS version 3.2.0

When are Special [var] fields merged?
Special [var] fields are merged with normal [var] fields. That is in the Show() method, this means just before the display of the merge result. But you can force the merge at any time with the MergeField() method.

A TBS block enables you define a zone and to display data from a record source.
You can define a TBS block using one or two TBS tags (see below).

Merging with data:
Merging a block with data is done using the MergeBlock() method. When a TBS block is merged with data, it is repeated as many times as there are records; and the associated TBS fields are replaced by the value of the columns stored in the current record.
A TBS field associated to a block is identified by its name which should be made of the name of the block followed by the name of the colmun to display and separated by a dot.
Examples:

- [Block1.ColA] This field will display the value of column ColA when block Block1 is merged.
- [Blokc1.ColB;frm='dd-mm-yyyy'] Champ avec un paramètre

Remark: when two separated blocks have the same name, then they will be considered has two sections of the same block. All content placed between those two sections of a block will be ignored and deleted between the merging. See sections of blocks to know more about sections.

Block syntaxes:

There are three possible syntaxes to define a TBS block:

Explicit Syntax:

Two TBS tags are used. One for the beginning of the block and another for the end of the block.

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

Those TBS tags for the block definition will be deleted during the merging.

Relative Syntax:

The block is defined by a pair of opening-closing Html tags. Only one TBS tag is required.

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

This TBS tag for the block definition must be placed between the pair of Html tags.
This TBS tag will be deleted during the merging.

Simplified Syntax:

An associated TBS field is used to define the block in a relative way (see the relative syntax above).

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

The TBS tag for the block definition (i.e. the block=... parameter) must be placed between the pair of Html tags. You are nor obliged to put the parameter block on the first field, it can be any of them inside the zone defined by the block.
Remark: you should not repeat the parameter block=... on each fields of the bloc, only one is enough. If you place several of them, this will be accepted by TBS but it may bring confusions about complementary parameters for block.

Which syntax to use?

The 'absolute' syntax is rarely used with Visual Editors because TBS tags have often to be placed between two Html tags. On the other hand, it is convenient for textual editors.

The 'relative' syntax enables you to indicate a block using only one TBS tag. Furthermore, there is no need to hide the TBS tag because it will be deleted during the displaying. This syntax is quite practical.

The 'simplified' syntax is really simple. It enables you to define a TBS block and a TBS Field with only one TBS tag. This syntax is the most current and the most practical.

Tip:

You can use the 'relative' or the 'absolute' syntax with custom tags using the Html standard.
Example:
<custom_tag>Hello [blk1.column1;block=custom_tag], how are you?</custom_tag>

Element

Description

BlockName

The name of the TBS block.

params

Optional. One or several parameters from the list below. Separated with ';'.

block=begin

Indicates the beginning of the block.

block=end

Indicates the end of the block.

block=tag
or
block=expr

Define a block bounded between the opening Html tag <tag...> and the closing Html tag </tag> which surround the TBS tag. The couple of indicated Html tags are integral part of the bloc.
Example:

<table id="tab1"> <tr><td>[b1.field1;block=tr]</td></tr></table>
The block is defined by the zone framed by pointillets.

Special marks:

block=_	Define a block on the text line which holds the TBS tag. A text line always ends with a new-line char. New lines for Windows, Linux and Mac are supported. This feature is very useful for a template with text contents for example.
block=tag/	By adding character / at the end of the tag's name, TBS won't retrieve the closing tag. The block will be defined on the single openning HTML tag which contains the TBS tag. This can be useful to multiply an image for example.

Note: special marks can be used for extending block too (see below).

Versioning: special marks "_" and "/" are supported since TBS 3.1.0.

Extending blocks:
You can extend the block's zone (or the section's zone) beyond the simple Html tag by using the following expressions:

To extend the block's zone on several successive tags:

<table><tr>[b1.field1;block=tr+tr+tr]</tr><tr>...</tr><tr>...</tr></table>
Note: you can specify tags of different types

To extend the block's zone on several successive tags placed before:

... <span>...</span><div>[b1.field1;block=span+(div)]</div> ...
Other example:
... <span>...</span> <div>[b1.field1;block=span+(div)+table]</div> <table>...</table> ...
The tag placed bewteen brackets means the one which contains the block's definition.

To exend the block's zone on a tag of the same type but with a higher encapsulation level:

<div> <div> [b1.field1;block=((div))] </div> </div>
The number of bracket means le encapsulation level of the tags.

Versioning : The Exending Blocks feature is supported since TBS version 3.0. Before that, you had to use parameters 'extend' and 'encaps' which are not supported anymore.

Block's parameters:

Parameter

Description

nodata

Indicates a section that is displayed only if there is no data to merge.

Example:

[b1.field1;block=tr]	[b1.field2]
[b1;block=tr;nodata]There is no data.

For more information about sections, see the chapter 'Sections of blocks'.

bmagnet=expr

Indicates an Html zone which must be deleted if the block is merged with no record (an emprt query, for example, or a PHP Array with no items). bmagnet has the same syntax as parameter block, i.e. that expr must be an Html tag or a TBS Extended block expression.
Example:

[b1.field1;block=tr;bmagnet=table]

[b1.field2]

In this example, the table will be deleted if there is no record to merge.

Remark: Value null is not accepted by MergeBlock() method as a data source, and it makes a TBS error instead of deleting the bmagnet zone. If you data source may be null, then you should make a check previously.
Example:

if (is_null($data)) $data = array();
$TBS->MergeBlock('b1',$data);

Versioning: parameter bmagnet is supported since TBS version 3.0.

headergrp=colname

Indicates a header section that is displayed each time the value of column colname changes.
colname must be a valid column name returned by the data source.
You can define several headergrp sections with different columns. Placement's order of headergrp sections in the block can modify the result.
For more information about sections, see the chapter 'Sections of blocks'.

footergrp=colname

Indicates a footer section that is displayed each time the value of column colname changes. See headergrp.

splittergrp=colname

Indicates a splitter section that is displayed each time the value of column colname changes. See headergrp.

parentgrp=colname

Indicates a parent section that is displayed each time the value of column colname changes. Unlike other sections, a parentgrp section allows normal sections inside itself. It's a way to define both a header and a footer in one section.

serial

Indicates that the block is a main block which contains serial secondary blocks.
For more information, see the chapter 'serial display (in columns)'.

p1=val1

Indicates the use of a dynamic query. All the occurrences of the string '%p1%' found in the query given to the MergeBlock() method are replaced by the value val1.
For more information, see the chapter 'dynamic queries / sub-blocks'.

ondata=fct_name

Indicates the name of a user Php function that will be executed during the block merging.
Since TBS version 3.0, it's also possible to indicate a method of a class (see OOP).
The function is called each time a record is taken from the data source. You can use the arguments of such a Php function to edit records before they are merged. The function must have the following syntax:
function fct_name($BlockName,&$CurrRec,$RecNum) { ... }

Argument	Description
$BlockName	Returns the name of the block calling the function (read only).
$CurrRec	Returns an associative PHP array containing the current record (read/write ; don't forget the & in the function header). If you set this variable to False, it ends the merging like it was the end of the record set.
$RecNum	Returns the number of the current record (read only, first record is number 1).

Examples:

function f_add_column($BlockName,&$CurrRec,$RecNum) {
$CurrRec['len'] = strlen($CurrRec['text']);
}

when expr1=expr2

Make the section conditional and define its condition. A conditional section is displayed only if its condition is verified.
Supported operators are:

= or ==	equal
!=	not equal
+-	greater than
+=-	greater than or equal to
-+	less than
-=+	less than or equal to
~=	expr1 match the regular expression expr2 (for experimented users)	Versioning: added in TBS 3.0

Both expr1 and expr2 must be string or numerical expressions. The expressions may contain [var] fields for an automatic block ([onload], [onshow]), or linked fields for a merged block.
Example:

<div>[onload;block=div;when [var.x]~='*to*'] ... </div>
The <div> block will be displayed only if $x>0.

Note: do not confuse parameter when (which works only for TBS blocs or sections) and parameter if (which works only for TBS fields). Thus, parameter when is taken into account only if parameter block exists in the same TBS tag.
See conditional blocks for more details.

default

Indicates a section of block that must be displayed only if no conditional section of the same block has been displayed.

several

Indicates that several conditional sections of the block can be displayed if several conditions are true. By default, conditional sections are exclusive.

Different blocks having the same name will be regarded as sections of the same block.
Sections can be used to:
- alternate the display (normal sections),
- display something if there is no data (NoData section),
- display a header each time the value of a column changes (grouping sections).

Normal sections:

When you define several normal sections, they will be used alternatively for each record.

Example:

[b1.caption;block=tr]

In this example, the block named 'b1' contains two normal sections. Records will be displayed alternatively with a green background and with a blue background.

NoData section:

The NoData section is a section displayed only if the data source has no records. There can be only one NoData section in a block. The NoData section is defined by adding the parameter nodata.

Example:

[b1.caption;block=tr]

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

Grouping sections:

Grouping sections are displayed every time a column's value in the record-set changes. You can define header, footer, splitter or parent sections using parameters headergrp, footergrp, splittergrp, and parentgrp. See block's parameters for more details.

Example:

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

Conditional sections:

Conditional sections are displayed only if their condition is verified. The condition for display is defined using parameter when. As soon as a section has this parameter, it becomes conditional. See Conditional display for more details.

Example:

[b1.name;block=tr]

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

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.

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.

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.

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==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 offers several tools for conditional display for both fields and blocks.

Conditional fields

For any TBS fields you can use parameters for conditional display, recalled below.

Parameter	Description
. (dot)	Display an Html unbreakable space if the field value is empty.
ifempty=value2	Display value2 if the field value is empty.
magnet=tag	Delete a tag or a pair of tags if the field value is empty.
if condition then value1 else value2	Display value1 or value2 depending on whether the condition is verified or not.
frm=format1\|format2\|format3\|format4	Changes the numeric format or date/time format depending on whether the value is positive, negative, zero or empty.

Example:
[var.error_id;if [val]=0;then 'no error';else 'error found']

Conditional sections

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.

Conditional section within normal blocks:

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.

Example:

Name: [b1.Name;block=tr]	normal section
Address: [b1.add_line1;block=tr;when [b1.address]=1] [b1.add_line2] [b1.add_zip] - [b1.add_town]	conditional section
No address.[b1;block=tr;default]	conditional section

Conditional section within automatic blocks:

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

Example:

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

Example:

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

Versioning: database plug-ins are supported since TBS version 1.8.

Coding a plug-in using PHP functions:

... (currently beeing rewritted, see TBS version 2.x manual) ...

Coding a plug-in using a PHP class:

... (currently beeing rewritted, see TBS version 2.x manual) ...

Coding plug-in using a PHP class to be referenced under property ObjectRef:

... (currently beeing rewritted, see TBS version 2.x manual) ...

Versioning: plug-ins are supported since TBS version 3.0.

Coding a plug-in using a PHP class:

• Plug-in's key:

Each plug-in has a plug-in key which is the name of its Php class. This key must be given to the method PlugIn() when you use it. Thus, it is recommended to define a PHP constant for the plug-in's key (see example below).

• Plug-in events:

A TBS plug-in must be a PHP class which contains one or several specific methods that will be recognized and plugged by TBS. Those specific methods are called plug-in events because they are executed automatically by TBS when the corresponding event occurs. A TBS plug-in can also have other methods and properties for internal purpose. A TBS plug-in must have at least the OnInstall event.

For example:

// TBS plug-in XXX
define('TBS_XXX','clsTbsPlugIng_XXX'); // That is the plug-in's key
class clsTbsPlugIng_XXX() {
function OnInstall(...) {...} // That is the OnInstall event
...
}

See the PHP file "tbs_plugin_syntaxes" to have all plug-in events, their usage and expected arguments. There is also a list of supported events at the bottom of this section.

The OnInstall event is special. It has to return an array with all activated events for the current plug-in (see the PHP file "tbs_plugin_syntaxes"). The OnInstall event is called when the plug-in is installed at the TBS instance.
This event can be called in three situations:
- When using method PlugIn() with the plug-in's key for the first time.
- When using method PlugIn() with the plug-in's key and the argument TBS_INSTALL.
- When a new TBS instance is created, if the plug-in's key has be added to the global array $_TBS_AutoInstallPlugIns[] (see file "tbs_plugin_syntaxes.php" for more details).

Property ->TBS:

As soon as the plug-in is installed on the TBS instance, a property ->TBS is automatically added to the plug-in, its value is a reference to the parent TBS instance. Remember this because this property can be very useful inside the plug-in's code.

Coding a plug-in using PHP functions:

The plug-ins' key is a string that you choose and which will be used for naming the function. It is recommended to define a PHP constant for the plug-in's key (see example below).

The plug-in events are coded using functions, and they names must be the string 'tbspi_', followed by the plug-in's key, followed by '_' and the event's name.
Example:

define('TBS_XXX','xxx');
function tbspi_xxx_OnInstall(...) {...}
...

All the rest works like for plug-in coded with a class. You must have at least the event OnInstall created, and it works the same way.

Remark: PHP functions are often faster than methods, but they don't let you having a ->TBS property to reach the parent TBS instance.

List of plug-in events:

	Plug-in Events	Description
•	OnInstall	Executed automatically when the plug-in is called for the first time, or when PlugIn() method is called with the specific argument for installing.
•	OnCommand	Executed when PlugIn() method is called. This is a way to execute any user command specific to the plug-in.
•	BeforeLoadTemplate	Executed when LoadTemplate() method is called. Can cancel TBS basic process.
•	AfterLoadTemplate	Executed at the end of LoadTemplate().
•	BeforeShow	Executed when Show() method is called. Can cancel TBS basic process.
•	AfterShow	Executed at the end of Show().
•	OnData	Executed each time a record of data is retrieved for a MergeBlock() process. (similar to parameter 'ondata' but for every block)
•	OnFormat	Executed each time a fields is being merged. (similar to parameter 'onformat' but for every fields)
•	OnOperation	Executed each time parameter 'ope' is defined with an unsupported keyword.
•	BeforeMergeBlock	Executed when bounds of a block are founded. Can cancel TBS basic process.
•	OnMergeSection	Executed when a section is merged, and before it is added to other sections.
•	AfterMergeBlock	Executed just before a merged block is inserted into the template.
•	OnSpecialVar	Executed when a non native Special Var Field (like [var..now]) is met.
•	OnMergeField	Executed on each field met when using the MergeField() method.

Parameter	Summary
htmlconv	Html conversion Mode for the field's value.
. (dot)	If the value is empty, then display an unbreakable space.
ifempty	If the value is empty, then display another value.
magnet	If the value is empty, then delete surrounding tags.
mtype	Use with magnet.
if	If the condition is verified, then change the value.
then	Use with if.
else	Use with if.
onformat	Executes a Php user function to modify the field merging.
frm	Apply a date-time or a numeric format.
locale	Use with frm. Display locale day and month's names.
protect	Protection mode for characters '['.
comm	Extends the field's bounds up to the Commentary tag that surround it.
noerr	Avoid some TBS error messages.
file	Includes the contents of the file.
script	Executes the Php script.
subtpl	Use with script or onformat. Turns the TBS instance into subtemplate mode.

Parameter	Summary
block	Defines the block's bounds.
nodata	Indicates the section that is displayed when there is no data in the data source.
headergrp	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	Sends a parameter to the dynamic query for the data source.
ondata	Executes a Php user function to modify the record when it has just been taken from the data source.
tplvars	Use with onload fields only. Define template variables.
when	Use with onload or onshow. Displays the section when the condition is verified.
default	Use with onload or onshow. Displays the section when no section is displayed.
several	Use with when. Indicate that several blocks of the group can be displayed.

Name	Summary
val	The keyword [val] can be used in field's parameters to represent the field's value.
var.*	Displays a Php variable.
var..*	Displays information about the TinyButStrong System.
#	Virtual column name for a block. It displays the record's number.
$	Virtual column name for a block. It displays the record's key if the data source is a Php Array.
onload	Automatic field or block, merged when the template is loaded.
onshow	Automatic field or block, merged when the template is shown.

Html Template	Php Program	Result
<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 Template	Php Program	Result
<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>

1.	Copy the file tbs_class.php in a directory of your Web site.
2.	At the beginning of your PHP program, add the lines: include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; Remark: if the TBS file tbs_class.php is in a different directory than your application, then you have to precise the directory in front of the TBS file name.