Help for TBS plug-ins of the standard distribution
by Skrol29, 2012-08-15

| Important note: When you use plug-ins with PHP 4 you should code: TBS =& new clsTinyButStrong; instead of: TBS = new clsTinyButStrong; otherwise some plug-in may not run correctly. This problem does not happens with PHP 5. |

• | ByPage | Enables the MergeBlock() method to display only a part of the records, instead of all records.
• | Cache System | Provides several actions for a small Cache System.
• | NavBar | Displays a navigation bar.
• | Html | Selecting HTML items and checking HTML contents.
• | MergeOnFly | Enables the MergeBlock() method to display data on fly.

Plug-in ByPage version 1.0.5

Compatibility: | Plug-in ByPage 1.0.0 run with TBS from 3.0.0 to 3.0.6
| Plug-in ByPage 1.0.2 or higher run with TBS 3.1.0 or higher

This plug-in enables the MergeBlock() method to display only a part of the records, instead of all records. Displayed records are those corresponding to a page number, like if the record set was split by pages having the same size.
Note: when you call the plug-in command, it activates the ByPage mode only for one MergeBlock() call. Other MergBlock() calls won't have the ByPage mode until you call the plug-in just before them.
Important remark: In most of cases, the ByPage mode costs as much process time as for the normal mode with the same query. This is explained in the chapter "how the ByPage plug-in works?" above.
Requirement: include the file 'tbs_plugin_bypage.php'. This can be after the TBS object variable is created.
Installation mode: automatic when the plug-in command is called for the first time.
Command syntax: $TBS->PlugIn(TBS_BYPAGE, int PageSize, int PageNum {, int RecCount})

Argument | Description
TBS_BYPAGE | This constant is the plug-in's key.
PageSize | Indicates the number of records per page.
PageNum | Indicates the number of the page to display. The first page is number 1. The special value -1 will display the last page of the record set.
RecCount | Optional, default value is 0. Use this argument if you need the MergeBlock() method to return the real total number of records. See more detail below.

Example :
include_once('tbs_plugin_bypage.php');
$TBS->PlugIn(TBS_BYPAGE, 20, 3);
$TBS->MergeBlock('b1','mysql','SELECT * FROM t_mytable ORDER BY id');
How the ByPage plug-in works ?
It's important to notice that this plug-in won't makes the query to run faster. Because all database systems don't have a LIMIT clause for SELECT queries, and because all queries are not SELECT queries then the plug-in must let the query as is without inserting any LIMIT clause by itself. Thus, the ByPage plug-in just sends the query, reads all records in order, starts to display records when the beginning of the page is reached, and stops to read and display when the end of the page is reached.
That's why the ByPage plug-in is not convenient to display a page among a large number of records. It's better to use the LIMIT clause of your database system instead (or other native clause for limiting data).
How to use argument RecCount ?
You should use RecCount if you need the MergeBlock() method to return the real total number of record (this can be useful when you need to display the page of data noticing the total number of records). In the normal mode, the MergeBlock() method return the total number of records, but in the ByPage mode, it return the number of the last read record, this can be different. But RecCount enables MergBlock() to whether makes a real count or to trust your value.
Value of argument RecCount:

RecCount = -1 | MergBlock() counts the real total number of record, and return this value. This need to read all data up to the bottom.
RecCount > 0 | MergeBlock() return RecCount.
RecCount = 0 (default value) | MergeBlock() return the number of the last record read, which can be different of the total number of record.

Example :
if (isset($_GET['nbrtot']) {
$RecCount = $_GET['nbrtot']; // MergeBlock() will trus this value.
} else {
$RecCount = -1; // Will Force MergeBlock() to count all records.
}
include_once('tbs_plugin_bypage.php');
$TBS->PlugIn(TBS_BYPAGE, 20, 3, $RecCount);
$nbrtot = $TBS->MergeBlock('b1', 'mysql', 'SELECT * FROM t_mytable ORDER BY id');
Plug-in Cache System version 1.0.6

Compatibility: | Plug-in CacheSystem 1.0.3 to 1.05 run with TBS from 3.0.3 to 3.2.0
| Plug-in CacheSystem 1.0.6 or higher run with TBS 3.3.0 or higher

This plug-in provides several actions for a Cache System. The Cache System enables you to manage manually or automatically the backup of the merge result into a temporary file called "cache" file.
Requirement: include the file 'tbs_plugin_cache.php'. This can be after the TBS object variable is created.
Installation mode: automatic when the plug-in command is called for the first time.
You can aslo install the plug-in manually in order to specify the default directory and the cache mask. See Setting Cache System parameters for more details.
Command syntax: bool $TBS->PlugIn(TBS_CACHE, string CacheId {, int Action/MaxAge}{, string Dir})
The function returns true or false depending to the success or failure of the action.

Argument | Description
CacheId | Unic id of the cache file. This must be a string, and it will be used in the name of the file.
Action/MaxAge | Determine the action to do. It must a be a constant of the Cache Sytem plug-in or a positive value. See table below for more details on available actions. The default value is 3600 wich correspond to an automatic backup with a max age of 1 hour.
Dir | Optional. The path of the directory where the cache file is saved. By default, it is the same directory as the script.

Example :
include_once('tbs_plugin_cache.php');
$TBS->PlugIn(TBS_CACHE, 'mainpage', 3600);
Manage a cache file:
The Cache System enables you to create, load, update or delete a cache file identified by CacheId. There is also an Automatic Mode that let the System manage those actions depending to a max-age of the cache file.
Cache on Show:
If you start the "Cache on Show", then the result of the merge will be automatically saved in the cache file at the first use of the TBS Show() method. The recording takes place after the display of the result.
Please note that by default the Show() method causes the end of the script. If you want to continue some treatments after the "Cache on Show", then you have to set the TBS Render property in order to avoid the end of the script.
Here is the list of possible actions for the Action/MaxAge argument, it can be a constant of the plug-in or a positive numerical value.

Action | Description
x >=0 (positive number) | Automatic Mode with max-age:
- | If the cache file exists and has been created less that x seconds ago, then the file is loaded and the TBS Show() method is executed. If you haven't set the TBS Render property then the script ends after displaying the result, otherwise the PlugIn() function returns true.
- | If the cache file doesn't exist or if it has been created more than x seconds ago, then "Cache on Show" is started (see above). The script continues normally and PlugIn() function returns false.
TBS_CACHENOW | Save the current result of the merge in the cache file corresponding to CacheId. PlugIn() function returns false. Example: $TBS->PlugIn(TBS_CACHE,$CacheId,TBS_CACHENOW);
TBS_CACHELOAD | Load the cache file corresponding to CacheId. PlugIn() function returns true if the cache file has been found and loaded, otherwise it returns false. Example: $TBS->PlugIn(TBS_CACHE,$CacheId,TBS_CACHELOAD);
TBS_CACHEDELETE | Delete the cache file corresponding to CacheId, if it exists. You can delete all the cache files of the directory using '*' for CacheId. Returns the number of deleted files. Examples: $TBS->PlugIn(TBS_CACHE,$CacheId,TBS_CACHEDELETE); $TBS->PlugIn(TBS_CACHE,'*',TBS_CACHEDELETE);
TBS_CACHEDELETEMASK | Delete files using a mask instead of the CacheId. Returns the number of deleted files. The mask must not contain any path information. Use the optional argument $Dir instead. Example: $TBS->PlugIn(TBS_CACHE,'*.txt',TBS_CACHEDELETEMASK,'./temp'); Supported since plug-in version 1.0.5
TBS_CACHEONSHOW | Start "Cache on show" for the cache file corresponding to CacheId. Always return false. Example: $TBS->PlugIn(TBS_CACHE,$CacheId,TBS_CACHEONSHOW);
TBS_CACHECANCEL | Cancel "Cache on Show" whatever is CacheId. Always return false. Example: $TBS->PlugIn(TBS_CACHE,$CacheId,TBS_CACHECANCEL);
TBS_CACHEGETAGE | Return the age of the cache file in seconds. Return false if the cache file doesn't exist.
TBS_CACHEGETNAME | Return the name of the cache file corresponding to the given CacheId. A name is returned even if the cache file doesn't exist yet.
TBS_CACHEISONSHOW | Return true if "Cache on show" is activated, otherwise, return false.

Setting Cache Sytem parameters:
By installing the plug-in manually, you can set the default directory and the names of cache files. Take care that you must install the plug-in before to use its command. Installing the plug-in after having called the command will produce an error.
Install syntax: $TBS->PlugIn(TBS_INSTALL, TBS_CACHE {, string Dir}{, string Mask})

Argument | Description
Dir | Default value is false. Indicates tThe path of the directory where the cache file is saved. By default, it is the same directory as the your application.
Mask | Default value is 'tbs_cache_*.php'. Representes the names of the created cache files. The mask must have one joker character '*' wich is replaced by the cache Id. For example, with the default mask, the command $TBS->PlugIn(TBS_CACHE,'mainpage',1000); will create a cache file named 'tbs_cache_mainpage.php'.

Example :
include_once('tbs_plugin_cache.php');
$TBS->PlugIn(TBS_INSTALL, TBS_CACHE, './cache', 'cache_*.tmp');
$TBS->PlugIn(TBS_CACHE, 'mainpage', 3600);
Plug-in NavBar version 1.0.6
This plug-in enables you to displays a navigation bar based on specific TBS block and TBS fields.The design of the navigation bar must be prepared in the HTML side using TBS block havins some specifications. See HTML side for more details.
Requirement: include the file 'tbs_plugin_navbar.php'. This can be after the TBS object variable is created.
Installation mode: automatic when the plug-in command is called for the first time.
Command syntax: $TBS->PlugIn(TBS_NAVBAR,string NavName, mix Options, int PageNum [, int RecCount, int PageSize])

Argument | Description
NavName | The name of the navigation bar. Note: you can merge several Navigation bars in one time and with the same options by separating their names with a comma.
Options | Enables you to force some options of the navigation bar. Those options can also be defined using block parameters in the template. But if you put them at the PlugIn() command too, they will be forced. This parameter can be blank ('', 0 or null), a numeric value or an array. If it's a numeric value, it indicates the number of pages displayed. If it's an array, it can contain the following items:
Key | Value
'navsize' | Number of pages displayed in the navigation bar. (default = 10).
'navpos' | Position of the navigation bar compared to the active page number. Use one of the following keywords: - 'step' (by default) to have the bar progressing by step. - 'centred' to center the bar on the active page number.
'navdel' | Name of a TBS block to delete when there is only one page or no page to display. This TBS block must surroud the navigation bar. If there are several pages to display then only TBS definition tags of this bloc are deleted.
'pagemin' | Number of the first page (default = 1).
PageNum | Number of the active page. The first page is number 1. To indicate the last page, use the value -1.
RecCount | Optional. The default value is -1. Indicates the total number of records, if known. If this number is unknown, you have to put the value -1. This argument is used only to calculate the number of the last page of the navigation bar.
PageSize | Optional. The default value is 1. Indicates the number of records per page. It has to be used together with RecCount. It is used only to calculate the number of the last page of the navigation bar.

Example:
$TBS->PlugIn(TBS_NAVBAR,'nav','',$page,$rec_nbr,$page_size);
HTML side
Use a normal TBS block to display the page numbers.
This block will be merged with a virtual data source having as much records as pages to display, and with the following columns:

Name | Description
page | Returns the number of a common page, reachable from the navigation bar.
curr | Returns the number of the active page.
first | Returns the number of the first page (1 by default).
prev | Returns the number of the previous page.
next | Returns the number of the next page.
last | Returns the number of the last page if it's known, otherwise returns -1.

page is the only value that changes and its linked field must be placed inside the block. Others columns have always the same value and can be placed inside the block as well as outside the block.
Those fields support the parameter endpoint. It will replace the value of the field with an empty string ('') when the active page is equal to first page or last page. This enables you to manage display exceptions with parameter magnet for example.
Example:
<a href="script.php?page=[nav.first;endpoint;magnet=a;mtype=m+m]">Beginning</a>
In this example, the link will be deleted when the active page is the first page.
The block can contain a special section to display the active page differently.
This section is defined using parameter currpage on the block definition.
Example:
Template:

|< | < | [nav.page;block=td] | [nav.page;block=td;currpage] | > | >|

Php code used:
$TBS->PlugIn(TBS_NAVBAR,'nav',10,17) ;
Result of the merge:

|< | < | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | > | >|

Remark: this example doesn't display links.
You can use parameter bmagnet (which is a block's parameter supported by TBS) to delete the navigation bar when there is only one page to display.
Example:

|< | < | [nav.page;block=td;bmagnet=table] | [nav.page;block=td;currpage] | > | >|

Options
The block definition can contain parameters that are specific to the navigation bar.
Those options can also be defined as a parameter of the plug-in's command

Parameter | Description
navsize=num | Number of pages displayed in the navigation bar. (default = 10).
navpos=keyword | Position of the navigation bar compared to the active page number. Use one of the following keywords: - 'step' (by default) to have the bar progressing by step. - 'centred' to center the bar on the active page number.
pagemin=num | Number of the first page (default = 1).

Plug-in HTML version 1.0.4

Versioning: | Plug-in HTML version 1.0 run with TBS 3.0.0 to 3.0.6
| Plug-in HTML version 1.0.2 and higher run with TBS >= 3.1.0

This plug-in provides several features to manage HTML templates:
• Select HTML items (lists, checkboxes and radio buttons).
• Looks if contents is HTML before to convert.
Those features can be called from any TBS field using parameter "ope=html". See below for more details.
The plug-in must be installed, otherwise you'll have a TBS error: "parameter ope doesn't support value 'html'".
Requirement: include the file 'tbs_plugin_html.php'.
Installation mode: automatic when included before the creation of the TBS variable.
If you include it after the creation of the TBS varibale, you should force the installation by using the command :
$TBS->PlugIn(TBS_INSTALL,TBS_HTML);
Command syntax: (no command).
Select HTML items:
List of options:

| Example: which will become after the merge:

Create a new item anywhere in the list. Inside this item, place a TBS field which would display the value of the item to select (you can place it anywhere inside the option tags). Then add parameters ope=html and select (without value) to the TBS field and it will select the corresponding item. This new item won't be displayed, il will only make other be selected.
If the value of the field is a PHP array, then several items can be selected.
If the value of the field is not found in the list, then no item is selected. But if you add parameter addmising then not found values will be added at the end of the list. Parameter addmissing is supported since version 1.0.3 of this plug-in.
Radio buttons and Checkboxes:
Place a TBS field which would display the value of the item to select (you can place it anywhere in the area containing items to select, see optimization below for more details about this area). Then add parameters ope=html and select=tagname to the TBS field and it will select the corresponding item. Only radio buttons and checkboxes named tagname will be browsed. The TBS field won't be displayed, il will only make items be selected.

| Example:
Boston [var.town_id;ope=html;select=r_test] Washington New York | which will be after the merge: | Boston Washington New York
In this example, the Radio button captioned 'Washington ' has been selected because the name of the Radio button tag is ''r_test' and its value is 2, and the TBS tag named 'town_id' has been merged with the value 2.

If the value of the field is a PHP array, then several items can be selected.
Optimization:
By default the bounds for searching items to select are html tags <select> for lists , and <form> for radio buttons and checkboxes. But you can change those bounds using parameter selbounds. It enables you to change the search zone for items to select by indicating an HTML tag type.
Example:
[var.town_id;ope=html;select=r_test;selbounds=div]
In this example, items to select will be searched between <div> and </div> tags that surround the TBS field.
Look if contents is HTML :
Use a TBS field with parameter ope=html and parameter look in order to check the value to merge and to convert it into HTML only if is not yet HTML.
Example:
[var.entered_data;ope=html;look]
Plug-in MergeOnFly version 1.1.1
This plug-in enables the MergeBlock() method to display data on fly. This means that the result of the merge will be displayed progressively during the execution of MergeBlock(). At the end of the MergeBlock(), only the part of the template after the block will remain. You steel have to use the Show() method for this ending part.
Notice: when you call the plug-in command, it activates the OnFly mode only for one MergeBlock() call. Other MergBlock() calls won't have the OnFly mode until you call the plug-in just before them.
You have to take care that the OnFly mode will cost much more time execution, because several small echo() commands always cost more time than a single big one. Despite this loss of execution time, the OnFly mode can be a smart issue when you have a very large number of records to display because the user can start the read the data before it ends.
Requirement: include the file 'tbs_plugin_mergeonfly.php'. This can be after the TBS object variable is created.
Installation mode: automatic when the plug-in command is called for the first time.
Command syntax: $TBS->PlugIn(TBS_ONFLY, int PackSize [, boolean CountSubRecord=false])

Argument | Description
PackSize | Number of records to display at a time.
CountSubRecord | true if the merged block have sub-blocks and you'd like sub-records to be counted for the PackSize. Defult value is false.

Example :
include_once('tbs_plugin_mergeonfly.php');
$TBS->PlugIn(TBS_ONFLY, 100);
$TBS->MergeBlock('b1','mysql','SELECT * FROM t_table1');