tbsOOo : TinyButStrong OOo

Author : Olivier LOYNET (tbsooo@free.fr)
Date : 2006-06-12
Version : 0.7.9
Web site : http://www.tinybutstrong.com
Forum : http://www.tinybutstrong.com/forum.php
Released under the GNU LGPL license : http://www.gnu.org/copyleft/lesser.html

tbsOOo PHP class extends the template engine TinyButStrong.

This class allows to create OpenOffice documents dynamically by separating display formatting from logic and data.
In practice, you create a template using OpenOffice with the TinyButStrong tags.
Then you create a PHP script that merges the template with a data source to get a new OpenOffice document.

News

[2006-06-12] TinyButStrongOOo 0.7.9 released
Correct a problem of EURO caracter
Correct a problem of zip parameters
New AddFileToDoc method : Add a file like an image to the current document
[2006-01] Forum
http://www.tinybutstrong.com/forum.php
[2005-12-12] TinyButStrongOOo 0.7.8 released
New SetDataCharset method : Define the source data's charset (ISO 8859-1, UTF8). By default ISO 8859-1 is used
[2005-11] PHP Classes : 5th place in October 2005 Innovation Award
The winners
[2005-10-12] Documentation
Small rectification and French version
[2005-09-28] TinyButStrongOOo 0.7.7 released
Convert "\n" source character to <text:line-break/>
[2005-09-23] TinyButStrongOOo 0.7.6 released
Special thanks to Skrol (skrol29@freesurf.fr) who write TinyButStrong and helped me to extend it to produce OpenOffice document.

Download

Download the last version with examples

Features

This class works on Linux, Windows and more…
This class works with OpenOffice 1.x documents and the new format used in OpenOffice 2 (OpenDocument 1.0, OASIS standard).
No need to install OpenOffice on your server.
This class uses the TinyButStrong native syntax and methods. You could merge 'var' and 'blocks' using the TBS syntax like (var, block, if, then, frm, ...). The merging operation respect the layout, justification and styles used in the template.

Limitations

This class can't add or change pictures dynamically in OpenOffice documents. The pictures have to be previously added during the template design.
This class can't add or change styles dynamically in OpenOffice documents. The style have to be previously defined during the template design.
This class can't use native XML format like 'date', 'url', 'number' in table or spreadsheet. All the merged data are in text format. Instead you can use the 'frm' parameter in TinyButStrong tags for formatting.

Requirements

server side

client side

Installation

Zip and Unzip

'zip'

'unzip'

'/usr/bin/zip'

'/usr/bin/unzip'

ZIP

UNZIP

info-zip

'c:\program files\bin\zip.exe'

'c:\program files\bin\unzip.exe'

Set PATH=c:\program files\bin;%PATH%

The process directory

'tmp/'

'/tmp'

'c:/windows/temp'

'c:\\windows\\temp'

OpenOffice

tips section

Tutorial

Step 1. Create a template with OpenOffice.

create an new writer document (.SXW).
write in the document the following TBS code : [var.x]
save the document as 'hello.sxw'
click here to load this example.

Step 2. Create a PHP script with the following code.

<?

    include_once('tbs_class.php');

    include_once('tbsooo_class.php');

  

  // data 

  $x = 'Hello World';

  

  // instantiate a TBS OOo class
 
  $OOo = new clsTinyButStrongOOo; 

  

  // setting the object

  $OOo->SetZipBinary('zip'); 

  $OOo->SetUnzipBinary('unzip'); 

  $OOo->SetProcessDir('tmp/'); 

  $OOo->SetDataCharset('ISO 8859-1'); 

  

  // create a new openoffice document from the template with an unique id 

  $OOo->NewDocFromTpl('hello.sxw'); 

  

  // merge data with OOo file content.xml 

  $OOo->LoadXmlFromDoc('content.xml'); 

  $OOo->SaveXmlToDoc(); 

  

  // display 

  header('Content-type: '.$OOo->GetMimetypeDoc()); 

  header('Content-Length: '.filesize($OOo->GetPathnameDoc())); 

  $OOo->FlushDoc(); 

  $OOo->RemoveDoc(); 

    ?>

Step 3. Execute the script to get an new document with data merged !.

click here to execute this example

Examples

	template	result
invoice example show on RMLL 2005	example_invoice.sxw	example_invoice.php
*TBS examples converted to tbsOOo*
	template	result
Hello World	tbsooo_us_examples_hello.sxw	tbsooo_us_examples_hello.php
variable merge	tbsooo_us_examples_var.sxw	tbsooo_us_examples_var.php
system variable merge	tbsooo_us_examples_system.sxw	tbsooo_us_examples_system.php
array merge	tbsooo_us_examples_dataarray.sxw	tbsooo_us_examples_dataarray.php
array merge horizontal	tbsooo_us_examples_datanum.sxc	tbsooo_us_examples_datanum.php
TBS frm parameter use	tbsooo_us_examples_prmfrm.sxw	tbsooo_us_examples_prmfrm.php
TBS max parameter use	tbsooo_us_examples_prmmax.sxw	tbsooo_us_examples_prmmax.php
TBS headergrp parameter use	tbsooo_us_examples_prmheader.sxw	tbsooo_us_examples_prmheader.php
TBS block syntax	tbsooo_us_examples_blocks.sxw	tbsooo_us_examples_blocks.php
TBS sub-block syntax	tbsooo_us_examples_subblock.sxw	tbsooo_us_examples_subblock.php
TBS serial syntax	tbsooo_us_examples_prmserial.sxw	tbsooo_us_examples_prmserial.php
TBS conditionnal display	tbsooo_us_examples_cond.sxw	tbsooo_us_examples_cond.php tbsooo_us_examples_cond.php?blk_id=1 tbsooo_us_examples_cond.php?blk_id=2 tbsooo_us_examples_cond.php?blk_id=3
TBS event syntax	tbsooo_us_examples_event.sxw	tbsooo_us_examples_event.php
TBS loop syntax	tbsooo_us_examples_loops.sxw	tbsooo_us_examples_loops.php?nbr=10 tbsooo_us_examples_loops.php?nbr=20 tbsooo_us_examples_loops.php?nbr=30

Tips

TinyButStrong :
- manual
- examples

Equivalent main tags beetween HTML and OpenOffice to use with TinyButStrong block syntax :

	HTML tags	OOo XML tags
table	<table>	<table:table>
row	<tr>	<table:table-row>
cell	<td>	<table:table-cell>

OpenOffice document format :

As XML has no native support for binary objects such as images, OLE objects or other media types, OpenOffice.org uses a package file to store the XML content of a document together with its associated binary data. This package is a standard Zip files, for more detail see :
The main XML files in an OpenOffice document to use with this class are :
- content.xml (document content)
- meta.xml (document header: document name, title, author, ...)
- styles.xml (document style sheet)
OpenDocument specs : http://www.oasis-open.org/committees/office/faq.php

Class definition

Constructor

Synopsis
$object = new clsTinyButStrongOOo()
Description
This class extend clsTinyButStrong
Parameter
none
Return value
object
Example
$OOo = new clsTinyButStrongOOo();

Methods

`boolean SetZipBinary (string $path_binary[, $test=false])`	Set the zip binary to compress XML files to OpenOffice documents
`boolean SetUnzipBinary (string $path_binary [, $test=false])`	Set the unzip binary to uncompress XML files from OpenOffice documents
`boolean SetProcessDir (string $process_path)`	Set the folder to process temporary OpenOffice documents
`void SetDataCharset (string $charset)`	Fix the source data's charset (ISO 8859-1 or UTF8)
`mixed NewDocFromTpl (string $ooo_template_filename)`	Create an new OpenOffice document from the OpenOffice template
`boolean LoadXmlFromDoc (string $xml_file)`	Unzip the XML file from the OpenOffice file and load as a TBS template to be merged
`boolean SaveXmlToDoc (void)`	Save the result from TBS into the XML file and zip into the OpenOffice document
`void AddFileToDoc (string $filename)`	Add a file into the OpenOffice document
`string GetPathnameDoc (void)`	Get the path of the new OpenOffice document
`string GetMimetypeDoc (void)`	Get the document mime type
`stream FlushDoc (void)`	Flush the document to STDOUT
`void RemoveDoc (void)`	Unlink the document
`void ClearProcessDir ([int $hour=2 [, int $minut=0]])`	Clean the process directory

Method: SetZipBinary

Synopsis
boolean SetZipBinary (string $path_binary[, $test=false])
Description
This method is optionnal. The default value in class is set to 'zip'.
The zip binary is needed to compress XML files into OpenOffice documents like a zip archive.
Parameter
string $path_binary : the full pathname or not, depend on the path server environment
boolean $test : make a test by executing zip, default false
Return value
boolean : TRUE is successfull
Note
This function can not be called statically.
Example
$OOo->SetZipBinary('zip'); // to fix the binary without the path, default value
or
$OOo->SetZipBinary('/usr/bin/zip'); // to fix the binary with the path
or
$OOo->SetZipBinary('/usr/bin/zip', true); // to fix the binary with the path and make a test

Method: SetUnzipBinary

Synopsis
boolean SetUnzipBinary (string $path_binary [, $test=false])
Description
This method is optionnal. The default value in class is set to 'unzip'.
The unzip binary is needed to uncompress XML files from OpenOffice documents like a zip archive.
Parameter
string $path_binary : the full pathname or not, depend on the path server environment
boolean $test : make a test by executing unzip, default false
Return value
boolean : TRUE is successfull
Note
This function can not be called statically.
Example
$OOo->SetUnzipBinary('unzip'); // to fix the binary without the path, default value
or
$OOo->SetUnzipBinary('/usr/bin/unzip'); // to fix the binary with the path
or
$OOo->SetUnzipBinary('/usr/bin/unzip', true); // to fix the binary with the path and make a test

Method: SetProcessDir

Synopsis
boolean SetProcessDir (string $process_path)
Description
Set the folder to process new OpenOffice documents. This directory need to be Read, Write and eXecute rights by PHP (or Apache) user.
The default value in class is set to 'tmp/'.
Parameter
string $process_path : the relative path from web site root. A trailing slash is automatically added.
Return value
boolean : TRUE is successfull
Note
This function can not be called statically.
Example
$OOo->SetProcessDir('tmp/'); // default value
or
$OOo->SetProcessDir('tmp'); // same as above
or
$OOo->SetProcessDir('./tmp'); // same as above

Method: SetDataCharset

Synopsis
void SetDataCharset (string $charset)
Description
Fix the source data's charset (ISO 8859-1 or UTF8).
This method is optionnal. The default value in class is set to 'ISO 8859-1'.
Parameter
string $charset : 'ISO 8859-1' or 'UTF8'.
Return value
none
Note
This function can not be called statically.
Example
$OOo->SetDataCharset('ISO 8859-1'); // default value
or
$OOo->SetDataCharset('UTF8');

Method: NewDocFromTpl

Synopsis
boolean NewDocFromTpl (string $ooo_template_filename)
Description
Create an new OpenOffice document from the OpenOffice template into the process directory with an unique ID.
Parameter
string $ooo_template_filename : OpenOffice document filename source
Return value
string : the new OpenOffice document pathname
Note
This function can not be called statically.
Example
$OOo->NewDocFromTpl('example_invoice.sxw');

Method: LoadXmlFromDoc

Synopsis
boolean LoadXmlFromDoc (string $xml_file)
Description
Unzip the XML file from the OpenOffice document and load as a TBS template.
Parameter
string $xml_file : the name of the main XML OpenOffice files are 'content.xml', 'meta.xml' and 'styles.xml'
Return value
boolean : TRUE is successfull
Note
This function can not be called statically.
Example
$OOo->LoadXmlFromDoc('content.xml');
or
$OOo->LoadXmlFromDoc('meta.xml');
or
$OOo->LoadXmlFromDoc('styles.xml');

Method: SaveXmlToDoc

Synopsis
boolean SaveXmlToDoc (void)
Description
Save the result from TBS in the XML file and zip into the OpenOffice document.
Parameter
none
Return value
boolean : TRUE is successfull
Note
This function can not be called statically.
Example
$OOo->SaveXmlToDoc();

Method: AddFileToDoc

Synopsis
void AddFileToDoc (string $filename)
Description
Add a file to the current document, like an image. The local path may be the same as the OOo document.
Parameter
string $filename
Return value
none
Note
This function can not be called statically.
Example
$OOo->AddFileToDoc('Pictures/new.jpg');

Method: GetPathnameDoc

Synopsis
string GetPathnameDoc (void)
Description
Get the new OpenOffice document path.
This method is useful is you want to get the pathfile of the new document to attach to a email or to convert it.
Parameter
none
Return value
string : the OpenOffice document pathname
Note
This function can not be called statically.
Example
$path = $OOo->GetPathnameDoc();
or
$realpath = realpath($OOo->GetPathnameDoc());
or
header('Location: '.$OOo->GetPathnameDoc()); // don't work with IE or if the document is proceed outside the web root

Method: GetMimetypeDoc

Synopsis
string GetMimetypeDoc (void)
Description
Get the OpenOffice document mime type.
Parameter
none
Return value
string : the document mime type
Note
This function can not be called statically.
Example
$mimetype = $OOo->GetMimetypeDoc();
or
header('Content-type: '.$OOo->GetMimetypeDoc());

Method: FlushDoc

Synopsis
stream FlushDoc (void)
Description
Return the OpenOffice document binary content to STDOUT
Parameter
none
Return value
stream : the OpenOffice document binary content
Note
This function can not be called statically.
Example
header('Content-type: '.$OOo->GetMimetypeDoc());
header('Content-Length: '.filesize($OOo->GetPathnameDoc()));
$OOo->FlushDoc();

Method: RemoveDoc

Synopsis
void RemoveDoc (void)
Description
Unlink the new OpenOffice document
Parameter
none
Return value
none
Note
This function can not be called statically.
Example
$OOo->RemoveDoc();
or
header('Content-type: '.$OOo->GetMimetypeDoc());
header('Content-Length: '.filesize($OOo->GetPathnameDoc()));
$OOo->FlushDoc();
$OOo->RemoveDoc();

Method: ClearProcessDir

Synopsis
void ClearProcessDir ([int $hour=2 [, int $minut=0]])
Description
This method is useful to remove all files from the process directory older than now minus hours and minuts.
Don't use this method if you use a system directory like /tmp or c:/windows/temp.
Parameter
int $hour : the number of hours, default 2
int $minut : the number of minuts default 0
Return value
none
Note
This function can not be called statically.
Example
$OOo->ClearProcessDir(); // default value
or
$OOo->ClearProcessDir(2,0); // remove file older than 2 hours
or
$OOo->ClearProcessDir(0,30); // remove file older than 30 minuts