NAME

OOTemplate - perl module for merging .odt files with data.

SYNOPSIS

use OOTemplate;

my $oodoc = new OOTemplate( 'letter.odt' );

$oodoc->setFieldData("company_name", "Acme Widgets");
$oodoc->setFieldData("saluation", "Dear Mr. Coyote");

$oodoc->setTableData("items", { qty => 1, product => "Anvil"},
                     "items", { qty => 12, product => "Bandages"}
                    );

$oodoc->setStylesFieldData("No returns without prior authorization");

$oodoc->finalize;

$oodoc->save("merged-letter.odt");

DESCRIPTION

Perl class for merging data with Open Office documents. Uses the OpenOffice::OODoc::Document class to read and manipulate documents, substituting data for pre-defined fields in the document.

HOW IT WORKS

Create an Open Office Writer template

Create an OO document that contains user defined fields. The fields define places where you would want to insert dynamic data elements.
Merge the data with the Writer template

Use this class to merge data elements with the document.

CONSTRUCTOR

my $document = OOTemplate->new( document-template-name );

Creates a new OOTemplate document instance. document-template-name is the fully qualified path name of an Open Office Writer file.

METHODS

OOTemplate inherits from OpenOffice::OODoc::Document

filename

filename()

This method returns the filename of the .odt template.

finalize

finalize()

Performs the substitutions in the template using the data previously set using setFieldData, setStylesFieldData, setTableData or setStylesTableData and prepares the document for saving.

clearFieldValues

clearFieldValues()

Clear all user-defined fields from document. You might want to do this if you populated the template with placeholders.

save

save( filename )

Saves the merged document using the specified filename.

setFieldData

setFieldData( field-name, value, ... )

setTableData

setTableData( table-name, { field-name => value, ...}, ... )

setStylesFieldData

setStylesFieldData( field-name, value, ... )

setStylesTableData

setStylesTableData( table-name, { field-name => value, ...}, ... )

setTableFields

setTableFields( table-name, options )

setStylesTableFields

setStylesTableFields( table-name, options )

These methods are only used when dynamically setting data elements.

Sets each field of of a table to a value.

$doc->setTableFields("tbl_Table1",
                     name => 'William Smith', title => 'President'
                    );

TIPS AND TRICKS

Multi-Page Documents

There are times when you might want to create a multi-page document using the same template with each page containing different data. You accomplish this by appending content to the initial page.

$oodoc = new OOTemplate( 'template.odt' );

$oodoc->setFieldData('field1' => 'some value');
....

$oodoc->finalize;

$doc2 = new OOTemplate( 'template.odt' );
$doc2->setFieldData('field1' => 'some other value');
....
$doc2->finalize;

$oodoc->addPagebreak( $doc2 );
$oodoc->appendContent( $doc2 );
$oodoc->save();

Multi-Row Tables

Adding rows to a table is actually accomplished by adding (cloning) the tables you've defined in the document. Thus, you simply set data for the same table name over and over for each row of the table.

$oodoc->setTableData('Table1', { col1 => 'foo', col2 => 'bar' },
                     'Table1', { col1 => 'boo', col2 => 'buz' }
                    );

The rows will appear in the order that you specify them.

Setting User-Defined Fields in Headers/Footers

Headers and footers in OO documents are actually implemented as styles. Under the covers, styles are stored in a separate XML document embedded in the .odt file.

When you add user defined fields to headers and footers you need to use setStylesFieldData and setStylesTableData in order to set the value of those fields.

Suppose you have defined a user defined field in the header of the document doc_number_header and again in the footer as doc_number_footer.

$oodoc->setStylesFieldData(doc_number_header => $document_number,
                           doc_number_footer => $document_number
                          );