Contact us Blog

Generating Word documents with dynamic images

Overview

The material below assumes that you are familiar with the process for generating Word documents using Apsona's Document Generator.

Apsona's Word document generator lets you include images and graphics directly in your Word template, and those images will appear as positioned in the output Word document. These are examples of static images, in the sense that the images are wired into the template so that the same images appear in all the documents produced by the generator.

But there are many situations where you would want to generate a Word document containing images produced dynamically, e.g., from a web URL. For example, when conducting an event that will host a number of attendees, you might need to generate a sign-up sheet for the event, containing the name, phone, email address and a QR code for each attendee. Whilst the name and email address are text fields, the QR code is a dynamically-generated image that encodes the information you specify. A similar example involves including, for each attendee, a profile picture that is available at a URL for that attendee.

To generate a document that contains dynamically-generated images such as in the above example, you will need two things:

An example report for generating QR codes

Once you have produced the merge document, you can use a report as data source for the merge. In this example, we'll use a report that includes a calculated field, shown in the screen shot below. This calculated field produces the URL for the QR code for the record ID of the contact, using the Google Charts QR code generator. Below is the formula it uses:
"https://chart.googleapis.com/chart?cht=qr&chs=150x150&choe=UTF-8&chld=L|2&chl=" +
      {!Contact ID}
Note that the formula relies on the Contact ID field in the report. Also note the parameter chs=150x150 which specifies the size of the generated QR code in pixels. If you want to change it to, say, 100x100, you would instead use chs=100x100.

Creating an image merge field

There are two alternative ways to create a merge field for an image. The first is the preferred way, and the second - the one that uses INCLUDEPICTURE - is the older technique that is retained for backward compatibility.

Method 1: The IMAGE specifier

With this method, the merge field for an image can be written either with or without a required width specification, as below: For example, the screen shot below shows two merge fields, one named Photo, with a requirement that should be 250 pixels wide in the generated document, and a second named Photo2 with no width specification. Some things to keep in mind with this method:

Method 2: the INCLUDEPICTURE tag

This is the older technique for creating merge fields, and in some ways is less reliable because Word sometimes refuses to update the generated document correctly. In general, we suggest the use of Method 1 above for most use cases.

Ordinarily, to create a merge field, you simply use Insert - Quick parts - Field in Word, or use a macro, as described elsewhere in our documentation. But with the INCLUDEPICTURE method, for an image URL, there are a few additional steps to take. Essentially you will do the following:
  1. Create a merge field, as usual.
  2. Open the merge field's contents and add an INCLUDEPICTURE tag in Word. You do this by
    • toggling the field code;
    • typing Ctrl-F9 to add an extra pair of braces;
    • moving the MERGEFIELD tag into the newly generated braces; and finally
    • adding the INCLUDEPICTURE tag.
The process is much easier to understand by watching this demo .

Printing the generated document

A key advantage of Method 1 above is that the images are included as part of the generated document, with no additional steps needed on your part. You can also generate PDF documents using the technique of Method 1.

But method 2 (the older INCLUDEPICTURE method) has some disadvantages in this regard. Once you have generated the merged document and downloaded it, you will need to tell Word to update all the images in the document before it can be printed. You can do this by pressing Ctrl-A (select all), followed by F9 (update all fields). You will then see a ready-to-print document, part of which might look like the screen shot below.

If you like, you can download the .docx template that produced this screen shot.

Limitations

At the moment, there are a few limitations: