TBS 3.0 what's new

What's new with TinyButStrong version 3.0
2006-04-02 - Skrol29

This document explains the differences between TBS version 2.x and TBS version 3.0.

Presentation:

The major change in TBS version 3.0 is the Plug-ins feature. Plug-ins enable you to customize some TBS processes such as LoadTemplate(), Show(), MergeBlock(), Special Var fields and string conversion. You can also add you own command to a plug-in. This is also the occasion for TBS to leave some deprecated features and to rearrange incoherent way of work. Thus, some old features will be converted into TBS plug-ins.

Plan of this document:

§ New features and enhancements
§ Changes of behaviour and syntax
§ No more supported
§ Plug-ins in details

New features and enhancements

•

New method PlugIn().

See chapter below.

•

New parameter 'bmagnet' :

This is a parameter for blocks. It defines a surrounding block to delete when there is no data to merge.
Example: [b1;block=tr;bmagnet=table]
In this example, the entire Html table will be deleted if the merged query has no data.

•

New parameter 'getbody' :

This parameter works with both parameters 'file' and 'script'. It indicates to search and keep the body part of the inserted file. By default, it searches for the couple of tags <body> and </body> but you can precise other tags.

Examples:

[onload;file=header.html;getbody]
In this example, only the contents between tags <body> and </body> of the file 'header.html' will be inserted.

[onload;file=header.html;getbody=table]
In this example, only the contents between tags <table> and </table> of the file 'header.html' will be inserted.

•

New parameter 'ope' :

This parameter enables you to make some basic operations on the value before the field is merged.

Examples:

[var.x;ope=list]		Explode the value if is an array.
[var.x;ope=mod:12]		Make (value modulo 12)
[var.x;ope=add:-1]		Make (value -1)
[var.x;ope=max:10]		Limit the value to 10 characters (replace parameter 'max') You can use parameter 'maxend' to define a different end when a value is cut. You can use parameter 'maxhtml' to specify that the string to cut maybe HTML contents.

You can also define your own 'ope' features using the OnOperation plug-in event.

•

New property NoErr :

It enables you to avoid all TBS error messages.
Example : $TBS->NoErr = true;

•

Parameter 'comm' enhancement :

Parameter 'comm' without any value still extends the bounds of a TBS fields up to the surrounding Html Comment tag. But you can now precise a couple of tags instead.
Example : <span>[var.x;comm=span]</span>

•

Parameter 'frm' enhancement :

Parameter 'frm' allow keywords ampm, AMPM and hm to display an hour with the AM/PM format.
Example : <span>[var.datex;frm='hm:mm:ss ampm']

•

Method GetBlockSource() enhancement :

By default, this method returns the source of a block in the current template, including the definition tags. This could be a problem when the block is defined with an explicit syntax (block=begin/block=end). A new extra argument enables you to precise if you want to delete definition tags from the returned block's source.

Example :
$def_tags = false;
$x = $TBS->GetBlockSource('b1',false,$def_tags);

•

Method MergeBlock() enhancement :

°	Arguments for ByPage Mode are deleted (see below). Now you can makes the method to return the full merged data by adding '' as a block name to merge. Example : $data = $TBS->MergeBlock('blk,','SELECT id FROM table_a');
°	It is also possible to call MergeBlock() with an empty string instead of a block's name.
°	The method can now merge fields outside the block bounds for sub-blocks too. (like [blk.#] for example).

•

Method MergeField() enhancement :

°	This method now accepts several field's names for argument. Example : $TBS->MergeField('b1,b2,b3',$value);
°	Can also be used to merges special fields [var], [onshow] and [onload]. In those cases, the argument value is ignored. This can be done with prvious TBS version using the MergeSpecial() method but is no longer supported. Example : $TBS->MergeField('var');

•

OOP enhancement (Oriented Object Programming) :

The syntax to refers to an object under property ->RefObject allow now to have a path like for Var Fields.
Example :
[var.x;onformat=~item1.item2.my_method]
In the example above, onformat function refers to
$TBS->ObjectRef['item1']['item2']->my_method();

•

Sub item syntax enhancement :

The syntax to refers to a sub item for fields can now have a reference to a method with arguments.
Examples :
[var.obj1.my_method(144,aaa)]
[var.obj1.my_method(222,bbb).item4]
Note : this syntax does not allow string delimitors.

Changes of behaviour and syntax

•

New syntax to define a block relatively ot Html tags.

This new syntax is compatible with the old syntax.
This syntax applies for paramaters 'block', 'magnet', 'selbounds', 'comm', and new parameter 'bmagnet'. It also makes parameters 'extend' and 'encaps' deprecated.

Old syntax	New syntax
block=div	block=div
block=div;extend=2	block=div+div+div or block=(div)+div+div
block=div;extend=-2	block=div+div+(div)
block=div;encaps=3	block=(((div)))
block=div;encaps=3;extend=2	block=(((div)))+div+div

The interest of this new syntax is double : you can extend the block's bounds over different tags which follow each other (example : block=div+span+table). And you can extend bounds not only for parameter block, but also other parameters magnet, bmagnet, selbounds and comm.
Please note that parameters 'extend' and 'encaps' are no more supported.

•

Parameter 'if' :

°	It is now processed before parameter 'file'.
°	When 'if' condition is false and parameter 'else' is omitted, then the value is not changed. In TBS 2.x the value was set to empty string ('') in this case.
°	You can now define several 'if'/'then' parameters in the same TBS field. Extra parameter 'if' will be used like a PHP elseif. In any case, only one final parameter 'esle' is allowed. Example : [var.x;if [val]=1;then 'one';if [val]=2;then 'two';else 'more']
°	You can now define regular expression for the if condition. Example : [var.x;if [val]~='to';then 'A';else 'B']

•

Parameters 'file' :

By default the file is inserted as is. TBS does not search and keep the body part of the inserted contents automatically anymore. You have to use the new parameter 'getbody' to get this feature.

•

Parameters 'script' :

°	If the script name is an empty string, then the parameter is simply ignored and no error message is displayed.
°	Parameters 'getob' and 'once' which could complete parameter 'script' are no more supported anymore. Only 'subtpl' stayes available and does makes the 'getob' feature.

•

Parameter 'frm' :

When a multiformat is defined, then an empty format will display an empty string. It used to be different: in TBS version 2.x, empty format was taken as equal to the previously defined format.

No more supported

	•	Parameter 'htmlconv=look'. Was used to check the contents to decide if it is Html yet, or to be converted to Html. No more supported.
	•	Parameter 'block=row'. This was a deprecated alias. Now you have to use 'block=tr' instead.
	•	Paremeter 'block=opt'. This was a deprecated alias. Now you have to use 'block=option' instead.
	•	Parameter 'max'. No more supported, you have to use new parameter 'ope' instead. Example : [var.x;ope=max:10]
	•	Parameter 'getob'. Fully supported by parameter 'subtpl'.
	•	Parameter 'once'. Was used with parameter 'script' to run the script only once. No more supported.
	•	Parameter 'extend'. No more supported. Now you have to use the new syntax for parameter 'block' instead.
	•	Parameter 'encaps'. No more supported. Now you have to use the new syntax for parameter 'block' instead
	•	Parameter 'onsection'. Deprecated, no more supported. Use parameter 'ondata' instead.
	•	Parameter 'selected'. No more supported. It is replaced by a plug-in which has a syntax closed to the old one. (see demo examples) Example : [var.x;ope=html;select=tagname]
	•	Method MergeNavigationBar() is no more supported. It is replaced by a plug-in which has quite the same syntax. Parameter 'navdel' for navigation bars has to be replaced by new parameter 'bmagnet' for blocks. Replace : TBS->MergeNavigationBar('nav1',,$page,$rec_nbr,$page_size); With : include_once('tbs_plugin_navbar.php'); ... TBS->PlugIn(TBS_NAVBAR,'nav1',,$page,$rec_nbr,$page_size);
	•	Method CacheAction() is no more supported. It is replaced by a plug-in which has quite the same syntax. (plug-in not yet available)
	•	Method MergeSpecial() is no more supported. It is replaced by a MergeField() enhancement. Replace : $TBS->MergeSpecial('var'); With : $TBS->MergeField('var');
	•	Method MergeBlock() extra arguments for ByPage Mode are no more suported. ByPage Mode is replaced by a plug-in. Replace : $TBS->MergeBlock('b1',$id,$Sql,$PageSize,$PageNum,$RecCnt) With : include_once('tbs_plugin_bypage.php'); ... $TBS->PlugIn(TBS_BYPAGE,$PageSize,$PageNum,$RecCnt); $TBS->MergeBlock('b1',$id,$Sql);

Plug-ins in details

A plug-in for TinyButStrong is a module that will enhance the Template Engine by adding extra features to basic TBS methods (like LoadTemplate, MergeBlock, Show) or by giving new commands to users (Php programers).

How to create a new TBS plug-in ?

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 automaticlally by TBS when the corresponding event occurs. A TBS plug-in can have other methods and properties for internal purpose. A TBS plug-in must have at least the OnInstall event.

You can use the PHP file 'tbs_plugin_syntaxes' to have all plug-in events, their usage and expected t arguments.

List of plug-in events:

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

How to install and use a TBS plug-in ?

Each plug-in has a plug-in Id which must the name of its Php class. This Id must be given to the method PlugIn() when you use it. Thus, you can define a PHP constant to call the plug-in.

For example :
define('TBS_TRY','clsTbsPlugIng_Try');
class clsTbsPlugIng_Try() {
  ...
}

You can install the plug-in manually using the command :
$TBS->PlugIn(TBS_INSTALL,TBS_TRY).
  -> This will execute the OnInstall() method of the TBS_TRY plug-in.

Or it will be installed automatically when you call it for the first time :
$TBS->PlugIn(TBS_TRY,'my first command');
  -> This will execute the OnCommandl() method of the TBS_TRY plug-in.
  -> If it is called for the first time, then the OnInstall() method is execute before.

• A plug-in is installed for a TBS instance only. If you have several TBS instances, you have to install the plug-in on each of TBS instances you need. As soon as a plug-in is installed; an instance of the plug-in class is created and a new property called ->TBS is added to it. Property ->TBS is a reference on the TBS instance on which it is installed. The class can use it for its internal purpose and it is available yet when OnInstall() method is called.

• You can also define a plug-in to be installed automatically to each new TBS instance. The the file tbs_plugin_syntaxes.php to know more.

• TinyButStrong is provided with several ready to use plug-ins, like NavigationBar, ByPageMode and CacheSystem.
There is also a plug-in template (tbs_plugin_syntaxes.php), it does nothing particular but it contains all expected syntaxes and other information for all plug-in events.