OpenTBS

version 1.3.1, 2010-07-01, by Skrol29
help file modified on 2010-07-01
  1. Introduction
  2. Installing
  3. Understanding principles
  4. Synopsis and 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 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). 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 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. But you do not have to bother with it because OpenTBS is managnf archives invisibly.

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.

Even if you can edit your template using directly OpenOffice or Ms Office, you will probably need to understand the XML tags and attributes you will merge. The file of the files xml_synopsis.txt is a small synopsis of the XML structure you can met in the inner source of those documents.

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

Other

• Automatically add an external picture file in the archive: (supported since OpenTBS version 1.3)
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 it comes 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 the current file loaded from the archive for debugging purpose:
$TBS->Show(OPENTBS_DEBUG_XML);
Note that [onshow] files are merged before the display.

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