05
Oct
Image Merging with LiveDocx
Written by: Jonathan Maron. Stored in: LiveDocx, Templates.

One of the most commonly requested new features in LiveDocx is the ability to merge images into a template. I am very happy to announce that exactly this feature has been implemented by the backend service. I have updated Zend_Service_LiveDocx_MailMerge to include this new functionality.

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/
4 Comments

4 Responses to “Image Merging with LiveDocx”

  1. Image Handling Methods Says:
    October 6th, 2010 at 07:39

    [...] the positive feedback from the blog post yesterday, announcing image merging, I would today like to elaborate a little on the image handling [...]

  2. Image Merging with LiveDocx – ZF 2.0 version Says:
    October 12th, 2010 at 08:00

    [...] Last week, I posted a sample application that shows how to use the new image merging functionality of LiveDocx 2.0. Since then, I have received several requests for a version that uses Zend Framework 2.0. [...]

  3. sas Says:
    April 19th, 2011 at 08:31

    Hello,
    Thanks for the code sample. I would like to mention some points for clarification:

    If your photo file is not on the same path with your php file, then the uploadImage code should be written in this way:

    if (!$mailMerge->imageExists($YOUR_PHOTO_FILE_NAME)) {
    $mailMerge->uploadImage($PATH_TO_YOUR_PHOTO_FILE);
    }
    As a real world example:
    if (!$mailMerge->imageExists(‘my_photo_2.jpg’)) {
    $mailMerge->uploadImage(‘/var/www/photos/my_photo_2.jpg’);
    }
    Otherwise, you will have problems!

    Second point is that, it would be good to emphasize the “image:photo” tag.
    You can change the “photo” value to anything you like for your document as a merge field name. However, you cannot change and always use “image” tag together with the field name as long as this is an image merge field/tag.
    In other words,
    $mailMerge->assign(‘image:photo’, $photoFilename); //correct
    $mailMerge->assign(‘image:myImageFile’, $photoFilename); //correct
    $mailMerge->assign(‘image:user_photo’, $photoFilename); //correct
    $mailMerge->assign(‘image:MYLOGO’, $photoFilename); //correct
    $mailMerge->assign(‘photo’, $photoFilename); //wrong if this is an image merge field

    * “image:” tells the api that this is an image merge field.

  4. swits Says:
    May 6th, 2011 at 16:57

    HI

    I am using your code in two websites now – excellent work.

    Is there any way to control the text wrapping around an inserted image? In MS terms, I would like to use “square” rather than the default “top and bottom”

    Thanks

    Chris

Leave a Reply