OpenTBS

version 1.3.2, 2010-07-22, by Skrol29
help file modified on 2010-07-26
  1. Introduction
  2. Installing
  3. Understanding principles
  4. Synopsis and code examples
  5. Demo
  6. Debugging your template
  7. What to do if Zlib extension is not enabled with PHP?
  8. Changelog
  9. License

Introduction

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.

Installing

Requirements:
- TinyButStrong version 3.5.0 or higher ("tbs_class.php" or "tbs_class_php5.php").
- 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.

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 output the entire zip archive including modified stored files. The output 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.

Synopsis and code examples

- Prepare the TinyButStrong Template Engine with the OpenTBS plug-in

include_once('tbs_class.php');
include_once('tbs_plugin_opentbs.php');

$TBS = new clsTinyButStrong;
$TBS->Plugin(TBS_INSTALL, OPENTBS_PLUGIN);

- Method LoadTemplate()

• Load an archive with the automatic extension recognition (explained above):
$TBS->LoadTemplate('document.odt'); // Load the archive 'document.odt'.

• Load an archive without the automatic extension recognition: (supported since OpenTBS version 1.1)
$TBS->LoadTemplate('document.odt#');

• Load an archive and one file stored in this archive:
$TBS->LoadTemplate('document.odt#content.xml');

• Load an archive and several files stored in this archive:
$TBS->LoadTemplate('document.odt#content.xml;settings.xml');

• Load a stored file from the current archive:
$TBS->LoadTemplate('#content.xml'); // Load the stored file 'content.xml' from the current archive.
The archive must be previously loaded.
If the file is stored in a subfolder, then indicate the full path. For example: 'word/document.xml'.

• Load an archive with special data conversion: (supported since OpenTBS version 1.3.2)
$TBS->LoadTemplate('document.odt', OPENTBS_ALREADY_UTF8);
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).

- Method Show()

•Output the merged archive as an HTTP donwload: ($file_name is optional)
$TBS->Show(OPENTBS_DOWNLOAD, $file_name);

• Output the merged archive as an HTTP output with your customized HTTP headers:
header(...); // your custom headers here
$TBS->Show(OPENTBS_NOHEADER); // output the binary file without header

• Output the merged archive as a new file saved on the server's disk:
$TBS->Show(OPENTBS_FILE, $file_name);

• Output the merged archive as a PHP string: (supported since OpenTBS version 1.1)
$TBS->Show(OPENTBS_STRING);
$string = $TBS->Source;
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.

- Other

• Automatically add an external picture file in the archive: (supported since OpenTBS version 1.3, for OpenOffice and MsOffice documents only)
Example: [onshow.x;ope=addpic;from='../pic/[val].gif';as='[val].gif';att=draw:image#xlink:href]
You can automatically add a new picture file in the archive by coding a TBS field directly in the template. When you define parameter "ope=addpic" for a TBS field in your template, then TBS will use the value of the field to insert the corresponding picture file inside the archive.
- Parameter "from" can be used to define the path of the picture to insert. The value can contain [val] or [var] fields. Parameter "from" is optional ; the default value is the field's value.
- Parameter "as" can be used to give a different internal name to picture file when copied in archive (the external picture file is not renamed, and the internal name must be without path). The value can contain [val] or [var] fields. Parameter "as" is optional ; the default value is the file name, without folder, of the field's value.
OpenTBS will found the correct folder in the archive where to place the picture according to the extension of the opened document.
The demo provides other examples of the usage of parameter "ope=addpic".
Note:
If you add a new picture inside the archive, you probably also need to display the picture in the document. For this, the TBS field you are using to insert the picture has its final value modified to be the internal name of the picture. Use it to change the proper attribute of the picture tag in the template.
In an OpenDocument, the following parameter can move the TBS field in the previous image tag: "att=draw:image#xlink:href"
In an OpenXML, the following parameter can move the TBS field in the previous image tag:"att=v:imagedata#r:id"

• Add any new file in the archive: (supported since OpenTBS version 1.3)
$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_ADDFILE, $Name, $Data, $DataType=TBSZIP_STRING, $Compress=true);
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 an existing file in the archive: (supported since OpenTBS version 1.3)
$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_DELETEFILE, $Name);
Delete the existing file in the archive, or a file previously added using the OPENTBS_ADDFILE command.

• Reset all modifications in the archive: (supported since OpenTBS version 1.1)
$TBS->Plugin(OPENTBS_PLUGIN, OPENTBS_RESET);
The automatic extension recognition is also applied as it was applied for the first load of the archive.

• Display debugging information:
$TBS->Show(OPENTBS_DEBUG_XML);
This will activate the debug mode and display the listing of added files, modified files and deleted files in the archive. It also display the contents merged with OpenTBS.
Note that this option overrides the others (since version 1.3.2). Thus it simplifies the debugging because you can add it to your existing call.
For example: $TBS->Show(OPENTBS_DOWNLOAD + OPENTBS_DEBUG_XML, $file_name); this will do only the debugging.

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

Demo

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

Debugging your template

Here is 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 option but a php error message or any other unexpected content has been output before by PHP.
Active the debug mode using the 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.
Active the debug mode using the 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".

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.

Changelog

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 output mode : 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.

License

OpenTBS is under LGPL (Lesser General Public License)