The final step of the tutorial is not directly relevant to this blog, but the first two steps are. To see some PHP code that illustrates how to populate templates with LiveDocx, using the Zend Framework, please take a look at this article: Brief introduction to LiveDocx in PHP.

If you have any questions about the video or need help using LiveDocx, please do not hesitate to use the comment section below.

Thank you Björn for a very easy-to-follow video tutorial.

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.

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.

Consider the following example (discussion under the code):

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

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('license-agreement.doc');
 
$mailMerge->assign(null);  // must be called as of phpLiveDocx 1.2
 
$mailMerge->createDocument();
 
$data = $mailMerge->retrieveDocument('html');
 
file_put_contents('./license-agreement.htm', $data);

We specify the document we want to to convert and then simply retrieve the document in the required format – XHTML in this case.

Please download the source document and converted document and take a look at the source code of the created HTML file.

You will see that the logo at the top left of the page is not linked in, as you may expect, but has been embedded in the HTML file, using the data URI scheme method. The markup to look out for is as follows:

1
2
3
4
5
6

<img src="data:image/png;base64,
iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGPC/xhBQAAAAlwSFlz
AAALEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IAAAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3
aXRoIFRoZSBHSU1Q72QlbgAAAF1JREFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1e
xdlYvBBeZ7jqch9//q1uH4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0vr4M
khoXe0rZigAAAABJRU5ErkJggg==" alt="" />

The main advantage of this embedded approach is that a request is not required to download the image file; hence, it is easier to share the document around, in particular, if the recipient is not connected to a network when viewing the file.

The Wikipedia article offers a detailed discussion on the advantages and disadvantages of the data URI scheme approach.

Sound complicated? It is not!

First of all, download append-template.docx. Then run the following code. The result is one file append-document.pdf, which contains 4 pages. Once page per set of data.

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
30
31
32
33
34
35
36
37

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('./append-template.docx');
 
$fieldValues = array (
    // set 1
    array (
        'software' => 'Magic Graphical Compression Suite v2.5',
        'name'     => 'Henry Richards'
    ),
    // set 2
    array (
        'software' => 'Magic CAD Suite v1.9',
        'name'     => 'Brüno Cassidy'
    ),
    // set 3
    array (
        'software' => 'Super Ray Tracer 19.2',
        'name'     => 'Paul Roberts'
    ),
    // set 4
    array (
        'software' => 'Random File Downloader 0.1a',
        'name'     => 'Kay Sandler'
    )                    
);
 
$mailMerge->assign($fieldValues);
 
$mailMerge->createDocument();
 
$data = $mailMerge->retrieveDocument('pdf');
 
file_put_contents('./append-document.pdf', $data);

This is a very simple sample, with a very simple template. However, this functionality is especially useful for scenarios, such as label printing and voucher or certificate creation.

If you need any help, please do not hesitate to post into the support forum.

In addition to the supported document file formats, phpLiveDocx 1.2 can now save documents as BMP, GIF, JPG, PNG and TIFF.

In the latest distribution file, in the directory /samples/mail-merge/bitmaps, you will find the following sample. The new methods to look out for are getAllBitmaps($zoomFactor, $format) and getBitmaps($fromPage, $toPage, $zoomFactor, $format).

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

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('software', 'Magic Graphical Compression Suite v1.9')
          ->assign('licensee', 'Henry Döner-Meyer')
          ->assign('company',  'Co-Operation')
          ->assign('date',     'January 11, 2010')
          ->assign('time',     'January 11, 2010')
          ->assign('city',     'Berlin')
          ->assign('country',  'Germany');
 
$mailMerge->createDocument();
 
// Get all bitmaps
$bitmaps = $mailMerge->getAllBitmaps(100, 'png');      // zoomFactor, format
 
// Get just bitmaps in specified range
//$bitmaps = $mailMerge->getBitmaps(2, 2, 100, 'png');   // fromPage, toPage, zoomFactor, format
 
foreach ($bitmaps as $pageNumber => $bitmapData) {
    $filename = sprintf('documentPage%d.png', $pageNumber);
    file_put_contents($filename, $bitmapData);
}
 
unset($mailMerge);

This produces the following two files (documentPage1.png and documentPage2.png) and writes them to disk in the same directory as the executable PHP code (click to enlarge):

To try this out for yourself, you will need to update to phplivedocx-1.2-20090810 or newer.

Yes. Indeed, it is.

I have just published a couple of sample applications and a brief article, which show how:

• Using phpLiveDocx without the Zend Framework

To better debug such issues, we have just released a script which can be run from the command line to check that a server environment is compatible to LiveDocx.

The script check-environment.php is contained in the directory /demos/Zend/Service/LiveDocx/.

In the case that your environment is compatible to LiveDocx, you will see the following:

LiveDocx Environment Checker
 
 1: Checking OS (Linux)..................................................PASS
 2: Checking SAPI (cli)..................................................PASS
 3: Checking PHP version (5.2.9).........................................PASS
 4: Checking HTTP stream wrapper.........................................PASS
 5: Checking HTTPS stream wrapper........................................PASS
 6: Checking Zend Framework path.........................................PASS
 7: Checking Zend Framework version (1.9.0)..............................PASS
 8: Checking SOAP extension..............................................PASS
 9: Checking DOM extension...............................................PASS
10: Checking SimpleXML extension.........................................PASS
11: Checking libXML extension............................................PASS
12: Checking your IP address (xxx.xxx.xxx.xxx)...........................PASS
13: Checking your city (Berlin)..........................................PASS
14: Checking your region (Berlin)........................................PASS
15: Checking your country (Germany)......................................PASS
16: Checking backend WSDL (0.843467950821s)..............................PASS
17: Checking backend credentials are defined.............................PASS
18: Instantiating Zend_Service_LiveDocx_MailMerge object (1.14s).........PASS
 
Congratulations! All tests passed. The server environment, in which this script
is running, is suitable for LiveDocx.

In the case that you do not have the Zend Framework correctly installed, you will see the following:

LiveDocx Environment Checker
 
 1: Checking OS (Linux)..................................................PASS
 2: Checking SAPI (cli)..................................................PASS
 3: Checking PHP version (5.2.9).........................................PASS
 4: Checking HTTP stream wrapper.........................................PASS
 5: Checking HTTPS stream wrapper........................................PASS
 6: Checking Zend Framework path.........................................FAIL
 
[...]

In the case that your username and/or password to LiveDocx is invalid, you will see the following:

LiveDocx Environment Checker
 
 1: Checking OS (Linux)..................................................PASS
 2: Checking SAPI (cli)..................................................PASS
 3: Checking PHP version (5.2.9).........................................PASS
 4: Checking HTTP stream wrapper.........................................PASS
 5: Checking HTTPS stream wrapper........................................PASS
 6: Checking Zend Framework path.........................................PASS
 7: Checking Zend Framework version (1.9.0)..............................PASS
 8: Checking SOAP extension..............................................PASS
 9: Checking DOM extension...............................................PASS
10: Checking SimpleXML extension.........................................PASS
11: Checking libXML extension............................................PASS
12: Checking your IP address (xxx.xxx.xxx.xxx)...........................PASS
13: Checking your city (Berlin)..........................................PASS
14: Checking your region (Berlin)........................................PASS
15: Checking your country (Germany)......................................PASS
16: Checking backend WSDL (1.38575911522s)...............................PASS
17: Checking backend credentials are defined.............................PASS
18: Instantiating Zend_Service_LiveDocx_MailMerge object (-1s)...........FAIL
 
One or more tests failed. The web server environment, in which this script is
running, does not meet the requirements for LiveDocx.

If you are having trouble getting started with LiveDocx, I would suggest you download the latest Zend Framework and try out the check-environment.php script.

All end-users have to do, is copy the documents they wish to convert into a specific network directory (aka Hot Folder) and the files are converted in a matter of minutes into the desired format. End-users can than pick up the converted documents and process them further, send them via e-mail or to the printer.

Consider the following screenshot of a typical Windows desktop (click to enlarge). The top window is the directory, which contains the files to convert. Once they have been converted the files are moved into the middle directory. The actual converted files are saved in the bottom window.

Supported file formats

The following input file formats are supported:

• DOCX – Office Open XML Format
• DOC – Microsoft Word DOC Format
• RTF – Rich Text File Format
• TXD – TX Text Control Format

The following output file formats are supported:

• DOCX – Office Open XML Format
• DOC – Microsoft Word DOC Format
• HTML – XHTML 1.0 Transitional Format
• RTF – Rich Text File Format
• PDF – Acrobat Portable Document Format
• TXD – TX Text Control Format
• TXT – ANSI Plain Text

Getting started

Download the current phpLiveDocx distribution file and unzip or untar the archive to your local file system. This sample application is contained in the /samples/mail-merge/convert-batch/ directory. If you are using phpLiveDocx for the first time, please review the Getting Started Guide.

Copy the files you want to convert into the directory queue. For your convenience, there is already a number of demonstration files in this directory.

Run the run-job.php script with the file format into which you wish to convert your documents. For example:

./run-job.php --output-format pdf

And sit back! phpLiveDocx will convert your documents.

The converted documents (i.e. the PDF versions in the above example) will be placed in the directory output.

The original document will be moved to the directory queue_done.

To get a list of supported output file formats from the command line, simply call run-job.php with no parameters:

./run-job.php

Automation with cron

If you are running Linux on your server, you can call the run-job.php script every n minutes to fully automate the task of converting documents.

If you set it up like this, all you have to do is copy the files you want to convert into the queue directory and wait for a maximum of n minutes.

Once the next cron job has been called, the documents will be converted into the desired format in the output directory.

To do this, fire up your crontab editor:

crontab -e

And add the following line to call run-job.php every 5 minutes:

*/5 * * * * cd [PATH]/phplivedocx/samples/mail-merge/convert-batch && ./run-job.php --output-format pdf | mail -a "From: [FROM_EMAIL]" -s "phpLiveDocx Batch Converter" [TO_EMAIL]

Replacing the placeholders (strings between [ and ]) with…

1. [PATH] with the path to the phpLiveDocx sample application.
2. [FROM_EMAIL] with the e-mail FROM which the cron job confirmation should be sent.
3. [TO_EMAIL] with the e-mail TO which the cron job confirmation should be sent.

cron will then execute run-job.php every five minutes and in addition sent you an e-mail report of the batch convert job to the specified e-mail address.

The final step to allow the situation, as shown in the above screenshot, is to share the three directories queue, queue_done and output with Windows clients. This can be done via Samba or any other network file system supported by Windows and/or Mac. Once the shares are in place, shortcuts to the appropriate network directories can be added to the desktop (illustrated in the right half of the screenshot).

Need help?

If you need help, please post your questions and/or comments below or in the support forum and I will assist as much as I can.