I implemented a Zend Framework 2.0 version of \Zend\Service\LiveDocx\MailMerge in June and have just added LiveDocx 2.0 functionality today.

You can download the latest version of Zend Framework 2.0, including LiveDocx 2.0 functionality, tests and demonstration applications from my GitHub.

Take a look at the following directory for a large number of demonstration applications that illustrate all LiveDocx functionality:

/demos/Zend/Service/LiveDocx/

I have sent a pull request to the Zend Framework guys, so you can expect the new code to be included in the main GIT repository shortly.

Below is the Zend Framework 2.0 version of the sample application that I posted last week:

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

use Zend\Date\Date;
use Zend\Service\LiveDocx\MailMerge;
 
$mailMerge = new MailMerge();
 
$mailMerge->setUsername('username')
          ->setPassword('password');
 
$photoFilename = 'dailemaitre.jpg';
 
if (!$mailMerge->imageExists($photoFilename)) {
    $mailMerge->uploadImage($photoFilename);
}
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('name',        'Daï Lemaitre')
          ->assign('company',     'Megasoft Co-operation')
          ->assign('date',        Date::now()->toString(Date::DATE_LONG))
          ->assign('image:photo', $photoFilename);
 
$mailMerge->createDocument();
 
$document = $mailMerge->retrieveDocument('pdf');
 
file_put_contents('document.pdf', $document);
 
$mailMerge->deleteImage($photoFilename);
 
unset($mailMerge);

getImageImportFormats()
Returns an array of supported image formats from which can be imported (lowercase).

getImageExportFormats()
Returns as array of supported image formats to which can be exported (lowercase).

uploadImage($filename)
Uploads an image file to your account on the LiveDocx backend service.

downloadImage($filename)
Downloads an image file from your account on the LiveDocx backend service.

listImages()
Returns an array of all images that are stored on the LiveDocx backend service.

deleteImage($filename)
Deletes an image file from the LiveDocx backend service.

imageExists($filename)
Checks whether an image file is available on the LiveDocx backend service.

If you are familiar with the Zend_Service_LiveDocx_MailMerge API, you will notice that these methods an very similar to the template handling methods.

The version of Zend_Service_LiveDocx_MailMerge that contains image merging will be released with the next Zend Framework release. For the time being, it is part of the Standard Trunk and can be checked out via SVN.

If you wish to try out the above methods, take a look at the following sample applications:

/demos/Zend/Service/LiveDocx/MailMerge/images/

Image merging is useful, for example, in the case of a badge application for a conference. In addition to a name, company name and date that should appear on the badge, it is possible to insert a photo of the delegate, using the Zend Framework.

Even it is sounds a little counter-intuitive, image merging works with text fields. In fact, inserting a text field for an image is almost identical to inserting a text field for textual information. The only difference is the naming convention of the text field. Whereas, a text field for textual information can have (almost) any identifier, a text field for an image must start with image:. For example: image:photo.

For example, in the case of our badge application, we would have the following 4 fields:

The text field, into which image data will be inserted is called image:photo and can be populated just like any other text field, using the assign() method. The text fields name, company and date are normal text fields for textual information.

Before an image can be inserted, it first has to be uploaded to your account on the backend LiveDocx server. This can be achieved using the uploadImage($filename) method. We then simply reference the filename in the merge process.

The following code snippet illustrates the flow:

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

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('username')
          ->setPassword('password');
 
$photoFilename = 'dailemaitre.jpg';
 
if (!$mailMerge->imageExists($photoFilename)) {
    $mailMerge->uploadImage($photoFilename);
}
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('name',        'Daï Lemaitre')
          ->assign('company',     'Megasoft Co-operation')
          ->assign('date',        Zend_Date::now()->toString(Zend_Date::DATE_LONG))
          ->assign('image:photo', $photoFilename);
 
$mailMerge->createDocument();
 
$document = $mailMerge->retrieveDocument('pdf');
 
file_put_contents('document.pdf', $document);
 
$mailMerge->deleteImage($photoFilename);

The version of Zend_Service_LiveDocx_MailMerge that contains image merging will be released with the next Zend Framework release. For the time being, it is part of the Standard Trunk and can be checked out via SVN.

You can find the above sample application in the following directory:

/demos/Zend/Service/LiveDocx/MailMerge/conference-pass/

• Creating templates using OpenOffice.org

His tutorial is relevant to OOo 2.4, 3.0 and 3.1.

I would like to draw special attention to the last paragraph of his text.

Although the merge field names in the above template appear to be:

• LiveDocx.letter.recipient
• LiveDocx.letter.sender

i.e. with a period as path separator, they are in fact:

• LiveDocxÿletterÿrecipient
• LiveDocxÿletterÿsender

i.e. with the character  ÿ  as path separator.

When assigning data to the template, you must use the notation with  ÿ  and not a period. For example:

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

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('LiveDocxÿletterÿrecipient', 'Sam Johnson')
          ->assign('LiveDocxÿletterÿsender', 'Peter James');
 
$mailMerge->createDocument();
 
$document = $mailMerge->retrieveDocument('pdf');
 
file_put_contents('document.pdf', $document);

The method getFieldNames() correctly returns the field names with  ÿ  as path separator.

If you own a copy of TX Text Control .Net, you already have a very nifty template designer installed on your hard disk. It is called TX Template Designer and is part of the basic install package of the aforementioned software component.

To create a template in TX Text Designer, just follow these brief steps.

1. Open the TX Template Designer. The original location is at: C:Program FilesThe Imaging Source Europe GmbHTX Text Control 14.0.NETSamplesTX Template Designer. An empty document will be opened automatically.
2. Insert a MergeField into the document by choosing Insert from the Insert main menu. Additionally, some sample text could be added to the test document.
3. Click on the inserted field to open the Mini Editor dialog. This dialog can be used to rapidly step through all fields to change the names or to open the properties dialog.

   Type in the name of the field: “name”:

   

4. Select Properties… in the Mini Editor dialog or press F2 to open the appropriate properties dialog. This dialog can be used to change the format of the field. Additionally, some advanced options can be adjusted. Select the settings as shown in the screenshot below:

   

5. Repeat step 2 and 3 to insert another field and name this field “company”. Additionally, you could change the text of both fields. The finished template should now look like this:

   

Consider the following PHP5 code, which can be used to populate the template created above. Assume that the template has been saved with the filename template.docx:

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

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('name',    'Henry Anderson');
$mailMerge->assign('company', 'Flowers Direct 2000');
 
$mailMerge->createDocument();
 
$document = $mailMerge->retrieveDocument('pdf');
 
file_put_contents('document.pdf', $document);

For a discussion on the logic of this source code, please see this post.

1. Open Microsoft Word 2003 to create a new document.
2. Select Insert, Field… from the main menu to open the Field dialog box.
3. Choose the MergeField from the Mail Merge category and specify a name for the new field: name.
4. Specify the format and some field options as shown in the following screenshot:

   

5. Repeat step 2 and 3 to insert another field and name this field “company”. Additionally, you could change the text of both fields. The finished template should now look like this:

   

Consider the following PHP5 code, which can be used to populate the template created above. Assume that the template has been saved with the filename template.docx:

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

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('NAME',    'Mitchel');
$mailMerge->assign('company', 'Flowers Direct 2000');
 
$mailMerge->createDocument();
 
$document = $mailMerge->retrieveDocument('pdf');
 
file_put_contents('document.pdf', $document);

For a discussion on the logic of this source code, please see this post.

In future blog posts, we will be looking at how to create templates with Open Office and TX Template Designer.

Template

The term template is used to refer to the input file, containing formatting and text fields. You can download an example template, stored as a DOCX file.

Document

The term document is used to refer to the output file that contains the template file, populated with data – i.e. the finished document. You can download an example document, stored as a PDF file.

The resulting word processing document can be saved in any supported format.

Supported template file formats (input)

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

Supported document file formats (output)

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

Supported image file formats (output)

• BMP – Bitmap Image Format
• GIF – Graphics Interchange Format
• JPG – Joint Photographic Experts Group Format
• PNG – Portable Network Graphics Format
• TIFF – Tagged Image File Format
• WMF – Windows Meta File Format

This information is also available programmatically. This post illustrates how.

The phpLiveDocx project and the backend service LiveDocx differentiate between the terms template and document. For details, please see this post.