OpenTBS plugin

OpenTBS is a plug-in for the TinyButStrong Template Engine.

TinyButStrong is a PHP Template Engine which has special template syntax and allows you to design templates in their natural editing tools. But it normally works only for Text files, including XML and HTML.

With TinyButStrong and its plug-in OpenTBS, you can use the template engine to merge OpenOffice documents and Ms Office documents with lot of facilities. All OpenDocument Format (ODF) and Office Open XML (OOXML) can be merged with OpenTBS, and also XPS files (XPS is a PDF competitor provided by Microsoft). In fact, all zip archives containing Xml/Html/Text files can be merged with OpenTBS.

What is special to OpenTBS:
• Design your templates directly with OpenOffice or MS Office.
• No exe file needed to merge documents.
• No temporary files needed to merge documents.
• Output directly as an http download, a new file on the disk, or as a string (for file attachment for example).
• Works with both PHP 4 and PHP 5.
• No PHP extension is required (If the Zlib extension is enabled it becomes easier to use templates, see more detail below)

You should know Template Engines and more specifically TinyButStrong to use OpenTBS.

2. Installing

Requirements:
- TinyButStrong version 3.6.0 or higher.
- PHP 4.3 or higher, PHP 5
- It is better to have the Zlib extension enabled on your PHP installation. If it's not, here is what to do.

Installation:
Just put the file "tbs_plugin_opentbs.php" with your PHP scripts.

3. Understanding principles

It is important to figure out that OpenOffice and Ms Office (since version 2007) documents are technically zip archives containing XML files, even if the extension of the document is not ".zip". Those zip archives can contain other file types like pictures or sounds, but the document structure and the text contents are saved as XML files.

TinyButStrong can merge XML files, but cannot read zip archives by itself. The plug-in OpenTBS extends the TinyButStrong methods LoadTemplate() and Show() to make them working with zip archives. But you do not have to bother with it because OpenTBS is managing archives in a way that is invisible for you.

When the OpenTBS plugin is installed, the LoadTemplate() method becomes able to first load a zip archive (an OpenOffice or Ms Office document), and then to load the contents of any XML or Text files stored in the archive. You can then merge the contents of XML or Text files with all features of the TinyButStrong template engine. At the end, the Show() method does render the entire zip archive including modified stored files. The render can be done as an HTTP download, a news file on the server's disk, or in a PHP string.

Since OpenTBS version 1.3, you can also add and delete files in the archive. Before this version you could only modify existing files in the archive.

OpenTBS has automatic extension recognition. When you load a document (an archive) which has one of the following extensions { odt, odg, ods, odf, odp, odm, docx, xlsx and pptx }, then the main XML file of the archive are automatically loaded, and some special character conversion are preset. For example, for all OpenDocument files, the stored file "content.xml" is automatically loaded.

4. Synopsis and code examples

4.1. Preparation of TinyButStrong Template Engine with the OpenTBS plug-in

4.2. Method LoadTemplate()

The archive must be previously loaded.
If the file is stored in a subfolder, then indicate the full path. For example: 'word/document.xml'.

OpenTBS manages XML files that are UTF8 encoded. But by default, it assumes that all the data to merge (which can come from PHP or SQL) is Ascii encoded, and thus it performs conversions. If you want to define the data conversion, then you can use one of the following constants:
- OPENTBS_DEFAULT: OpenTBS assumes that all data is ASCII encoded,
- OPENTBS_ALREADY_UTF8: OpenTBS assumes that all data is already UTF8 encoded,
- OPENTBS_ALREADY_XML: OpenTBS assumes that all data is already XML encoded, and thus it won't convert data at all. Take care of that option.
Please note that if you need to change the data conversion for one or few fields only in your template, then you can use parameter "htmlconv" (see the TBS documentation for more details).

4.3. Method Show()

When you use OPENTBS_STRING then there is no output for the client. But instead, the binary source of the archive is placed into property $TBS->Source. This feature can be useful, for example, when you want to place the merged document into an email as an attached file.

4.4. Change pictures in the document

Parameter "ope=changepic" is a feature provided by the OpenTBS plug-in, which extends the "ope" parameter natively present with TBS.
When a TBS field having "ope=changepic" is placed in the template and merged, then OpenTBS will search the first picture located before the field (to be more precise, the TBS field must be located somewhere inside or after the opening tag of the picture in the template source code), and then it will change the picture assuming that the value of the field is the path for a picture file on the server. You don't have to care about loading the picture file in the document, OpenTBS will manage this for you.

In order to simplify your coding, they are other complementary parameters that are provided:

Parameter "from" enables you to reformulate the path of the picture to insert. The parameter's value can contain the [val] keyword or any [var] fields, they work the same way as with parameter "file". Parameter "from" is optional.
Parameter "as" enables you to reformulate name of the picture that it will take inside the document. It is rare to need it, but it can help in some cases. Note that the external picture file is not renamed. The new name must be defined without path. The parameter's value can contain the [val] keyword or any [var] fields, they work the same way as with parameter "file". Parameter "as" is optional.
Parameter "default" enables you to define the picture that should be used when the expected one is not found. The parameter's value must be the path of a file on the server, or the keyword "current". If you've set "default=current" then OpenTBS will let the picture of the template if the expected one is not found.

4.5. Manual modification of files in the archive

Add a new file in the archive. If $Data is false then the previously add file with the given name is canceled if any. $DataType accepts TBSZIP_STRING and TBSZIP_FILE ($Data must then be the path of the external file to insert). $Compress can be true, false or an array with keys ('meth','len_u','crc32') which means that the data is already previously compressed.

Delete the existing file in the archive, or a file previously added using the OPENTBS_ADDFILE command.

The automatic extension recognition is also applied as it was applied for the first load of the archive.

4.6. Miscellaneous

• Property $TBS->tbsCurrFile indicates the name of the current file loaded from the archive. The value is false if no file is loaded yet from the archive.

Other TinyButStrong methods and properties stay unchanged and are available for merging your template.

5. Demo

The OpenTBS package includes a full set of runnable templates. Some templates can contain useful complementary information for designing.
Run the following demo under PHP: OpenTBS demo

6. Debugging your template

Since OpenTBS version 1.3.2, there is a debug render option which displays information instead of producing the final result:

This command will render the result as debug information. I.e. OpenTBS will display the listing of added files, modified files and deleted files in the archive. And it also displays the XML contents it has merged.
If you combine the render option with other render options, then the debug will be done instead of any other render.
For example: $TBS->Show(OPENTBS_DOWNLOAD + OPENTBS_DEBUG_XML, $file_name); this will do only the debug.

You can also use the OPENTBS_DEBUG_AVOIDAUTOFIELDS render option in order to avoid automatic fields (like [onshow] and [var]) to be merged.
For example: $TBS->Show(OPENTBS_DEBUG_XML + OPENTBS_DEBUG_AVOIDAUTOFIELDS);

If you want to avoid [onload] fields to be merged, then use the OPENTBS_DEBUG_AVOIDAUTOFIELDS render option on the Render property before the document is loaded.
For example:
$TBS->Render = OPENTBS_DEBUG_AVOIDAUTOFIELDS;
$TBS->LoadTemplate('mydoc.odt');

Otherwise, here are some indications that may help for the issues you can met with merging:

a) The merged document is producing error messages when opened with its application (OpenOffice or Ms Office)

The most likely causes are:
• You've chosen the OPENTBS_DOWNLOAD render option but a php error message or any other unexpected content has been output before by PHP.
Activate the debug mode using the render option OPENTBS_DEBUG_XML, it helps to check PHP error message and other unexpected content.
or:
• The merging has produced an invalid XML content in an XML file of the document.
Activate the debug mode using the render option OPENTBS_DEBUG_XML, it helps to check the XML contents of merged files. See section (b) below for more information in the XML structure of the files.

b) The merged document is well opened by its application (OpenOffice or Ms Office) but the content is not designed as expected

First, you can have a look the demo templates, they contain examples and advices for each type of document.
And to go further: even if you can edit your template using directly OpenOffice or Ms Office, you will probably need to understand the XML tags and attributes to complete your merge. The file xml_synopsis.txt is a small synopsis of the XML structure you can found in the inner source of those documents. Have a look to it if you feel lost.

c) Go deeper in the debugging

You can view the inner source of a document using a zip software like 7-Zip. It allows you to open an archive even if the extension is not ".zip".

7. What to do if Zlib extension is not enabled with PHP?

OpenTBS uses Zlib functions in order to automatically uncompress and recompress files stored in the zip archive. If Zlib is not enabled, then you have to use your own uncompress/compress tool, or to prepare the template to have files uncompressed in the zip archive.

Example to uncompress the "content.xml" file in an ODT document using 7-Zip:
1) open the ODT file with 7-Zip
2) extract the "content.xml" file from the ODT file in the same folder than the ODT file
3) close 7-Zip
4) open 7-Zip, and change current directory to be the same as the ODT file
5) select the "content.xml" file and click on button [Add], or menu [File][7-Zip][Add to archive...]
6) A new window named "Add to archive" is opened,
- replace the archive name with the ODT file name,
- set the Compression level to "None".
7) Click on [Ok]
If you re-open the ODT file with 7-Zip, you can notice that the size and the uncompressed size are the same.
If the file should be placed in a sub-folder of the archive, then open the archive and rename the file in order to move it in a folder. For example rename "manifest.xml" to "META-INF\manifest.xml" will move it into META-INF. But moving the file will no delete the one which has the same name in the target folder. You have to go and delete the old one.

8. Changelog

version 1.5.0, on 2011-03-20
- new feature: headers and footers are automatically loaded for OpenOffice & MsOffice.
- new feature: automatically cleans up spelling and change trackings information in MsWord templates (such information may deconstruct the TBS tags). This feature can be disabled.
- new constant OPENTBS_DEBUG_AVOIDAUTOFIELDS
- improvement: Debug doesn't stopped if an OpenTBS alert occurs.
- improvement: OpenTBS alerts say if the process will be stopped.
- fixed bug: in debug mode: "warning function.str-repeat: Second argument has to be greater than or equal to 0"
- fixed bug: when using OPENTBS_RESET: "Warning: Missing argument 2 for clsOpenTBS::OnCommand() in ... on line 225"
- fixed bug: DML images were not found when using parameter "ope=changepic" in a DOCX document
- fixed bug: the script ends and display the XML contents when a when using parameter "ope=changepic" with a new image type in a DOCX document

version 1.4.1, on 2010-10-28
- major bug fixed: due to TbsZip, some added or modified files can be saved the document with a wrong CRC control code. This could make softwares to consider the document as corrupted, but were often easily fixed by OpenOffice and Ms Office. Only few CRC codes are wrongly saved, thus the bug is rare and can seem to appear randomly on few documents.

version 1.3.3, on 2010-08-05
- property Version of OpenTBS version 1.3.2 was saying 1.3.1

version 1.3.2, on 2010-07-23
- possibility to change de default data conversion using the new constants OPENTBS_DEFAULT, OPENTBS_ALREADY_XML or OPENTBS_ALREADY_UTF8
- enhanced debug mode: listing of added, deleted and modified files ; and show XML formated contents of files merged with OpenTBS.

version 1.3.1, on 2010-07-01
- based on TbsZip version 2.1: fixes a bug that saved a bad time of modification file was added, and saved time modification when a file content is replaced.
- the addpic operator now automatically updates the "fanifest.xml" file on OpenOffice document. Without this fix, an ODP merged document could be open with an error message with OpenOffice >= 3.2

version 1.3, on 2010-06-01
- a new plugin command that add a new file in the archive
- a new plugin command that delete a new file in the archive
- a parameter 'ope=addpic' that add a new picture in the archive directly from the template
- based on a TbsZip v2 (modify/delete/add files in a zip archive, )

version 1.1, on 2009-11-19
- New render option : OPENTBS_STRING
- New feature: can reset changes in the current archive using $TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_RESET);
- New behavior: extension of the archive is ignored by LoadTemplate() if the name is ended with '#'
- Bug fixed: in case of several files to take from the archive in one shot, then only the last one had [onload] fields merged.

OpenTBS

1. Introduction