Plug-in Help

include('tbs_class.php');
$TBS = new clsTinyButStrong; // The TBS engine

include('tbs_plugin_excel.php');
$TBS->PlugIn(TBS_INSTALL,TBS_EXCEL); // Install the Excel plug-in

$TBS->LoadTemplate('my_template.xml'); // Open the Excel-XML template
$TBS->MergeBlock('bz',$my_data); // Merge the block
$TBS->Show() // Force the result to bas donwload as an Excel file.

include the file 'tbs_plugin_excel.php'. This can be after the TBS object variable is created.
This plug-in requires TBS version 3.0.5 or higher.

Example:

$TBS->PlugIn(TBS_INSTALL,TBS_EXCEL);

• Change the name of the file for download:

$TBS->PlugIn(TBS_EXCEL,TBS_EXCEL_FILENAME,'file.xls');

• Enables the file to be displayed within the browser (Internet Explorer only):

$TBS->PlugIn(TBS_EXCEL,TBS_EXCEL_INLINE);

- When the method Show() is called, then the merged template is output as a file for download. You can cancel the download by using the TBS property Render.
- By default, the file to download has the same name as the template but with an ".xls' extension. You can change the default file name using a command described above.

You can choose one of those two ways:
• Create a new document with Excel. Save it with choosing "XML Spreadsheet (*.xml)" for the File type in the dialog box.

I suggest you to change the extension of the file for ".xls" just in order to have your template opened with Excel normally from Windows Explorer. Otherwise, Windows Explorer may ask you to choose a program to open the XLS file when you double-click on it. What ever, Excel will makes no problem to open your file.

or:
• Use the empty.xls file which is provided with this plug-in distribution.

Your template can have several sheets, and you can use all Excel formats for displaying you data.

Microsoft Excel assigns a type for each value placed into a cell (it can be String, Numeric, BateTime, Boolean or Error). But when you put a TBS field into a cell, then the type of the cell's value is automatically set to String. If the value to be merged by the TBS field is not a string, you can force the type of the cell's value using parameter ope. This can be useful for calculating total, or using Excel formats for example.

Parameter		Value forced to
ope=xlNum		Numeric
ope=xlDT		DateTime

Examples:

Current date:	[var..now;ope=xlDT]
Total amount:	[var.amount;ope=xlNum]

Remark: If the merged value is not corresponding to its type then it will produce an error when the document is opened.
The String type can display any value.

Within an Excel-XML document, <Table> <Row> and <Cell> elements are use to dispose data into the Worksheets. It is quite similar to the HTML <table><tr> and <td> elements. But a <Table> is really tuchy to multiply (see section Debuggin below).

Thus, the more commun TBS blocks you'll define will be block=Row when you want to exand rows, or block=Cell when you whant to expand columns.
Examples:

Title	Price
[b1.title;block=Row]	[b1.price;ope=xlNum]

After a block is merged, Excel formulas (like SUM) over this block may not be what you wanted because cells or rows have been expanded by the block.

• If the formula is placed on the rigth or bottom of the merged block:

Use an Excel formula with Absolute Reference to refer to the first cell of the block, and Relative Reference to refer to the last cell of the block. This way, the formula will stay valid after the block is expanded. This is working because Relative References are save relatively to the cell with the formula.

Example:

	A	B
1	[b1.title;block=Row]	[b1.price;ope=xlNum]
2		=SUM(B$1:B1)

• If the formula is placed on the left or top of the merged block:

The tip above won't fit in this case because both relative ans absolute reference will refer to the first cell of the block. So this plug-in give another dedicated trick for this.

TBS parameter ope=xlPushref placed in an Excel formula, makes the previous Relative Reference to be pushed as much as the value of the TBS field's value. Only the first previous Relative Reference will be pushed. The TBS field with parameter must be placed inside a +N("") function, this enables the Excel formula to stay valid. If your formula deals with strings, you can use &N("").

Example:

	A	B
1		=SUM(B2:B2)+N("[b1.#;ope=xlPushRef]")
2	[b1.title;block=Row]	[b1.price;ope=xlNum]

TBS error messages will cause the result to not be a downloadable file because error messages are prompted before header information are sent.
Nevertheless, your result may be an invalid Excel-XML document. XML syntax is less tolerating than HTML. If your document is invalid then Excel will prompt an unhelpful error message when opened. Then you will probably need to look at the source of the merged document to understand what's wrong.

Here is some interesting information about the Excel-XML syntax:

- One document contains one or several <Worksheets> elements.
- One <Worsheet> contains one or several <Table> elements.
- One <Table> contains one or more <Row> elements.
- One <Row> contains one or more <Cell> elements.

Diagram:
<Worksheet ... >
  <Table ... >
    <Row ...>
      <Cell ...> </Cell> <Cell ...> </Cell> <Cell ...> </Cell>
    </Row ...>
  </Table ... >
</Worksheet ... >

• Microsoft Excel decides how to split your data in <Tables> , <Cell> and <Row>. Or you can decide it by yourself by manually changing the source of the template.
• Take care that your items may be separated in several <Table> elements in a Worksheets, this happens mostly when data items are separated by numerous empty cells.
• <Tables> elements should not be repeated by merging TBS block because their first <Row> and <Cell> elements may contain absolute indexes for positioning.
• They are some other XML elements but not really interesting for merging TBS blocks.

Version 1.0.3:	Monor fixes in the HTML header which force the file to download.
Version 1.0.2:	Bug fixed about special sections (like headergrp, when, nodata, ... ) that could be bad placed after a MergeBlock().