OpenTBS

version1.1, 2009-11-19, by Skrol29
help file modified on 2010-03-10
  1. Introduction
  2. Installing
  3. Understanding principles
  4. Code examples
  5. Demo
  6. Changelog
  7. 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 XML, HTML and Text files.

With TinyButStrong and its plug-in OpenTBS, you can use the template engine to merge OpenOffice documents and Ms Office 2007-2010 documents with lot of facilities. All OpenDocument Format (ODF) and Office Open XML (OOXML) can be merged with OpenTBS,and also XPS files. 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 >=2007.
• 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 for PHP enabled (version 1.2.3 or higher, a lower version can makes corrupted documents).

Installation:
Just add the file "tbs_plugin_opentbs.php".

What difference if the Zlib extension is not enabled in the PHP configuration?
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 (see below).

When Zlib extension in not enabled in PHP
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.

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

Thus, LoadTemplate() becomes able to first load a zip archive (an OpenOffice or Ms Office document), and then to load for a merge 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 is able to 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.

Please note that this version of OpenTBS can only modify exiting files in the archive. It cannot delete an existing file, and cannot add new files in the archive.

OpenTBS has an automatic extension recognition. When you load a document (an archive) which has one of the following extensions (odt, odg, ods, odf, odp, 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.

Even if you can edit your template using directly OpenOffice or Ms Office >=2007, you will probably need to understand the XML tags and attributes you will merge. Here is a small synopsis of the files supported by OpenTBS in native : xml_synopsis.txt

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 previlously loaded.
If the file is stored in a subfolder, then indicate the full path. For example: 'word/document.xml'.

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.

• Display the current file loaded file from the archive for debugging purpose:
$TBS->Show(OPENTBS_DEBUG_XML);
Note that [onshow] files are merged before the display.

Other

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

• 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

Run the following demo under PHP: OpenTBS demo

Changelog

version 1.1, on 2009-11-19
- New ouput 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)