Site: www.tinybutstrong.com
Date: 2022-09-25

TinyButStrong Documentation

version 3.14
Template Engine for Pro and Beginners
PHP 8
PHP 7
PHP 5

Table of Contents:

Subject Description
   
• Introduction  
    Basic principles  
    Installation  
    Mini examples  
• PHP side  
    • To begin  
        create a new TBS object for working with templates
        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 SetOption() set TBS options
        method GetOption() get TBS options
        method ResetVarRef() reset the VarRef property
        method GetVarRefItem() get an item in the VarRef property
        method SetVarRefItem() set an item in the VarRef property
        method ReplaceFields() replace simple fields with long fields
        method GetAttValue()  
        method PlugIn() execute a plug-in's action
        property VarRef set variables to be merged with automatic fields
        property Assigned prepares information for a subsequent merging
        property Source returns the current contents of the result
        property TplVars returns template variables
        Object Oriented Programming (OOP) to make TBS OOP friendly
• Template side  
    • TBS fields  
        Definition and syntax  
        Parameters  
        Order of processing parameters  
        Automatic fields  
        Special automatic fields  
    • TBS blocks  
        Definition and syntaxes  
        Parameters  
        Sections of block  
        Automatic blocks  
        Parallel merge (dynamic columns)  
        Serial display (in columns)  
        Subblocks  
        Automatic subblocks  
        Subblocks with dynamic queries  
     • Miscellaneous  
        Subtemplates  
        Conditional display overview  
• Improve TBS by coding  
    Extended methods  
    Block alias  
    Data Reader Plug-ins  
    Other plug-ins  
• Summary  
    TBS Field's parameters  
    TBS Block's parameters  
    Names of Special Fields and Blocks  

Introduction:

TinyButStrong (TBS) is a PHP class useful to develop an application in a clean way, separating PHP scripts and XML/HTML/Text files. With TBS, the files are generated dynamically by merging a template with data. It is called a Template Engine.

The name TBS comes from the fact that this tool contains only 8 functions and yet, it is very powerful. It allows you to merge templates with your PHP variables or your MySQL, PostgreSQL, or SQLite.

TBS has been engineered so that you can develop your templates with ease using any visual editors (like Dreamweaver or FrontPage). But if you are used to designing your templates with a text editor, it is nice as well. TBS also enables you to create JavaScript dynamically.

As the name of it tells, TBS is easy to use, strong and fast. It is completely °~° freeware °~°.

Basic principles:

On the HTML side (or other file type):

You design a page which does not necessarily contain any PHP scripts, nor any programming. In this page you place TBS tags in the places where you want to display the dynamic data. This page is called a 'template'.

There are two types of tags: the 'fields' which are used to display dynamic data items, and the 'blocks' which are used to define an area, mostly in order to display records from a data source.

On the PHP side:

You use an object TBS variable to manage the merge of your template with the data. At the end, TBS shows the result of the merge.

Installation:

  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.

Explanations and technical details:

TinyButStrong is a library written in PHP, it's a component to be referenced in your own PHP programs. In technical terms, TinyButStrong is a PHP 'class' ; the name of this class is clsTinyButStrong.

The variable $TBS that you add at the beginning of your PHP program enables you to execute the merge of your template from your PHP application. In technical terms, the variable $TBS is an 'instance' of the clsTinyButStrong class.

Mini examples:

Example 1:

Html Template Php Program Result
<html>
  <body>
    [onshow.message] 
  </body>
</html>
<?php
     
  include_once('tbs_class.php');
  $TBS = new clsTinyButStrong;
  $TBS->LoadTemplate('template.htm');

  $message = 'Hello';
  $TBS->Show();
<html>
  <body>
    Hello
  </body>
</html>

Example 2:

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>

PHP side:

The merging of a template is done in a PHP program using an object variable declared as a clsTinyButStrong class.

Example of statement:

$TBS = new clsTinyButStrong;

This object allows you to load a template, to handle the merging of it with data, and then to show the result.

Example of PHP code:

include_once('tbs_class.php');
$TBS = new clsTinyButStrong;
$TBS->LoadTemplate('template.htm') ;
$TBS->MergeBlock('ctry','mysql','SELECT * FROM t_country');
$TBS->Show();

Here is the description of the TinyButStrong object:

create a new TBS object:

A TBS object is created as a new instance of the clsTinyButStrong class. A TBS object enables you to work with one or several templates using the object's methods and properties.

Syntax to create a new TBS object as of version 3.8.0: $TBS = new clsTinyButStrong({array Options})

Argument Description
Options An array of options to set for the option of the template engine. See all available options at the SetOption section.

Examples:

$TBS1 = new clsTinyButStrong;                                             // default behavior
$TBS2 = new clsTinyButStrong( array('chr_open'=>'{', 'chr_close'=>'}') ); // TBS tags will be like {var.x} instead of [var.x]
$TBS3 = new clsTinyButStrong( array('var_prefix'=>'tbs_fct_') );          // TBS will display only PHP global variables beginning with 'tbs_var_'
$TBS4 = new clsTinyButStrong( array('fct_prefix'=>'tbs_fct_') );          // TBS will call only PHP function beginning with 'tbs_fct_'

Versioning:

Before TBS version 3.8.0, the syntax to create a new TBS object was:
   $TBS = new clsTinyButStrong({string chr_delim {, string var_prefix {, string fct_prefix}}});
where:

  • chr_delim is the concatenation of (the option chr_open + the string ',' + the option chr_close). For example: '{,}'
  • var_prefix is the value for the option var_prefix
  • fct_prefix is the value for the option fct_prefix

method LoadTemplate():

Loads a template for the merging process. The complete contents of the file is immediately stored in the Source property of the TBS object, then [onload] fields and blocks are merged. 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 Charset = ''])

Argument Description
File Local or absolute path of the file to load.
This value can be null or '' (empty string) for special actions. See below for more details.
Charset

Optional. Will set the charset option.

Scope of the file path:

If the file is not found then its' also searched into the directory of the last loaded template, or the last loaded subtemplate.

Since TBS version 3.3.0, the file also searched into the include_path.

Adding the file at the end of the current template:

You can use the keyword '+' for the argument Charset to have the file defined by File added to the end of the current template. The current charset will not be modified.

Special actions using argument File:

Since TBS version 3.4.0.
If File is null, then all default actions (Plug-ins, [onload] tags, and Charset) are applied without loading any file.
If File is '' (empty string), then only the charset option is modified, without doing any other action. (deprecated since TBS version 3.8.0, use SetOption() instead)
In both cases, if Charset is '+', then it will be ignored and the current charset will not be modified.

Example:

$TBS->Source = $template; // load the template from a string
$TBS->LoadTemplate(null,'BIG5'); //  run plug-ins if any, and merges [onload] tags if any
...
$TBS->LoadTemplate('',false); // turn the charset to no-charset

method MergeBlock():

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

Versioning: since TBS version 3.12.0, MergeBlock() return false if no block and no field have been merged. Before that it returned 0.

TinyButStrong supports several data source types in native:

Php data: an array, a string, a number, an IteratorAggregate
PHP Databases Drivers: MySQL, PostgreSQL, SQLite, PDO
PHP Library Connectors: Doctrine DBAL, Zend_Db

You can also add a new one: 'database plug-ins'.

Syntax: mixed $TBS->MergeBlock(string BlockName, mixed Source [, string Query = '' [, mixed QryPrms = false]])

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.
QryPrms Optional. Extra parameters for the query. Few data source types are taking this argument in account.
Versioning: the argument QryPrms is supported since TBS version 3.7.0.

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: column1, column2, column3
Linked TBS Fields: [block1.column1], [block1.column2], [block1.column3]

If no block's definition is found in the template (that is parameter block is never used on the block's fields), 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 subnames

In a TBS field, you can refer to an array item, a method or a property using subnames:

An item of an array [block1.arr1.key1]
A property of an object: [block1.obj1.propZ]
A method of an object [block1.obj1.methA()]
A method of an object with argument : [block1.obj1.methA(arg1)]
Cascading subnames: [block1.arr1.key2.methA().PropZ]

This assumes the parent's name of a subname refers to an array or an object.

Remarks :

  • Using lot of subnames can decrease performance since the parsing is reassessed on each record.
  • Don't merge data having objects with methods that should not be called from a template. Because the template builder could invoke them erroneously.

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

You cannot merge several blocks having the same names because they are considered by TBS has a one and only block composed of several sections. Nevertheless, you can use a tip to get a similar behavior. If you use parameter p1 without value in the block definition, that does forces TBS to consider the section as a new block break, like it does for subblocks.

Example:

Id Name
[b.id;block=tr;p1] [b.name]
Id Name
[b.id;block=tr;p1] [b.name]

$TBS->MergeBlock('b','mysql','SELECT * FROM MyTable');

Versioning: this tip is available since TBS version 3.4.

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('block1,*','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
Assigned (*) The keyword 'assigned' or omitted -
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)
PHP ArrayObject A PHP object. Supported since TBS version 3.5.0. -
PHP Iterator
PHP IteratorAggregate
PDO A PDO object. Supported since TBS version 3.7.0. An SQL statement. Optional argument QryPrms can be used like with PDOStatement->execute(QryPrms).
Zend DB Adapter A Zend DB Adapter object. Supported since TBS version 3.8.0. An SQL statement. Optional argument QryPrms can be used like with $db->execute($sql, $prms).
MySQLi A MySQLi object. Supported since TBS version 3.7.0. An SQL statement
MySQL A MySql connection identifier or the keyword 'mysql' An SQL statement
A MySql result identifier -
PostgreSQL A PostgreSql connection identifier An SQL statement
A PostgreSql result identifier -
SQLite An SQLite connection identifier An SQLite statement
An SQLite result identifier -
SQLite3 An SQLite3 object An SQLite statement. You can use the optional argument QryPrms in order to bind values.
Exemple #1: array("value1", "values2").
Exemple #2: array(':p1'=>"value1", 'p2' => "value2").
Exemple #3: array(':p1'=>array("value1", SQLITE3_TEXT)).
An SQLite3Stmt object You can use the optional argument Query in order to bind values. See examples above.
An SQLite3Result object -
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:

• Assigned

The argument Source has to be equal to 'assigned' or be omitted. The block is merged with the arguments defined in the property Assigned.

Example : $TBS->MergeBlock('b1');

Versioning: the keyword 'assigned' is supported since TBS version 3.5.

• 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 VarRef or ObjectRef.

Syntax when Query is a string:

  • 'varref_key[key1]->PropZ[key2]->methA()[key3]...'
    or
  • '~objref_key[key1]->PropZ[key2]->methA()[key3]...'

In the first syntax, 'varref_key' is a key under $TBS->VarRef. (Thus VarRef must be an associated array). By default $TBS->VarRef is a reference on $GLOBAL. See property VarRef for more details.
In the second syntax, 'objref_key' is a key under $TBS->ObjectRef. (Thus ObjectRef must be an associated array). See property ObjectRef for more details.
Sub items like [key] represents a key assuming the previous item is an associative array.
Sub items like ->methA() represents a method assuming the previous item is an object. You can use argments ; for example : ->methA(arg1)
Sub items like ->PropZ represents a property assuming the previous item is an object.

The final item must be an array.

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 subblocks with dynamic queries.

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.

method Show():

Terminates the merge.

Syntax: $TBS->Show([int Render = false])

The Show() method performs the following actions:

  1. Merge [onshow] fields and blocks,
  2. Merge [var] fields (for compatibility with version prior to 3.2.0),
  3. Display the result (this action can be cancelled by defining another Render in the options or in the argument),
  4. End the script (this action can be cancelled by defining another Render in the options or in the argument).

The Render allows to adjust the behavior of the Show() method. See the Render option for more information.

method GetBlockSource():

Returns the source of a TBS Block from the template. If no block is found, the method returns false.

Syntax: string $TBS->GetBlockSource(string BlockName [, boolean AsArray = false [, boolean DefTags = true [, mix ReplaceWith = false]]])

Argument Description
BlockName The name of the block to search for.
AsArray Optional. The default value is false. If this parameter is true the method returns the source of the block as a PHP array instead of a string. If the result is an array, then each sections of the block is saved as an item. First item is index 1.
DefTags Optional. The default value is true. 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.

ReplaceWith Optional. Default value is false. If this argument is a string then the block source is replaced with it in the template. You can use ReplaceWith = '' (empty string) in order to delete the block source from the template.

Versioning: this argument is supported since TBS version 3.05.


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.

Versioning:

  • Since TBS 3.05 if AsArray is false then the method returns block with all its sections. Before TBS 3.05 it return only the first section.
  • Since TBS 3.05 if AsArray is true and the block is not found then the method returns false. Before TBS 3.05 it return an empty Array.

method MergeField():

Replaces one or several TBS Fields with a fixed value or by calling a user function. Each TBS fields having the specified base name will be merged.

Since TBS version 3.0, it's also possible to indicate a method of a class (see OOP).

It is also possible to merge the special [onload], [onshow] and [var] (see below).

Syntax: $TBS->MergeField(string BaseName, mixed DataOrFct [, boolean FctMode = false [, array DefaultPrm = false ]])

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

List of parameters to apply by default to the merged fields. Parameters have to be given as an associative PHP array. If a parameter is defined in both argument DefaultPrm and in the field, then the parameter of the field will be taken in account.
This argument is supported since TBS version 3.5.0.

Merging with data :

If argument FctMode is omitted or false, then TBS assumes DataOrFct is some data. It can be a numeric, a string, an array or an object. For an array or an object, names of TBS Fields must have suffixes like automatic fields ([onload] and [onshow]).

Example:

$TBS->MergeField('account',array('id'=>55,'name'=>'Bob'));
In this example, the fields [account.id] and [account.name] will be merged.

If you have subdata, MergeField also support subnames.

Merging with a user function:

If argument FctMode is true, then TBS assumes DataOrFct is the name of a global function. It can also be a method, see OOP for more details.

TBS calls this function for each field found in the template. The 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 automatic fields and blocks:

You can use the method MergeField() in order to force the merge of the automatic fields and blocks ([onload] and [onshow]). But in this case, only the first argument should be indicated.

Example: $TBS->MergeField('var');

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

Method SetOption():

Set one or several TBS options. See the list and desciptions of options below.
Some of the TBS options are a new way of setting old TBS features.

Versioning: methods SetOption() is supported since TBS version 3.8.0.

Syntax:

$TBS->SetOption(string $option_name, mixed $value)

Syntax for an array of options:

$TBS->SetOption(array $options)

Examples:

$TBS->SetOption('charset', false); // change the Charset option
$TBS->SetOption( array('chr_open'=>'{', 'chr_close'=>'}') ); // change several options

Syntaxes for options that are arrays:

Syntax 1: $TBS->SetOption(string $option_name, string $item, mixed $value)
Syntax 2: $TBS->SetOption(string $option_name, array $values)

Examples:


$TBS->SetOption('tpl_frms', 'curr', '0,000.0'); // add item 'curr' to the Template Formats
$TBS->SetOption('tpl_frms', 'curr', null); // delete item 'curr' from the Template Formats
$TBS->SetOption('tpl_frms', null); // delete all items from the Template Formats

$TBS->SetOption('include_path', 'tpl/english'); // add one path to the TBS include_path
$TBS->SetOption('include_path', 'tpl/english', null); // delete one path from the TBS include_path
$TBS->SetOption('include_path', null); // delete all pathes from the TBS include_path

Options

Option name Description
var_prefix

Limit the usage of automatic fields ([onload] [onshow] and [var]) in templates. TBS will display only keys prefixed with var_prefix. Other keys will produce an error message. The default value is '' (empty string) which means no limitation.

Example: if option var_prefix is set to 'my' then
fields [onload.my_key], [onshow.my_key] and [var.my_key] will be merged,
while [onload.me_key], [onshow.me_key] or [var.me_key] will procuce an error.

fct_prefix

Limit the usage of custom PHP functions (relative to parameters onformat and ondata) in templates. TBS will call only PHP function prefixed with fct_prefix. Other functions will produce an error message. The default value is '' (empty string) which means no limitation.

noerr

Enables you to avoid all TinyButStrong error messages. Default value is false.

The errors that were not displayed can however be returned with the special automatic field [onshow..error_msg].

Furthermore you can check the presence of error using property $TBS->ErrCount which counts TBS errors regardless of option noerr. When the noerr option is set to false, error messages are concatened in property $TBS->ErrMsg.

Option noerr is a bit different from the field's parameter noerr. Option noerr applies for any TBS error and will avoid the merge of a block or a field which has an error. While parameter noerr ensures the merge.

Option noerr is useful in two cases:

  • For professional sites put into production for whom no error message can be displayed. Take care 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.
  • For merges that do not accept TinyButStrong basic error messages. For example, an OpenOffice document will not open correctly if a TBS error occurs. Set option noerr to true and the field [onshow..error_msg] to display TBS errors in a viewable place of your OpenOffice document.

Versioning: the special automatic field [onshow..error_msg] is supported since TBS version 3.5.0.

auto_merge

A combination of the couple of options onload and onshow. Default value is true.

onload

Cancel the automatic processing of [onload] fields. This option accept only values true of false. Default value is true. This can be very useful especially, but not only, for some TBS plug-ins.

onshow

Cancel the automatic processing of [onshow] fields.This option accept only values true of false. Default value is true. This can be very useful especially, but not only, for some TBS plug-ins. Note that for compatibility, free [var] fields are automatically processed even if option onshow is set to false.

att_delim

This option tells which is string delimiter to be choosen by parameter att when a new Xml/Html attribute has to be created.

The supported values are :
  • " (double-quote),
  • ' (simple_quote),
  • false (whill choose the first attribute delimiter found).
protect

Protects all merged items by replacing the characters '[' with their corresponding XML/HTML code '&#91;'. Default value is true.

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.

charset

Indicates the character encoding (charset) to use for conversion of special characters when data will be merged. It should be the same as the charset of the template. In a Html page, the template charset is defined at the beginning of the file, in the attribute 'content' of a <Meta> tag.

The default value is '' (empty string) which is the correct value for charsets 'UTF-8', 'ISO-8859-1' (Latin 1), 'ISO-8859-15', 'cp866', 'cp1251', 'cp1252', and 'KOI8-R'. See the PHP function htmlspecialchars() for other charsets and technical explanations.

No character conversion:

If you use value false for the charset option, then data will to not be converted when merged into the model.
Note that parameters strconv can be use to define the conversion of special characters for one TBS field only.

User function:

If your charset is not yet supported by PHP, you can indicate a user function that will perform the conversion of special characters. For this, use the charset option with the syntax '=myfunction'.

Since TBS version 3.0, it's also possible to indicate a method of a class (see OOP).
Since TBS version 3.3.0, such a custom function should have a second argument for line break conversion.
Since TBS version 3.5.0, the charset option can also be an array containing an object and a method. Example: array(&$obj, 'mymethod').

Here is an example which gives the expected syntaxe:

function f_StrToXml($Txt string,$ConvBr boolean) {
  // Convert a string into an XML text.
  $x = htmlspecialchars(utf8_encode($Txt));
  if ($ConvBr) {
    $x = nl2br($x); // Convert any type of line break
    $x = str_replace('<br />', '<text:line-break/>',$x);
  }
  return $x;
}
chr_open

Opening delimiter for TBS fields.

It's recommended to let the default TBS delimiters, while changing them is working well. Default TBS delimiters are [ and ] because those characters are usable quite everywhere in XML/HTML documents, and they are located faster than delimiters { / } or ( / ) since they are rarer, especially in HTML.

chr_close

Closing delimiter for TBS fields. Must be only one character.

tpl_frms Enables you to define formats in the template that you can reuse for parameter frm. It is the same feature as parameter tplfrms, but option tpl_frms is defined in the PHP side, while parameter tplfrms is defined in the template side. You can manage this option using the syntax for options that are array.
prm_combo

Enables you to define a set of parameters that can be applied at the template side using parameter combo.
Argument $item must be the name of the combo.
Argument $value must be an associative array of parameters (param => value).

A combo definition can use parameter combo.
In order to define a set parameters with several if and then, you can to set one 'if' and one 'then' key associated to an array of values instead of a single value.

Examples:

// simple example
$TBS->SetOption('prm_combo', 'my_combo_1', array('att'=>'div#data-date', 'frm'=>'yyyy-mm-dd', 'magnet'=>'div', 'enlarge'=>'span'));

// example using a parameter that is supposed to have no value (value true used instead)
$TBS->SetOption('prm_combo', 'my_combo_2', array('noerr'=>true, 'magnet'=>'div'));

// example using multiple if/then parameters
$TBS->SetOption('prm_combo', 'my_combo_2', array('if'=>array('[val]=1', '[val]=2', '[val]=3'), 'then'=>array('One', 'Two', 'Three'), 'else'=>'More');

Versioning: option 'prm_combo' is supported since TBS version 3.11.0.

include_path

Enables you to define one or several paths where TBS should search files for method LoadTemplate(), parameters script and file.
You can manage this option using the syntax for options that are array.

block_alias Enables you to define block alias.
You can manage this option using the syntax for options that are array.
parallel_conf Enables you to define a configuration for parallel merge.
You can manage this option using the syntax for options that are array.
render

Indicates how the merging ends. The value must be a combination of the following constants. The default value is (TBS_OUTPUT + TBS_EXIT). The Render property changes the behavior of the Show() method.

Constant Description
TBS_NOTHING Indicates that none of the actions below are processed at the end of Show().
TBS_OUTPUT Indicates that the result of the merge must be displayed at the end of Show(). TBS uses the PHP command echo.
TBS_EXIT Indicates that PHP terminate all script at the end of Show(). TBS uses the PHP function exit.
methods_allowed

Allow methods in automatic fields. The default value is false. If you set this option to true, then automatic fields can call methods of its sub items. It is a security point to not allow methods by default on automatic fields because all global variables can be called by automatic fields until VarRef is redefined.

Example of automatic field calling a method: [onshow.my_objet.my_method]

Versioning: option 'methods_allowed' is supported since TBS version 3.8.2.

scripts_allowed

Allow to use parameter script. The default value is false. This is a security option.

Versioning: option 'scripts_allowed' is supported since TBS version 3.14.0.

old_subtemplate

Use the old sub-template technic of TinyButStrong 3.8.2 or lower. Since version 3.9.0 there is a more robust technic. The old technic consists in calling PHP output buffering. Use this option if you encounter strange behaviors with your old code when using parameter script and subtpl. This may happen only if you called the PHP command echo() in the sub-template script, which is quite rare.

Versioning: option 'old_subtemplate' is supported since TBS version 3.9.0.

Compatibility with previous TBS versions:

Some TBS options are a new way of setting old TBS features.
The old features are still suported for compatibility, but they become deprecated. It is better to use the TBS options.

Option Corresponding old feature Supported since version
var_prefix, fct_prefix, chr_open, chr_close was arguments of the instanciation: $TBS = new clsTinyButStrong() 2.0.0
charset was an arguments of the method $TBS->LoadTemplate() 1.90
render was a dedicated property: $TBS->Render 1.60
protect was a dedicated property: $TBS->Protect 1.64
noerr was a dedicated property: $TBS->NoErr 3.0.0
onload was a dedicated property: $TBS->OnLoad 3.6.0
onshow was a dedicated property: $TBS->OnShow 3.6.0
att_delim was a dedicated property: $TBS->AttDelim 3.5.0

Method GetOption():

Return the value of a TBS option.

Syntax: mixed $TBS->GetOption(string $option_name)

For supported options names, see method SetOption().

Versioning: methods GetOption() is supported since TBS version 3.8.0.

Method ResetVarRef():

Reset the VarRef property.

By default, VarRef refers to the PHP global variable $GLOBALS.

Syntax: $TBS->ResetVarRef(boolean $to_globals)

Argument Description
$to_globals Indicates if the property VarRef refers to $GLOBALS or is a new empty array.
- if $to_globals is true then VarRef refers to $GLOBALS.
- if $to_globals is false then VarRef is a new empty array.

Method GetVarRefItem():

Get an item value in the VarRef property.

This function uniformizes the way to get a VarRef item, whether VarRef refers to $GLOBALS or not.

Syntax: mixed $TBS->GetVarRefItem(string $key , mixed $default = null)

If VarRef if a dedicated array, then this function is the same as doing $TBS->VarRef[$key] ?? $default;

Versioning: methods GetVarRefItem() is supported since TBS version 3.13.0.

Method SetVarRefItem():

Set an item value in the VarRef property.

This function uniformizes the way to set a VarRef item, whether VarRef refers to $GLOBALS or not.

Syntax: $TBS->SetVarRefItem(string $key , mixed $value)

Syntax for an array of items: $TBS->SetVarRefItem(array $items)

If VarRef if a dedicated array, then this function is the same as doing $TBS->VarRef[$key] = $value;

Versioning: methods SetVarRefItem() is supported since TBS version 3.13.0.
The syntax for an array of items is supported since TBS version 3.13.1.

Method ReplaceFields():

Replace a set of simple TBS fields in the template with new definitions prepared at the PHP side. Note than this function does not merges any field ; it only replaces the definition of fields.

This is useful when you miss some place in the template for certain fields ; and also to delete some fields.

Syntax: mixed $TBS->ReplaceFields(array $fields [, string $block_name = false])

Argument Description
$fields An associative where keys are the names of the simple TBS tags to replace in the template ; and values are the new definition of the field.
The new definition of the field can be either :
- an array of TBS parameters, with the same principle as SetOption('prm_combo')
- a string that will replace the full TBS field's definition.
$block_name (optional) A block's name to add as prefix of all field's names (only if the new definition is an array of parameter)

In the template, the simple TBS fields to replace must have no parameters. Fields with parameters won't be replaced.

If the new definition of the field is an array of parameter, then the field's name is unchanged unless you use the special parameter 'name'.

Example:

// [s1] will be replaced with [s1;enlarge=div;magnet=table;frm=0.00;noerr]
// [s2] will be replaced with [onshow.x2;frm=0.00]
// [s3] will be replaced with [onshow.x3;noerr]
// [s4] will be deleted
$TBS->ReplaceFields( array(
  's1' => array('enlarge' => 'div', 'magnet' => 'table', 'frm' => '0.00', 'noerr' => true),
  's2' => array('name' => 'onshow.x2', 'frm' => '0.00'),
  's3' => '[onshow.x3;noerr]',
  's4' => '',
));

Versioning: methods ReplaceFields() is supported since TBS version 3.11.0.

Method GetAttValue():

Return the value of an XML/HTML attribute in the template.

Syntax: mixed $TBS->GetAttValue(string $field_name [, boolean $delete = true])

Argument Description
$field_name The name of a TBS field in the template. The field must have parameter att.
$delete (Optional, true by default) Indicate if the TBS field must be deleted after it is found.

The function will search the first TBS field with the given name, and then search for the attribute targeted by its parameter att.

The function takes in acount only the first field that is met. The TBS field is deleted if $delete is true, but is remains unmodified in the template if $delete is false.

The function return:

  • the value's attribute as a string,
  • true if the attribute is a boolean attribute (that is without value),
  • null if the TBS field is not found or if it has no parameter att,
  • false if the target XML/HTML element is not found or if the asked attribute is not found.

Versioning: methods GetAttValue() is supported since TBS version 3.11.0.

Method PlugIn():

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.

Remark: 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_XXX, TBS_XXX);    
In this example, the plug-in identified by the key TBS_XXX is installed.

Remarks:

  • A plug-in is installed relatively 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.

Property VarRef:

Property VarRef is the array of the items that will be merged with automatic fields ([onload], [onshow] and [var]).

Syntax: array $TBS->VarRef

By default $TBS->VarRef refers to the special $GLOBALS variable of PHP. This is for compatibility reasons, but it is recommended to use another array instead (see below).

You can set $TBS->VarRef to be a new empty array using the method $TBS->ResetVarRef(false);

You can also set $TBS->VarRef to be a reference to your own array : $TBS->VarRef =& $my_array;

Warning
As of TBS version 3.13.0, is not possible to access directly to the VarRef items when the property refers to $GLOBALS. This is because of the PHP restriction on $GLOBALS that occurs with PHP 8.1.
In order to ensure the compatibility to any situation, you can manage the items of VarRef using the methods $TBS->SetVarRefItem() and $TBS->GetVarRefItem().

Notes:

  • Method ResetVarRef($ToGlobal) is a shorthand for resetting property VarRef to $GLOBALS or to an empty array.
  • If property VarRef is changed by a sub-template, the change is available only for the sub-template.

Example when VarRef is a custom array (recommended):

$TBS->ResetVarRef(false); // VarRef is now a new empty array
$TBS->VarRef['my_item'] = "my value";
$TBS->SetVarRefItem('my_item', "my value"); // same as above but ensure the compatibility with any situation

Example when VarRef is attached to $GLOBALS (by default):

$TBS->VarRef['my_item'] = "my value"; // this will raise an error as of TBS version 3.13.0
$GLOBALS['my_item'] = "my value";
$TBS->SetVarRefItem('my_item', "my value"); // same as above but ensure the compatibility with any situation

Versioning:

  • Property VarRef is supported since TBS version 3.8. Before this version, the scope of automatic fields was PHP global variables.
  • Since TBS version 3.13.0, you cannot directly use the property $TBS->VarRef when it refers to $GLOBAL. This is because of a PHP 8.1 restriction. Use SetVarRefItem() and GetVarRefItem() instead.
    Before TBS version 3.13.0, property $TBS->VarRef used to be by default a PHP reference the $GLOBAL variable.

Property Assigned:

Enables you to define information for a subsequent merging which can be automatic or manual.

Syntax: array $TBS->Assigned

Property Assigned is a PHP array defined by the user. Arguments for methods MergeBlock() and MergeField() can be saved there. Arguments have to be saved in a PHP array with numerical keys and ordered following the syntax of those methods. It is possible to use optional string keys in order to define specific behaviors:

Optional key Description
'type'=>'mergeblock' Indicates that arguments are for the MergeBlock() method. This key is optional because it is the default behavior.
'type'=>'mergefield' Indicates that arguments are for the MergeField() method.
'auto'=>'onload' Indicates that the merging must be started automatically after [onload] tags.
'auto'=>'onshow' Indicates that the merging must be started automatically after [onshow] tags.
'merged'=>0 This key is added automatically by TBS during the merging. It counts the number of times this entry was merged.

Example of a manual merging:

$TBS->Assigned['b'] = array('b1,b2', &$cnt_id, 'SELECT id, name FROM table1');
... 
$TBS->MergeBlock('b'); // merge block b1 and b2 with the SQL query          

Example of an automatic merging:

$TBS->Assigned['b'] = array('b1,b2', &$cnt_id, 'SELECT id, name FROM table1', 'auto'=>'onload'); 

Example of merging fields:

$TBS->Assigned['f1'] = array('f1', $data, 'type'=>'mergefield');
... 
$TBS->MergeField('f1'); // merge field f1 witht the array $data

Notes:

  • To merge an assigned block or field, you just have to call the corresponding method using only the name of the assigned key. You can add the argument Source = 'assigned', but this is optional because it is the default value. In other words, $TBS->MergeBlock('b') is equivalent to $TBS->MergeBlock('b', 'assigned').
  • An assignment with 'auto'=>'onload' will be merged, of course, only if it is defined before calling the LoadTemplate() method.
  • You can pass some arguments by reference for you assignments. This is particularly useful for PHP 4 which is passing object with a copy by default.

Versioning: property Assigned is supported since TBS version 3.5.

property Source:

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

Syntax: string $TBS->Source

Notes:

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

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

$TBS->Source = $my_template;
$TBS->LoadTemplate(null); //  run plug-ins if any, and merges [onload] tags 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;

property TplVars:

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:

Object Oriented Programming (OOP):

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:

  • If you are coding for an old version of PHP prior to version 5, it is better to use the assignment by reference using "=&" instead of "=", in order to force objects to be passed by reference.
  • Since an object is referenced under ObjectRef, its sub objects will also be accessible by the TBS syntax.
• Using ObjectRef in automatic fields:

Use the symbol '~' to call what is referenced under ObjectRef.
For example (valid for both [onload], [onshow] and [var]):

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

Remarks:

  • TBS proceeds to a coherence control, it will determine itself whether your automatic 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 automatic field must call a value at the end, not an object.
  • When you are calling a method with arguments (like methY(a,b) in the example above), then TBS does a lazy analysis of arguments, without string delimiters. There is no intention to go further in the analysis because having PHP code in the template is not the purpose.
• 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).

Template side:

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. 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: TEMPLATE ... [FieldName{;param1}{;param2}{;param3}{...}] ... TEMPLATE

Element Description
FieldName The name of the Field.
The dot (.) is a special character reserved for sub-names in TBS fields. It enables you to indicate a column name (see Blocks) or sub-values (see MergeField()).
Warning: names that begin with onload, onshow and var are reserved for 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'
Literal single quotes in the string must be escaped using two adjacent single quotes ('').
Example: ifempty='hello that''s me'

A parameter can contain embedded TBS fields, but only under special circumstances:
- the embedded field is merged before the parent field,
- the embedded field if a [var] field placed into a parameter file, script, if, then, else or when.
In the other cases; the embedded TBS field will not be processed and will be taken as is, like text.
Examples:
[x;strconv=[var.y]] : [var.y] will not be merged and parameter "strconv" will have an unvalid value.
[x;if [var.y]=1] : [var.y] will be correctly merged and the "if" condition will be correctly evaluated.

Field's parameters:

Parameter Description
strconv=val

Ennables you to modify the string conversion for this TBS field only. Note that the string conversion used by default for all TBS fields is the charset option. It is often corresponding to an Xml/Html charset but not necessary.

You can specify several values using seperator '+'. Example : strconv=yes+js

The values can be one of the following keywords:

yes (default value) Performe the default special string conversion, including new lines.
no No special string conversion. Useful to modify Xml/Html source.
nobr Let the default string conversion, except new lines (useful for <pre> tags for example).
wsp Preserve white spaces (useful for spaces at the beginning of lines).
esc No special string conversion and double the single quote characters (').
js Convert the data item to a string that can be inserted between JavaScript text delimiters.
url Convert the data item to a string that can be inserted inside an URL. (supported since TBS version 3.5.2)
utf8 Convert the data item from ISO-8859-1 (Latin 1) to UTF-8. (supported since TBS version 3.6.0)
look Deprecated. Performs the default string conversion only if no Xml/Html entities are found inside the data item.

Versioning:

  • Parameter strconv is supported since TBS version 3.8.0. It is an alias of parameter htmlconv which was misnamed and becomes deprecated.
  • Keyword utf8 needs the mbstring PHP extension since TBS version 3.14.0.
. (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.

att=path

Move the current field into an attribute of an XML/HTML tag before it is merged. This parameter is very useful when it is too difficult for the template designer to place a TBS field into an attribute.

The value path must indicate the place of the attribute relatively to the current field.
If the attribute doesn't exist in the specified tag, then it is created.
If the attribute already exists in the specified tag and it has already a value, then the field replaces all the current value.
You can chose to place the field as an added value using parameter attadd.
You can complete the attribute's value by applying a mask to it using parameter ope=msk.
You can delete the attribute in case of empty value using parameter magnet=#.

Syntax for value path: att=[+][tag1+tag2+tag3+...#]attribute or att=.
By default the attribute is searched before the current field. But if '+' is the first character of the path, then it is searched after. If no tag list is specified, then the attribute is looked at in the first tag met in the search direction. If a tag list is used, tag1 is search first, then tag2, ... regardless of the direction of the search (before/after). You can put a tag name between one or several bracket levels in order to specify that the searched tag must embed the current field.

If you set att=. then TBS will assume that the TBS fields is already positioned inside the target attribute.

Examples:

[onshow.x;att=class] moves into attribute 'class' of the first tag placed before.
[onshow.x;att=div#class] moves into attribute 'class' of the first <div> placed before.
[onshow.x;att=+div#class] moves into attribute 'class' of the first <div> placed after.
[onshow.x;att=((div))#class] moves into attribute 'class' of the second embedding <div> placed before.
[onshow.x;att=table+div#class] moves into attribute 'class' of the first <div> after the first <table> placed before.

Notes:

  • Before TBS version to 3.10.0, method MergeBlock() could not move a TBS field over another TBS field placed after it. This makes a TBS error to occur.
  • When the attribute has no value before the field is moved, then TBS chooses what string delimiter to use regarding other attributes (XML/HTML accepts both (") and (')). You can force the delimiter you need using option att_delim.

Versioning: Parameter att is supported since TBS version 3.5.0

attadd

To be used with parameter att. Indicate that the field is added into the attribute's value, instead of being replacing the attribute's value. Please note that the added value won't be simply concatenated with previous values, it will be added with a space character separator in order to perform an adding to the meaning of attributes.

Example:

<div class="style1">[onshow.x;att=class;attadd]
in this example, if we have $x='style2' then we obtain <div class="style1 style2">

There is no way for now to simply concatenate the field's value with the previous attribute's value. But instead, you can use parameter ope=msk in order to apply a mask to the field's value.

Example:

<div class="old">[onshow.z;att=class;ope=msk:style*]
in this example, if we have $z='2' then we obtain <div class="style2">

Versioning: Parameter attadd is supported since TBS version 3.5.0

atttrue
or
atttrue=value

To be used with parameter att. Indicates that the attribute (indicated with parameter att) must be managed as a boolan XHTML/HTML attribute. I.e. it is either present in the tag with the format attribute="attribute" in order to mean TRUE, or ommited in the tag in order to mean FALSE.

If atttrue is set with a given value, then the boolean attribute will be TRUE (present) if the field is equal to this value, otherwise it will be FALSE (omitted).
If atttrue is set with no value, then the boolean attribute will be TRUE (present) if the field's value is non empty, and it will be FALSE (omitted) if the field's value is empty.

Examples:

<input type="checkbox">[onshow.accept;att=selected;atttrue=1]

Versioning: Parameter atttrue is supported since TBS version 3.6.0

magnet=tag
or
magnet=expr
or
magnet=#

Assign a magnet XML/HTML zone 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.

Parameter magnet supports the same syntax as parameter block, i.e. that expr must be an XML/HTML tag or a TBS extended block expression.
It also support the syntax magnet=# which means that the magnet zone is the HTML/HTML attribute wherein the TBS field is embedded.

Example:

(<a href="[onshow.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 XML/HTML zone should be delimited by 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.

Versioning:

  • Since TBS version 3.3.0, parameter ope has keywords (nif, minv, mok and mko) that improve parameter magnet.
  • The sytax magnet=# without parameter att is supported since TBS version 3.8.0.
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="[onshow.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="[onshow.link;magnet=img;mtype=m*]">
Example 2: <br> [onshow.address;magnet=br]
*m Delete the single tag that is after the field, and everything that is between the tag and the field.
Example: [onshow.address;magnet=br;mtype=*m]<br>
enlarge

Enlarge 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 XML/HTML tags.

Example:

xxx <!-- [myfield;enlarge] here some comments --> yyy

or

xxx <div> [myfield;enlarge=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:

  • Parameter enlarge is supported since TBS version 3.8.0. It is an alias of parameter comm which was misnamed and becomes deprecated.
  • Parameter comm is available for other XML/HTML tags since TBS 3.0.
noerr

Avoid some of the TBS Error messages for this TBS field. When such a message can be cancelled, it is mentioned in the message.

After the error is cancelled, the value of the field becomes an empty string ('').

See also the TBS option noerr which enables you to cancel any TBS error message.

Option noerr is a bit different from the field's parameter noerr. Option noerr applies for any TBS error and will avoid the merge of a block or a field which has an error. While parameter noerr ensures the merge.

file=filename

Replace the field with the contents of the file.

Filename can be a string or an expression.

Parameter file supports automatic embded fields [val] and [var].

If parameter script is used by omitting the filename value (example: [onshow.file;script;subtpl]), then the field's value is used for the file name.
If the file is not found, then it will be searched in the folder of the last loaded template (since TBS version 3.2.0).

Examples:

[onload;file=header.html]
[onload;file=[var.filename]]

If filename is an empty string, then no error message is displayed, it is like parameter file is ignored. This can be used to manage conditional insertion.

Example:

[onload;file=[var.insert;if [val]=1;then 'header.html';else '']]

You will found more details about this parameter in the chapter Subtemplates.

See also: getpart and script

getpart=taglist

To be used with parameter file or script.
Indicates that not all the file contents is loaded but only some XML/HTML parts of it defined with the tag list. The tags of the list must be separated with plus (+), and placed between parentheses if you want the tags themselves to be retrieved with their content. If the file has several XML/HTML part of a tag, all those parts will be automatically concatenated. If parameter getpart is used without value, then the <body> tag is taken by default.

Example:

[onload;file=header.htm;getpart=(script)+(style)+body]

Versioning:

  • Parameter getpart is supported since TBS version 3.8.0. It is an alias of parameter getbody which was misnamed and becomes deprecated.
  • Parameter getbody is supported since TBS version 3.0. In previous versions, it was automatically processed when using parameter file. Now it becomes explicit.
  • The tag list is supported since TBS version 3.5.0. Before this version, the value of getbody can be only one tag without parentheses.
store=taglist

To be used with parameter file or script.
It works like parameter getpart but the recovered part is buffered into a TBS store instead of being directly displayed. This enables you to store some parts of the sub-template and display them elsewhere in the main template.
A TBS store can be displayed using a special automatic field using the key store and the name of the store.
By default the name of a store is 'default', but it can be changed using parameter storename.

Parameter store is useful to use a sub-template as a component that will spread several contents in the main template.

Example:

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>The main template</title>
  [onshow.store.default]
</head>
<body>
  Here is a component :
  <div>
    [onload;file=component1.htm;getpart=body;store=(script)+(style)]
  </div>
</body>
</html>

Versioning: Parameter store is supported since TBS version 3.8.0.

storename=name To be used with parameter store. Parameter storename changes the name of the store. See parameter store.

Versioning: Parameter store is supported since TBS version 3.8.0.

rename old=new

To be used with parameter file or script. Renames TBS blocks and fields in the subtemplate before it is inserted. You can define several block to rename by separate them with coma. If a new name is an empty string then the old block is deleted by merging it with an empty array.

This parameter is useful when you want to use the same subtemplate several times in the main template.

Example:

Address 1: [onload;file=address.htm]
Address 2: [onload;file=address.htm;rename town1=town2,zip1=zip2,email=]

Versioning: parameter rename is supported since TBS version 3.5.1.

See chapter 'Subtemplates' for more details about subtemplates.
script=filename

Execute the Php script just before replacing the TBS field.

Filename can be a string or an expression.

Parameter script supports automatic embded fields [val] and [var].

If parameter script is used by omitting the filename value (example: [onshow.file;script;subtpl]), then the field's value is used for the file name.
If the file is not found, then it will be searched in the folder of the last loaded template (since TBS version 3.2.0).

* Take care that in your script variables will be obsiously local instead of global. 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)
* If the filename expression (or the value of the field) return an empty string (''), then parameter script is ignored and no error occurs. You can use this behavior in order to use a conditional insertion.

See chapter 'Subtemplates' for more details about how to use this parameter in subtemplate mode.

Versioning: Since TBS version 3.14.0 this feature is locked by default. You have to set the option scripts_allowed to true in order to unlock it.

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

Replace the current value with the value of parameter then or else, depending on whether the condition is verified or not. Both parameters then and else are optional. A missing then or else means no replacement for its corresponding case.

Supported operators are: (same as parameter when for blocks)

= 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.
Equal and not equal operators are always string comparisons and are case insensitive.
As with other parameters, string expressions can be delimited with single quotes ('), and literal single quotes in the string must be escaped using two adjacent single quotes ('').

Parameter if supports automatic embded fields [val] and [var].

Example:

[onshow.x;if [val]+-0;then 'OK';else 'FAIL']
The field will displayed OK only if « $x > 0 ».

If the emmebed fields may contains single quotes, you need to use delimitors and to escape strings in the field's value and both expressions:

[onshow.x;strconv=esc;if '[val]'='abc';then 'OK';else 'FAIL']
The field will displayed OK only if « $x == 'abc' ».

The expressions may contain [var] fields and other TBS fields, but you have to make sure that they are merged before the containing field is merged. Otherwise the condition will always be considered as false.

It is also possible to define several couples of if/then in the same field. Supported since TBS version 3.0
Example:

[onshow.x;if [val]=0;then 'ZERO';if [val]=10;then 'TEN';if [val]=20;then 'TWENTY';else [val]]

See parameters then and else for other examples.

then val1

If the parameter if is defined and its condition is verified, then the data item is replaced with val1.

Parameter then supports automatic embded fields [val] and [var].

Since TBS version 3.0, it is also possible to define several couples of if/then in the same field.

Examples:

[onshow.image;if [val]='';then 'image0.gif']
[onshow.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.

Parameter then supports automatic embded fields [val] and [var].

Example:

[onshow.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 just before the value is formated for the merge. This allows typically to modify the text to display. The onformat function does not replace the formating. String conversion or parameter frm are applied just after the onformat function.
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 The name of the current field (read only).
  $CurrVal The value of the current field. (Don't forget the & character in the statement).
The function is supposed to change this value in order to format it.
  $CurrPrm Optional. The PHP array containing the parameters for the current field (Don't forget the & character in the statement).
  $TBS Optional. Gives the current TBS instance. (Don't forget the & character in the statement).
Use this argument with lot of care. It is used sometimes for the subtemplate mode.

Example:

HTML: [onshow.x;onformat=f_to_utf8]
PHP:
function f_to_utf8($FieldName, &$CurrVal) {
  $CurrVal= utf8_encode($CurrVal);
}

See chapter 'Subtemplates' for more details about how to use this arguments in subtemplate mode.
Since TBS version 3.6.0, it's possible to limit the allowed PHP functions for parameter onformat. See create a new TBS object.

protect=val

Enables you to protect or unprotect the data item to be merged by replacing the characters '[' with their corresponding XML/HTML code '&#91;'. 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.

Nevertheless, it is possible to disable the protection by default if you set TBS option 'protect' to false.

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:

[onshow.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: [onshow.caption;ope=max:10]
  • Add parameter maxhtml to indicate that the value before merging can contain Html characters. Only characters starting with "&" end ending with ";" will be considered. HTML entities are not considered as HTML characters.
  • Add parameter maxutf8 to indicate that the value before merging can contain UTF8 characters. Versionning: maxutf8 is supported since TBS version 3.5.2.
  • Add parameter maxend to change the cutting symbol.
Example: [onshow.caption;ope=max:10;maxhtml;maxend='+']
mod:n Apply the modulo n to the value to merge. Example: [onshow.numlig;ope=mod:7]
add:n Add the numeric n to the value to merge. Example: [onshow.number;ope=add:-1]
mul:n Mutlyplies the value to merge by the numeric 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: [onshow.myarray;ope=list]
Add parameter valsep in order to change the item separator.
Example: [onshow.myarray;ope=list;valsep='+']
mok:x (means "magnet ok") To be used with parameter magnet. The TBS field is never displayed, but the magnet tag is kept when the value of the field is equal to 'x'. The magnet tag is deleted in other cases. You cannot use mok and mko in the same TBS field. You can define several values to keep the magnet tag by defining several mok. Example: [onshow.x;magnet=div;ope=mok:1,mok:2] (mok is supported since TBS version 3.5.2)
mko:x (means "magnet ko") To be used with parameter magnet. The TBS field is never displayed, but the magnet tag is deleted when the value of the field is equal to 'x'. The magnet tag is kept in other cases. You cannot use mok and mko in the same TBS field. You can define several values to delete the magnet tag by defining several mko. Example: [onshow.x;magnet=div;ope=mko:1,mko:2] (mko is supported since TBS version 3.5.2)
nif:x (means "null if") If the value is equal to 'x' then it is replaced with '' (empty string). This operation is designed to make parameter magnet to work with other values than ''. (supported since TBS version 3.3.0)
minv (means "magnet invisible") Replace the value with '' (empty string) but parameter magnet will consider the old value. This operation is designed to make totaly invisible a TBS field which do magnet stuffs. (supported since TBS version 3.3.0)
msk:x (means "mask") Apply a mask to the value. Characters '*' in the mask will be replaced by the original value. Example: [onshow.img_id;ope=msk:img_*.gif] (supported since TBS version 3.6.0)
lower Convert the value to lower case. (supported since TBS version 3.8.0)
upper Convert the value to upper case. (supported since TBS version 3.8.0)
upper1 Convert the value to upper case for the first character only. (supported since TBS version 3.8.0)
upperw Convert the value to upper case for the first character of each word. (supported since TBS version 3.8.0)
utf8 Can be used with max, upper, lower, upperw in order to indicate that the value is UTF8 encoded. upper1 is not supported in UTF8. (supported since TBS version 3.8.0)

Versioning:

  • Parameter ope is supported since TBS version 3.0. It replaces parameter max which doesn't exist since this version.
  • Multiple operations and 'mul" and "div" are supported since TBS version 3.2.0.
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. Add keyword (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. Add keyword (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
ampm, AMPM : "am" or "pm" signal , "AM" or "PM" signal.
(locale) Display locale day and month's names. The locale language can be set using the PHP function setlocale(). It works only if locale parameters have been set on the server. For PHP reasons, in locale mode xx does not work and d does like dd.

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

Interpretation of merged values:

  • If the PHP type of the data item is numerical, then it is considered as a Unix timestamp.
  • If the PHP type of the data item is string, then it is first considered as a formatted date-time and will be converted into timestamp using strtotime(). In case of failure, the original string value will be considered as a timestamp.
  • If the PHP type of the data item is object, then, then it will be converted into string.
  • Other PHP types will not be formatted and will be displayed converted into string.

It is recommended to use parameter frm with date-time value that use a non-ambiguous string representation, such as "yyyy-mm-dd hh:nn:ss". Most of PHP driver for Database System return date-time values and timestamp values is this format.

Versioning:

  • Keywords ampm and AMPM are supported since TBS version 3.0.
  • Keyword hm was supported since TBS 3.0 and is deprecated and replaced with keyword rr since TBS version 3.2.0.
  • Keywords rr, r, and h are supported since TBS version 3.2.0.
  • Keyword (locale) is supported since TBS version 3.4.0.
Numeric format:

To define the decimal part, use an expression like '0d0...' where 'd' 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 '0t000d...' where 't' is the thousand separator. If there is no decimal, use the format '0t000.' (with a dot).

In order to display leading zeros, use an expression like '0000d...' where '0000' represents the number of digits you want to have. If there is no decimal, use the format '0000.' (with a dot). Versioning: This feature is supported since TBS version 3.5.2.

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
  [fld;frm='000000.'] 002456
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)
combo=names

Apply combo's parameters. A combo is a set of parameters that have been previously defined at the PHP side using method SetOption('prm_combo').

Any other explicit parameters in the TBS field will override parameters coming from the combo.

You can apply several combo by separating names with coma (,).

Combo are useful to make reusable set of parameters, or to shorten a TBS tag when parameter are too long for the template. See also method ReplaceField() in order to shorten fields in the template.

Example:

PHP:
$TBS->SetOption('prm_combo', 'add_date', array('att'=>'div#data-date', 'frm'=>'yyyy-mm-dd', 'magnet'=>'div', 'enlarge'=>'span'));
HTML: [onshow.x;combo=add_date]

Versioning: parameter combo is supported since TBS version 3.11.0.

locale

Deprecated since TBS version 3.4.0, and may be badly supported.
Instead you should use parameter frm with the keyword (locale).

tplfrms

Enables you to define formats in the template that you can reuse for parameter frm. Works only with onload automatic fields.
It is the same feature as option tpl_frms, but option tpl_frms is defined in the PHP side, while parameter tplfrms is defined in the template side.

Example:

[onload;tplfrms;doll=$ 0,000.00;mydt=yyyy-mm-dd]
[onshow.amount;frm=doll] ... [onshow.date;frm=mydt]
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.

Order of processing parameters:

When you want to use several parameters in the same TBS field, then it can be interesting to understand in which order they are processed.
TBS changes the value to be merged, without changing the original value.

Order of processes:

  1. Retreive the value of the field to be merged.
  2. Change the value using parameters:
    1. onformat
    2. ope + plug-ins OnOperation
    3. frm or strconv or default char conversion
    4. if
    5. file
    6. script
    7. att
    8. ifempty or atttrue or magnet or attadd, those parameters cannot work together, the first used in this list is applied
  3. Insert the value in the template.

Automatic fields

Automatic fields enable you to automatically merge data when some events occur.

Automatic fields support subnames. They merges items stored in $TBS->VarRef. By default $TBS->VarRef is a reference on $GLOBAL. See property VarRef for more details.

Automatic fields can also merge TBS special information (see Special automatic fields), or data of the ObjectRef property (see Objet Oriented Programming).

An automatic field without subname will be merged with an empty string value ('').

There are three types of automatic fields:

  • [onload] fields, which are automatically merged when the LoadTemplate() method is called.
  • [onshow] fields, which are automatically merged when the Show() method is called.
  • [var] fields, which are automatically merged only if they are embedded into parameter file, script, if, then, else or when. Thus placed, they are merged when their parent are merged.

Of course automatic fields support all fields' parameters.

Examples :

[onload.x] Will be merged with the global variable $x when the LoadTemplate() method is called.
[onshow.x] Will be merged with the global variable $x when the Show() method is called.
[onload;file=header.html] Inserts a subtemplate when LoadTemplate() method is called.
[b1.col1;if [val]=[var.x];then 'good'; else 'bad'] The [var.x] field will be merged only when its parent [b1.col1] is merged.

Automatic fields cannot merge a variable which is local to a function. You can add your local variable to $TBS->VarRef, or you can merge it using MergeField().

Note: You can force the merge of automatic fields using MergeField().

Embedded automatic fields

Some parameters can manage embedded TBS fields. That is those embedded fields will be automatically merged at the time the parameter is evaluated.

Inside parameters file, script, if, then, else, embedded automatic fields are : [var] and [val].

Inside parameters when, embedded automatic fields are : [var] and the fields of the same block.

Note that the special fields [val] and [var] won't be merged when placed inside other parameters.

Note that other ordinary embedded fields won't be merged when placed inside any other parameters. You have to ensure that such fields are merged before, otherwise the merged result could be unexpected. Most of the time such embedded fields are simply not merged.

Bad templating examples:

[onload;if [onload.x]=1;then 'yes';else 'no']
This example will always display 'no', because the embedded field [onload.x] will never be merged (only [val] and [var] could be merged here).
Corrects expressions are :
  [onload;if [var.x]=1;then 'yes';else 'no']
  [onload.x;if [val]=1;then 'yes';else 'no']

[b1.nom;block=tr;headergrp=[var.x]]
In this example, [var.x] will not be merged yet when you call $TBS->MergeBlock('b1',...)
The header will then be defined badly.
It needs one of those:
- using an onload field: [b1.name;block=tr;headergrp=[onload.x]]
- calling $TBS->MergeField('var') avant $TBS->MergeBlock('b1',...)
- using a customized field name: [b1.name;block=tr;headergrp=[zzz]] manually merged with $TBS->MergeField('zzz',$x)

Security: how to limit automatic fields usage in templates?

You can limit the automatic fields usage by defining a prefix for allowed PHP variables. For details, see create a new TBS object.

Prevent from processing automatic fields [onload] and [onshow]

TBS options onload and onshow enable you to cancel the processing of [onload] and [onshow] fields. Those options accept only true of false values. This can be very useful especially, but not only, for some TBS plug-ins. Note that [var] fields are automatically processed even if onshow option is set to false. See method SetOptions() for more details about TBS options.

Versioning:

  • Automatic fields [onload] and [onshow] are supported since TBS version 3.2.0. For compatibility with versions prior to 3.2.0, remaining [var] fields are still merged as if there were [onshow] fields but is it recommended to use real [onshow] fields instead.
  • [var] are processed into parameter then and else since TBS version 2.02.
  • Options onload and onshow are supported since TBS version 3.8.0
  • Properties $TBS->OnLoad and $TBS->OnShow do act like the corresponding options but are deprectated. Those properties are supported since TBS version 3.6.0.

Special automatic fields:

A Special automatic field is a TBS automatic field which has a special name and can display special data provided by the template engine.
The special names can work only with automatic fields. That is [onload], [onshow] and [var].
The scpecial names always have a double dot before the key instead of one.

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

Available keys for special automatic fields:
Key Description Example
now Date and hour of the server. [onshow..now;frm='mm-dd-yyyy']
version The version of TinyButStrong. [onshow..version]
script_name The name of the PHP file currently executing. <form action="[onshow..script_name]">
template_name The name of the last loaded template file.
It is the name given to the LoadTemplate() method.
 
template_date The creation date of the last loaded template file.  
template_path The directory of the last loaded template file.
It is the directory given to the LoadTemplate() method.
 
tplvars.* The value of an item set in the TplVars property.
('*' must be the key of an existing item in the array)
[onshow..tplvars.title]
cst.* The value of a PHP constant.
(* must be the name of an existing constant)
[onshow..cst.PHP_VERSION]
tbs_info Information about TBS and installed plug-ins. [onshow..tbs_info]
error_msg Display errors that have been avoid during the time when TBS option noerr is set to true. [onshow..error_msg]
php_info Display the PhpInfo sight, the same as the PHP function phpinfo(). [onshow..php_info]
store.* Display the contents aggregated in a store. [onshow..store.default]

Versioning:

  • special var fields cst and tbs_info are supported since TBS version 3.2.0.
  • error_msg is supported since TBS version 3.5.0.
  • php_info and store are supported since TBS version 3.8.0.

TBS Blocks:

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 column to display and separated by a dot.

Examples:

- [Block1.ColumnA] This field will display the value of column ColumnA when block Block1 is merged.
- [Blokc1.ColumnB;frm='dd-mm-yyyy'] Another field but with a TBS parameter.

The dot (.) is a special character reserved for sub-names in TBS field. It cannot be used in a column's name.

The space character ( ) is supported in column names since TBS version 3.5.0.

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 during 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:
TEMPLATE...[BlockName;block=begin;params]...TEMPLATE...[BlockName;block=end]...TEMPLATE
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 XML/HTML tags which is given by a single TBS tag.
Example:
TEMPLATE...<tag_name...>...[BlockName;block=tag_name;params]...</tag_name...>...TEMPLATE
This TBS tag for the block definition must be placed between the pair of XML/HTML tags.
This TBS tag will be deleted during the merging.
Remark: You can aslo define a block's zone by a combination of XML/HTML tags. See parameter block for more details.
Simplified Syntax:
An associated TBS field is used to define the block in a relative way (see the relative syntax above).
Example:
TEMPLATE...<tag_name...>...[BlockName.ColumnName;block=tag_name;params]...</tag_name...>...TEMPLATE
The TBS tag for the block definition (i.e. the block=... parameter) must be placed between the pair of XML/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.
Remarks:
• 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.
• You can aslo define a block's zone by a combination of XML/HTML tags. See parameter block for more details.

Which syntax to use?

The 'absolute' syntax is rarely used with Visual Editors because TBS tags have often to be placed between two XML/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 XML/HTML standard.

Example:

<custom_tag>Hello [blk1.column1;block=custom_tag], how are you?</custom_tag>

Synopsis of a block 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 by the XML/HTML element, that is between the opening XML/HTML tag <tag...> and the closing XML/HTML tag </tag> which surround the TBS tag. The couple of indicated XML/HTML tags are integral part of the bloc. The TBS tag can also be placed inside the opening tag.

If the element is a single tag ending with "/" (such as <image href="img.gif" /> ) then the block is bounded by the single tag.

Examples:

<table id="tab1"> <tr><td>[b1.column1;block=tr]</td></tr></table>
The block is defined by the zone framed by pointillets.
<table id="tab1"> <tr id="row-[b1.column2;block=tr]"><td>[b1.column1]</td></tr></table>
The TBS tag can be placed inside the opening tag.
<div id="image-list"> <image href="img/[b1.column1;block=image]" alt="the picture" /> </div>
If the tag is a single tag ending with "/" then the block is bounded by the single tag.
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. Supported since TBS 3.1.0.
block=/ Define a block on the simple tag containg the TBS field. TBS assumes the tag is ending with "/", otherwise an error occurs. Supported since TBS 3.1.0.
block=. Define a block on the TBS field that contains this parameter. Supported since TBS 3.10.0.
block=tag/ Deprectated. By adding character "/" at the end of the tag's name, TBS assumes the tag is single. This syntax is ignored since TBS version 3.5.2 because TBS can recognize single tags by itself. Coding "block=image/" is the same as "block=image".
Extended blocks:

You can define the block's zone (or the section's zone) beyond the simple XML/HTML elements or special marks by using the following expressions. Note that Special Marks (see above) can be used for extended blocks.

To define the block's zone on several successive elements:

<ul>...</ul><div>[b1.field1;block=div+div+div+table]</div><div>...</div><div>...</div><table>...</table><p>...</p>

The same using multiplicated elements: (supported since TBS 3.10.0)

<ul>...</ul><div>[b1.field1;block=3*div+table]</div><div>...</div><div>...</div><table>...</table><p>...</p>

To define the block's zone on several successive elements placed before:

The element placed bewteen brackets means the one which contains the block's definition.

Exemple #1: ... <span>...</span><div>[b1.field1;block=p+(div)]</div> ...

Exemple #2: ...<span>...</span> <div>[b1.field1;block=p+(div)+table]</div> <table>...</table> ...

To define 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 the encapsulation level of the tags.

To define the block's but exclusing the limits, use the operator "!" on the limit elements: (supported since TBS 3.10.0)

Exemple #1: ...<div>...text here...[b1.field1;block=!div]...text there...</div>...

Exemple #2: ...<ul>...</ul><div>...text here...[b1.field1;block=div+!table]...text there...</div><ul>...</ul><table></table>...

Exemple #3: ...<p></p><ul>...</ul><div>...text here...[b1.field1;block=!p+(.)+!table]...text there...</div><ul>...</ul><table></table>...

Note that the operator "!" can be used only on the first and the last element of the block definition.

Versioning : The Extended 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=tag
or
bmagnet=expr
Indicates an XML/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). Parameter bmagnet supports the same syntax as parameter block, i.e. that expr must be an XML/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.

parallel=configuration_id

Merge a block with a parallel process for sub-blocks. This can typically merges a table block in columns.
By default, TinyButStrong supports the configuration id named "tbs:table" for merging HTML tables. But you can define your own configuration.
See Parallel merge for examples and how to add a custom configuration.

Versioning: parameter parallel is supported since TBS version 3.9.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.
Since TBS version 3.3.0, colname can also be a virtual column # or $, and it also support the subitems syntaxe of TBS fields.
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. The syntax is the same as headergrp.
splittergrp=colname Indicates a splitter section that is displayed each time the value of column colname changes. The syntax is the same as 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.
firstingrp=colname Indicates a section which replaces the normal section each time the value of column colname is the first in its group. That is when the value is different from the previous one.
You can define several firstingrp, lastingrp, singleingrp sections but only the first relevant one will be displayed for the same record if they are several relevant.
The syntax is the same as headergrp.
Parameter firstingrp is supported since TBS 3.12.
lastingrp=colname Indicates a section which replaces the normal section each time the value of column colname is the last in its group. That is when the value is different from the next one.
The syntax is the same as headergrp.
Parameter lastingrp is supported since TBS 3.12.
singleingrp=colname Indicates a section which replaces the normal section each time the value of column colname single in its group. That is when the value is different from the previous and the next one. This parameter is useful when you use both firstingrp and lastingrp and you also need to specify when happen when both cases are met.
The syntax is the same as headergrp.
Parameter singleingrp is supported since TBS 3.12.
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 Subblocks with dynamic queries.
If it used without any value, that enables you to merge several blocks of the same name. See "Merging several blocks with the same data" for more details.
sub1=column1 Define the column containing the data for an automatic subblock.
For more information, see the chapter Automatic subblocks.
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']);
}

Since TBS version 3.6.0, it's possible to limit the allowed PHP functions for parameter ondata. See create a new TBS object.
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: (same as parameter if/then/else for fieds)

= 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.
Equal and not equal operators are always string comparisons and are case insensitive.
As with other parameters, string expressions can be delimited with single quotes ('), and literal single quotes in the string must be escaped using two adjacent single quotes ('').

Parameter if supports automatic embded fields [var].

Example:

<div> ... [onload;block=div;when [var.x]+-0] ... </div>
The <div> block will be displayed only if « $x > 0 ».

If the emmebed fields may contains single quotes, you need to use delimitor and to escape strings in both expressions:

<div> ... [onload;block=div;when '[var.x;strconv=esc]'='abc'] ... </div>
The <div> block will be displayed only if « $x == 'abc' ».

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.

Sections of block:

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

Parallel merge (dynamic columns):

The parallel merge is supported since TBS version 3.9.0.

The parameter parallel enables you to merge a block with a parallel process for sub-blocks. This can typically merges a table block in columns.

How does it works ?

First of all you have to define a block over one or several closed cells in the same row of a table. It can be at any row of the table, it makes no difference. Then add parameter "parallel=tbs:table" to this block. Then TBS will merge the cells as expected for this row, but also for all the same columns of other rows in the table. The configuration "parallel=tbs:table" tells TBS how is structured the <table> element in HTML, and then it can found other cells of the same columns. TBS can even process spanned cells if it is consistent with the asked merge.

By default, TinyButStrong supports the configuration named "tbs:table" for merging HTML tables. But you can define your own configurations.

Example:

Template:

Category [b.date]
Thin [b.thin;block=td;parallel=tbs:table]
Heavy [b.heavy]
Total [b.total]

PHP:

$data = array(
 array('date' => '2013-10-13', 'thin' => 156, 'heavy' => 128, 'total' => 284),
 array('date' => '2013-10-14', 'thin' => 233, 'heavy' =>  25, 'total' => 284),
 array('date' => '2013-10-15', 'thin' => 110, 'heavy' => 412, 'total' => 130),
 array('date' => '2013-10-16', 'thin' => 258, 'heavy' => 522, 'total' => 258),
);
$TBS->MergeBlock('b', $data);

Result:

Category 2013-10-13 2013-10-14 2013-10-15 2013-10-16
Thin 156 233 110 128
Heavy 128 25 412 130
Total 284 258 522 258

Remark: The parallel merge doesn't work with headergrp and serial mode.

Define a new configuration:

$configuration = array(
 // Name of the parent entity. The process will be limited to this element and its childs.
 'parent' => 'table',
 // Names of tags that must be simply ignored. Such start and ending tags are ignored but childs are not ignored.
 // For elements that must be completely ignored including childs, you just have to not mentioned it in the configuration.
 'ignore' => array('!--', 'caption', 'thead', 'thbody', 'thfoot'),
 // Names of entities recognized as column's definitions, and their span attributes ('' for no span attribute).
 // Such entities must always be placed before the row entities.
 'cols'   => array(),
 // Names of entities recognized as rows.
 'rows'   => array('tr'),
 // Names of entities recognized as cells, and their span attibute ('' for no span attribute).
 'cells'  => array(
   'td' => 'colspan',
   'th' => 'colspan',
  ),
);
// Save the new configuratin with its ID.
$TBS->SetOption('parallel_conf', 'tbs:table',  $configuration);
    

Serial display (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]

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.
     

Remarks:

  • The serial display also works with sections of block, automatic subblocks and subblocks with dynamic queries.
  • For any usage, it must be considered that the main block (named bx in the example above) cannot merge data directly and is used only to defined the scope of secondary blocks. And in an other hand, each secondary block (named bx_1, bx_2, ... in the example) behaves like a normal block relatively to the data. Thus, as an example, in order to use serial display combined with automatic subblock, parameter sub1 must be define on each secondary blocks, and has no effects if defined on the main block.

Subblocks:

A subblock is a TBS block nested into another TBS block and that should be displayed as a separated block for each record of its parent block.

Example:

Parent block record #1
Subblock record #1.1
Subblock record #1.2
Parent block record #2
Subblock record #2.1
Subblock record #2.2
Subblock record #2.3
Parent block record #3
Subblock record #3.1

They are two different ways to perform subblocks with TBS:

  • Automatic subblock: (since TBS 3.5.0) it is when the data of the parent block has a column which contains the ready-to-merge data for the subblock. Automatic subblocks are activated using parameter sub1 in the parent block, and they are merged automatically during the merge of the parent block. No extra MergeBlock() are needed. See Automatic subblocks for more details.
  • Subblock with dynamic query: it is when the data of the subblocks are retrieved using a query which can change for each record of the parent block. Subblocks with dynamic queries need an extra MergeBlock() to perform the merging with their dynamic query. Parameter p1 is also needed in the subblock definition in order to set the values to inject in the dynamic query. See Subblocks with dynamic queries for more details.

Automatic subblocks:

Automatic subblock are supported since TBS version 3.5.0.

You can use automatic subblocks when the data of the parent block has a column which contains the ready-to-merge subdata for the subblock. Set parameter sub1=column in the parent block to define the column which contain the data for the subblock. If you have several subblocks to merge in the same parent block then use parameters sub2, sub3, ... The name of the subblock must be the same as the parent block followed by the suffix _sub1, (or _sub2, _sub3, ...).

The data of the parent block must have a column which contains the data of the subblock. Supported data types are:

  • a PHP array
  • an object supported by TBS (natively or with a plug-in)
  • a text string of values separated by comas (,).

Example:

Name: [body.name;block=tr;sub1=spokenlg]
[body_sub1.val;block=tr]

Corresponding PHP code:

$data = array(
  array('name'=>'Peter', 'spokenlg'=>array( 'US', 'FR' ) ),
  array('name'=>'Paul',  'spokenlg'=>array( 'US' ) ),
  array('name'=>'Jack',  'spokenlg'=>array( 'FR', 'ES', 'IT') ),
);
$TBS->MergeBlock('body', $data);

Result of the merge:

Name: Peter
US
FR
Name: Paul
US
Name: Jack
FR
ES
IT

Have the column optional:

If you want no error message when the column is omitted in the parent data, then you can set it optional by using parenthesis. This is working only if the parent data is a PHP array. Optional column is supported since TBS version 3.6.0.

Example:

Name: [body.name;block=tr;sub1=(spokenlg)]
[body_sub1.val;block=tr]

Direct subblocks (which are not saved under a column):

If you use parameter sub1 by omitting the column name, then TBS will assume that the data for the subblock are available directly on the current record instead of under a column of this record. Direct subblocks are supported since TBS version 3.6.1.

Example of data that can be merged with a direct subblock:

$data = array();
$data['group1'] = array();
$data['group1'][] = array('id'=>1, 'name'=>'peter');
$data['group1'][] = array('id'=>2, 'name'=>'paul');
$data['group2'] = array();
$data['group2'][] = array('id'=>3, 'name'=>'jules');
$data['group2'][] = array('id'=>4, 'name'=>'jim');

Example of direct subblock that can be merged with those data:

Group : [body.$;block=tr;sub1]
[body_sub1.name;block=tr]

Several levels of automatic subblocks:

TBS supports several levels of automatic subblock. For example you can have blocks "b", 'b_sub1", 'b_sub1_sub1", 'b_sub1_sub1_sub1" and so on.

Subblocks with 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 parameter $query given to the MergeBlock() method must be a string and has to contain marks such as %p1%, %p2%, %p3%, ... in order to welcome the values of the parameters p1, p2, p3,...

Note that you can also use a dynamic query with a PHP Array using a string that refers to a PHP Array stored in a global variable. See Php data sources.

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%')");

Or using an Array:

global $data_town; // the coutry code is the main key of the array
$TBS->MergeBlock('blk', 'array', 'data_town[%p1%]');

Result of the merge:

Country: France

Paris france
Toulouse france

Country: USA

Washington us
Boston us

Use with subblocks:

Dynamic queries enable you to easily build a system of a main-block with subblocks. Here is how you can do it:

  1. Create a main block, and then a subblock inside the main block.
  2. Link them by adding to the subblock a parameter p1 whose value is a field from the main block.
  3. At the PHP side, merge the main block first, and then the subblock.

Example:

Country: [main.country;block=tr]
[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%)';

Or using an Array:

$TBS->MergeBlock('main', $data_county);
global $data_town; // the coutry code is the main key of the array
$TBS->MergeBlock('blk', 'array', 'data_town[%p1%]');

Result of the merge:

Country: France
Paris
Toulouse
Country: Germany
Berlin
Munich
Country: Spain
Madrid
Barcelona

Remarks:

  • The parameter strconv=esc enables you to pass protected string values to the query.
  • The dynamic queries also work with sections of block and serial display.

Automatic blocks:

Automatic blocks enable you to automatically merge conditional blocks when some events occur.

There are two types of automatic blocks:

  • [onload] blocks which are merged automatically when the LoadTemplate() method is called.
  • [onshow] blocks which are merged automatically when the Show() method is called.

Automatic blocks are not merged with data ; that's why they cannot have normal sections (non conditional sections) and linked fields. Automatic blocks can have only conditional sections. Conditions are evaluated only once, and they can be expressions containing [var] fields.

Example:

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

[onshow;block=tr;when [var.user]=1] User : [onshow.username]

If you need to have a group of exclusive sections, with or without a default section, you can suffix the [onload] and [onshow] bloc's names with "_" followed by a subname.

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 ?

See Conditional sections for more details.

Subtemplates:

There are two ways to insert 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. If the value is an empty string, then no error message is displayed, it is like parameter file is ignored. This can be used to manage conditional insertion.

Examples:

[onload;file=header.htm]
[onload;file=[var.file_header]]
[onload.sub1;file=[val]]
[onload;file=[var.insert;if [val]=1;then 'header.html';else '']]

Contents of the file is inserted at the place of the field, without no char conversion and no TBS protection.
[onload] tags contained in the file are processed at the insertion. [onshow] tags 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().

You can create a subtemplate in an independent XML/HTML/Text file, and ask TBS to include in the main template only the <body> part (or another part). This can be done by adding parameter getpart to parameter file in the TBS field of the main template. This technique enables you to work WYSIWYG with your subtemplates.

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.

In the Subtemplate mode, 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.

Versioning: since TBS version 3.8.3, the PHP direct outputs (such as those done with the command echo) are no longer diverted from the subtemplate to the main template.

Example with parameter script:

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

PHP script:

<?php

// script specialbox.php

$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:
[onload.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.

Conditional display overview:

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:
[onshow.error_id;if [val]=0;then 'no error';else 'error found']

Conditional sections

You can use conditional sections any TBS block (data block or automatic block). A conditional section is a 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.

• The case of data blocks:

If it is a data block, it means a block merged with MergeBlock(), then the conditional sections are reassessed for each record. It is even possible to define a data block with only conditional sections, with no standard section.

• Defining the conditions:

The conditions defined into parameters when can be expressions that contain [var] fields et and linked fields (if it is a data block). See parameter when for more details about operators supported by TBS.

• Section exclusivity:

By default conditional sections are exclusive inside a block. It means only one conditional section of a block can be displayed. But 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 with a data block:

Name: [b1.Name;block=tr] standard 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] default conditional section (optional)

Example with an automatic block:

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

Improve TBS by coding:

You can add features to TinyButStrong using plug-ins. The database plug-ins simply enable the method MergeBlock() to recognize new types of database. The other plug-ins enable you to add features to TBS or to modify its main methods in order to make it more specialized.

In both cases, a plug-in is made of a set of PHP functions or one PHP class which have to fit with a special syntax expected by TBS. Some plug-ins are proposed for download at the TinyButStrong web site.

Extended methods:

Extended methods are custom methods that you can add to a TinyButStrong instance. This can be usefull for a plug-in for example.

Versioning: Extended methods are supported since TBS version 3.8. The feature needs PHP 5.0 or higher.

Examples:

If you define:
$TBS->ExtendedMethods['newMethod1'] = array(&$myObject, 'myMethod');
then if you call:
$TBS->newMethod1($x);
it whill run :
$myObject->myMethod($x);

If you define:
$TBS->ExtendedMethods['newMethod2'] = 'myFunction';
then if you call:
$TBS->newMethod($x);
it whill run :
myFunction($x);

Block alias:

A block alias is a special name for a block definition, which will be replaced with another list of tags or which will call a custom function to find the block bounds.
Block alias really empower the way of defining blocks. It is useful for plug-ins or when you want to simplify the understanding of the template coder.

Versioning: Block alias are supported since TBS version 3.8.

Examples:

$TBS->SetOption('block_alias', 'row', 'tr'); // the alias replace one tag
$TBS->SetOption('block_alias', 'dblrow', 'tr+tr'); // the alias replace several tags
$TBS->SetOption('block_alias', 'my_alias', array($myObj, 'findBounds') ); // the alias call a custom function to find the bounds

Use in the template :

[blk1;block=row] or [blk1;block=row+row] or even [blk1;block=th+row]
[blk2;block=dblrow]
[blk3;block=my_alias]
  

Defining a block alias with a function:

Example :

class clsTest {
 /** 
  * Function findBound() will be call two times for finding the bounds of the block. Once with $Forward=true, and once with $Forward=false.
  * It is supposed to return the position of the inner bounds of the block. 
  * It can return false if an error occurs of if the template source is inconsistent for finding the block at the given position.
  *
  * @param string  $Tag The name of the block alias
  * @param string  $Txt The source of the template
  * @param integer $Pos The position of the TBS field in $Txt
  * @param boolean $Forward The direction of the search
  * @param mixed   $LevelStop Encapsulation level in a block of the same type. Ignore this in your code if your block type does not support self-encapsulation. 
  * @return integer
  */
	function findBound($Tag, $Txt, $Pos, $Forward, $LevelStop) {
		if ($Forward) {
			return strpos($Txt, '}', $Pos);
		} else {
			return strrpos(substr($Txt, 0, $Pos+1), '{');
		}
	}
}

 

Data Reader Plug-ins:

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

When you use $TBS->MergeBlock($BlockName, $Source, $Query), TBS is first examining $Source to see if it supported as a data source.

A Data Reader plug-in enables TBS to to recognize new data sources.

You can found several examples of Data Reader plug-in at the TinyButStrong web site.

Data Reader plug-in made with 3 PHP functions

Synopsis:

function tbsdb_XXX_open(&$Source, &$Query) 
This function is called one time by the MergeBlock process, before the other user functions.
It is supposed to use $Source and $Query to open a recordset, and return a reference of that recordset.
function tbsdb_XXX_fetch(&$Rs [,$RecNum]) 
This function is called several times by the MergeBlock process, as many times as there are data to fetch from the query.
This function should return the next record as an associative array (column name=> value), or return false if there is no record left.
$Rs is the value provided by tbsdb_XXX_open(). It is commonly a recordset's reference.
$RecNum can be useful for some database type such as Oracle, for which the number of the record is needed to retrieve it.
function tbsdb_XXX_close(&$Rs) 
This function is called on time by the MergeBlock process, after the other user functions.
This function should close the recordset properly.
$Rs is the value provided by tbsdb_XXX_open(). It is commonly a recordset's reference.

TBS will automatically use this Data Reader plug-in for $TBS->MergeBlock($BlockName, $Source, $Query) when:

  • $Source is equal the string 'XXX'.
  • or
  • $Source is a PHP ressource which type is named 'XXX'. Spaces are deleted and '-' are replaces with '_'.
  • or
  • $Source is a PHP object which class is named 'XXX'.

Data Reader plug-in made with a class

Example with a direct object:

class MyCustomClass {
  function tbsdb_open(&$Source, &$Query) {...}
  function tbsdb_fetch(&$Rs ,$RecNum) {...}
  function tbsdb_close(&$Rs) {...}
}
$Source = new MyCustomClass();
$TBS->MergeBlock($BlockName, $Source, $Query);    

When the MergeBlock process meet of value for $Source which is an object, and have at least 3 methods namedtbsdb_open(), tbsdb_fetch() and tbsdb_close(), then it assumes that the object is a Data Reader plug-in. There can be other methods and properties, but those 3 methods must have the same syntax and the same feature as the user functions described above.

Database plug-in based on property ObjectRef:

Example with an objet saved in ObjectRef:

class MyCustomClass {

  function XXX_open(&$Source, &$Query) {...}
  function XXX_fetch(&$Rs ,$RecNum) {...}
  function XXX_close(&$Rs) {...}

  function YYY_open(&$Source, &$Query) {...}
  function YYY_fetch(&$Rs ,$RecNum) {...}
  function YYY_close(&$Rs) {...}

}
$TBS->ObjectRef = new MyCustomClass();
...
$TBS->MergeBlock($BlockName, '~XXX', $Query);
When the MergeBlock process meet a value for $Source which is a string beginning with '~' then it assumes that property $TBS->ObjectRef is a Data Reader plug-in based on an object (see OOP). The object must have the same requirements as a Data Reader plug-in based on objet described above, but the names of the methods can be different.

Other plug-ins:

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.
OnCacheField Executed each time a field is put in the cache of a Block definition. (supported since TBS 3.6.0)
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.
OnMergeGroup Executed before a header, a footer or a splitter section is merged. (supported since TBS 3.3.0)
AfterMergeBlock Executed just before a merged block is inserted into the template.
OnSpecialVar Executed when a non native Special Var Field (like [onshow..now]) is met.
OnMergeField Executed on each field met when using the MergeField() method.

Summary:

TBS Field's parameters:

Parameter Summary
strconv

Char conversion Mode for the field's value.

htmlconv Deprecated, alias of strconv.
. (dot) If the value is empty, then display an unbreakable space.
ifempty If the value is empty, then display another value.
att Move the field into the attribute of an XML/HTML tag.
   attadd Use with att. Indicate that the merged value must be added instead of be replacing the attribute's value.
   atttrue Use with att. Indicate that the target attribute must be managed as a boolean attribute.
magnet If the value is empty, then delete surrounding element.
   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.
combo Apply a set of predefined parameters.
tplfrms Use with onload fields only. Define template formats.
tplvars Use with onload fields only. Define template variables.
protect Protection mode for characters '['.
enlarge Enlarges the field's bounds up to the Commentary tag that surround it.
comm Deprecated, alias of enlarge.
noerr Avoid some TBS error messages.
file Includes the contents of the file.
script Executes the Php script.
   getpart Use with file or script. Insert only a part of the subtemplate.
   getbody Deprecated, alias of getpart.
   store Use with file or script. Store a part of the subtemplate in order to display it elsewhere.
   storename Use with store. Change the name of the store.
   rename Use with file or script. Rename TBS block and fields in a subtemplate.
   subtpl Use with script or onformat. Turns the TBS instance into subtemplate mode.

TBS Block's parameters:

Parameter Summary
block Defines the block's bounds.
nodata Indicates the section that is displayed when there is no data in the data source.
bmagnet If there is no data, then delete the surrounding element.
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.
firstingrp Indicates a section that replaces the normal section when the value of a column changes.
lastingrp Indicates a section that replaces the normal section when the value of a column changes.
singleingrp Indicates a section that replaces the normal section when the value of a column changes.
parallel Indicates a configuration for merging data in columns or with any custom parallel method.
serial Indicates a section that contains a series of several records.
p1 Sends a parameter to the dynamic query for the data source.
sub1 Define the column containing the data for an automatic subblock.
ondata Executes a Php user function to modify the record when it has just been taken from the data source.
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.

Names of Special Fields and Blocks:

Name Summary
val The keyword [val] can be used in field's parameters to represent the field's value.
# 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.
var Embedded automatic field.