An oft underestimated feature of LiveDocx is support for the Microsoft Word INCLUDETEXT field type, which allows templates to be chained together into one larger template. The entire contents of the sub-templates are brought into the main template in the order in which the fields are inserted, during the merge process. The final document contains the contents of the template and all sub-templates.

To learn more about INCLUDETEXT and how to insert INCLUDETEXT fields into your template, please take a look the following articles:

• WD2000: How to Create a Long Document in Word, Section IncludeText Field

• Using IncludeText Fields – Part 1: Creating Templates

• Using IncludeText Fields – Part 2: Putting It All To Work

Zend\Service\LiveDocx\MailMerge provides two methods to control how or whether sub-templates are included in the main template.

In the default state, all templates, which are referenced in INCLUDETEXT fields are included during the merge process.

If you do not want this to be the case, the method setIgnoreSubTemplates() can be set to true. This disables the inclusion of all sub-templates during the merge process. Using the free public LiveDocx service, you cannot selectively define which templates should be included. It is an all-or-nothing approach.

The premium and licensed versions of the LiveDocx service, on the other hand, allow for more fine grained control. These versions provide the method setSubTemplateIgnoreList(), which takes an array of filenames that should not be included. This way, you can, for example, included sub-templates 2 and 5, but not 1, 3 and 4.

The methods setIgnoreSubTemplates() and setSubTemplateIgnoreList() will be part of Zend Framework 2 when it ships. The latest code updates should be merged into master on the Zend canonical repository within the next few weeks. For the time being, the code is still in my GitHub repository, in the branch livedocx-2.0.

You can clone the latest code at:
https://github.com/jonathanmaron/zf2/tree/livedocx-2.0

Take a look at the following directory for some demonstration applications that illustrate the methods setIgnoreSubTemplates() and setSubTemplateIgnoreList()

/demos/Zend/Service/LiveDocx/MailMerge/templates-ignore/

Feel free to contact me, using the comments section below, if you need any help, or notice any inconsistencies in the code.

June 10, 2011: The code updates mentioned in this post have now been merged into master on the Zend canonical repository.

You can clone the latest code at:
https://github.com/jonathanmaron/zf2/tree/livedocx-2.0

What’s new in this version?

• Exception handling has been migrated to ZF2 practices i.e. Exception/RuntimeException and Exception/InvalidArgumentException.

• Exceptions from the backend service now contain only the message from the backend service. The backend engineers requested this be the case, as it aides support cases.

• The inline documentation has been updated.

• The methods logIn() and logOut() are now protected in scope.

• The methods setIsLoggedIn() and getIsLoggedIn() were added.

• The quality and coverage of unit tests have been vastly improved (63 tests, 203 assertions).

You are welcome to clone the repository and try out the new code for yourself. Feel free to contact me, using the comments section below, if you need any help, or notice any inconsistencies in the code.

June 10, 2011: The code updates mentioned in this post have now been merged into master on the Zend canonical repository.

Although the release of Zend Framework 2.0 is a long way off — currently there is no official release plan — contributors are encouraged to port their components as soon as possible.

Therefore, I am delighted to announce that you can download a version of \Zend\Service\LiveDocx, complete with the latest development version of Zend Framework 2.0 from my account at GitHub.

In particular, take a look at the shipped demo applications, in the directory /demos/Zend/Service/LiveDocx. They illustrate how to use all parts of the framework and offer a good introduction to the usage of namespaces in PHP 5.3, if this topic is new to you.

To whet your appetite, below is the bitmaps demo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

use Zend\Date\Date;
use Zend\Service\LiveDocx\MailMerge;
 
$mailMerge = new MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('software', 'Magic Graphical Compression Suite v1.9')
          ->assign('licensee', 'Daï Lemaitre')
          ->assign('company',  'Megasoft Co-operation')
          ->assign('date',     Date::now()->toString(Date::DATE_LONG))
          ->assign('time',     Date::now()->toString(Date::TIME_LONG))
          ->assign('city',     'Lyon')
          ->assign('country',  'France');
 
$mailMerge->createDocument();
 
// Get all bitmaps
$bitmaps = $mailMerge->getAllBitmaps(100, 'png');      // zoomFactor, format
 
foreach ($bitmaps as $pageNumber => $bitmapData) {
    $filename = sprintf('document-page-%d.png', $pageNumber);
    file_put_contents($filename, $bitmapData);
}
 
unset($mailMerge);

Note, this is development code and should not yet be used in production applications.

Alessandro Nuzzo has just published a great introduction about Zend_Service_LiveDocx. If you are able to read Italian take a look at the following:

Mi capita spesso di dover generare dinamicamente dei file PDF o DOC. Alla ricerca di una soluzione che mi facilitasse il lavoro mi sono imbattuto in LiveDocx, un servizio basato su SOAP che permette di generare dei documenti partendo da dei template creati con un word processor. Solitamente quando devo generare dei PDF utilizzo 2 approcci: o l’”HTML-to-PDF Approach” oppure il “Programmatic Approach”.

Continue reading:

• LiveDocx: template based document generation

Download Zend Framework 1.10.0 Full and read the updated documentation on ZendFramework.com.

You can find Zend_Service_LiveDocx_* at the following locations in the distribution tree:

Source code

/library/Zend/Service/LiveDocx.php
/library/Zend/Service/LiveDocx/MailMerge.php
/library/Zend/Service/LiveDocx/Exception.php

Unit tests

/tests/Zend/Service/LiveDocx/LiveDocxTest.php
/tests/Zend/Service/LiveDocx/MailMergeTest.php
/tests/Zend/Service/LiveDocx/MailMerge/*

Demonstration applications

/demos/Zend/Service/LiveDocx/*

I really recommend taking a look at the demonstration applications, as they illustrate all of Zend_Service_LiveDocx functionality.

You can check that your server environment is set up correctly to run Zend_Service_LiveDocx, by executing check-environment.php in the directory /demos/Zend/Service/LiveDocx/.

I would like to thank Matthew Weier O’Phinney, Zend Framework Project Lead and all other members of the Zend Framework community, who have contributed to Zend_Service_LiveDocx.

As of the first alpha version of Zend Framework 1.10, the functionality of Tis_Service_LiveDocx is available directly in the Zend Framework in Zend_Service_LiveDocx.

As of today, the use of Tis_Service_LiveDocx is deprecated. Instead use Zend_Service_LiveDocx.

With the exception of the constructor, the API of Zend_Service_LiveDocx is 100% backward compatible to that of Tis_Service_LiveDocx.

At the wish of the Zend Framework community, the constructor was updated from:

1
2

// deprecated - do not use
$mailMerge = new Tis_Service_LiveDocx_MailMerge('myUsername', 'myPassword');

to:

1
2
3
4
5
6
7
8
9
10
11
12
13

// correct - do use
$mailMerge = new Zend_Service_LiveDocx_MailMerge(
    array (
        'username' => 'myUsername',
        'password' => 'myPassword'
    )
);
 
// alternatively
$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');

I would encourage you to update your projects to use the Zend_Service_LiveDocx family of classes.

If you need any assistance in migrating your code, please post a support request into the support forum.

Please go to the download section of ZendFramework.com and download Zend Framework 1.10.0 Beta 1 Full.

The paths to the demonstration applications and documentation remain the same as listed in the previous post.

Please go to the download section of ZendFramework.com and download Zend Framework 1.10.0 Alpha Full.

The paths to the demonstration applications and documentation remain the same as listed in the previous post.

Using Subversion (SVN) you can anonymously checkout the Standard Trunk repository:

svn checkout http://framework.zend.com/svn/framework/standard/trunk/ ./

You can find Zend_Service_LiveDocx_* at the following locations:

Source code

/library/Zend/Service/LiveDocx.php
/library/Zend/Service/LiveDocx/MailMerge.php
/library/Zend/Service/LiveDocx/Exception.php

Unit tests

/tests/Zend/Service/LiveDocx/LiveDocxTest.php
/tests/Zend/Service/LiveDocx/MailMergeTest.php
/tests/Zend/Service/LiveDocx/MailMerge/*

End-User documentation (as raw XML)

/documentation/manual/en/module_specs/Zend_Service_LiveDocx.xml
/documentation/manual/en/figures/zend.service.livedocx.*

Demonstration applications

/demos/Zend/Service/LiveDocx/*

Learn more about the Zend Framework repository in the official wiki.

I would like to thank Matthew Weier O’Phinney, Zend Framework Project Lead for promoting Zend_Service_LiveDocx to the Standard Trunk repository.

The next and final step will be Zend_Service_LiveDocx becoming part of the Zend Framework 1.10 distribution file.

LiveDocx is the tool of choice for the invoice generation process. But how do you efficiently get a printed copy of the invoices to the customer? One way would be to concatenate all the created invoices into one massive PDF file and then dispatch this PDF file to the printers.

Backend concatenation

As of LiveDocx 1.2, it has been possible to assign multiple records in the form of a nested associative array to a template. The result is one concatenated document, containing the populated template (one per nested sub-array).

This backend concatenation approach is a fantastic way to create hundreds of documents in one run, but in the case that your application demands thousands or even tens of thousands of documents, the amount of data that has be transfered via SOAP in one request does get extremely large and depending upon your Internet connection, can become a little slow and consequently burdensome.

This blog post offers a new approach to generate documents using LiveDocx on the backend, but perform the concatenation locally. The following screenshot illustrates the sample application in action (click to zoom):

The code has been written for the official Zend_Service_LiveDocx_MailMerge component, which is currently in the Standard Trunk. By modifying the constructor, however, you can easily make it work with Tis_Service_Service_MailMerge.

Generate remotely, concatenate locally

In the sample application, documents are created by the backend LiveDocx server and concatenated locally, using either pdftk or Ghostscript in the function concatenatePdfFilenames(). This approach has the advantage that only the singular documents are transfered from the backend LiveDocx service via SOAP to the server and not the entire concatenated document, which theoretically can be many gigabytes in size. The disadvantage, of course, is that one or these tools must be installed on the local server. However, as both are open source and available for Windows and Linux, this should not pose such a problem. Often they will already be installed on your server.

If both pdftk and Ghostscript are available, it is recommended to use pdftk, as it is considerably faster and uses less memory. Ghostscript, on the other hand, generates slightly small PDF files.

Try it out yourself

The source code to this sample application is located at /demos/Zend/Service/LiveDocx/MailMerge/license-agreement/generate-document-concat.php of the Standard Trunk. Simply checkout the entire repository or update your local working copy. If you are just curious about what the code looks like, you can view the source code here: generate-document-concat.php.

If you have any questions about this local concatenation approach, please post into the comments below.