TinyButStrong Documentation

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 = ''])

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

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:

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

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

Link between the block and the records:

Merging subnames

Merging several blocks with the same data:

Returning the full merged record set:

Counting the records:

Resource and Request arguments according to the data source type:

Php data sources:

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

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

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

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

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

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.

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

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

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

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

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.

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

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

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

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.

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.

Reset the VarRef property.

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

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

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.

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.

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

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.

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

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

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.

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

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

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

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

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:

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.

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;

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.

Remarks:

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

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

Calling methods of a class without created object:

Calling created objects:

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

Field's parameters:

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

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

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

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.

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:

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:

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:

Relative Syntax:

Simplified Syntax:

Which syntax to use?

Synopsis of a block tag:

Block's parameters:

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.

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:

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:

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:

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.

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

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

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

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.

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.

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.

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.

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

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

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.

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:

Several levels of automatic subblocks:

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.

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

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

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.

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

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

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

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.

See Conditional sections for more details.

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:

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

<?php

// script specialbox.php

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

Example with parameter onformat:

[onload.user_mode;onformat=f_user_info;subtpl]

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

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.

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:

Example with an automatic block:

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

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), '{');
		}
	}
}

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) 

function tbsdb_XXX_fetch(&$Rs [,$RecNum]) 

function tbsdb_XXX_close(&$Rs) 

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

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: