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:
- In your document template, there must be a merge field that can be mapped to the image's URL.
- The URL data must be available for merging, either from a field in one of your objects, or from a calculated value produced in the Apsona report that feeds
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
Note that the formula relies on the
field in the report. Also note the parameter
which specifies the size of the generated QR code in pixels. If you want to change it to, say, 100x100, you would instead use
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:
mergeFieldName@IMAGE specifying a field named mergeFieldName whose contents will be replaced by the image at the corresponding URL;
mergeFieldName@IMAGE,W=nnn specifying a field named mergeFieldName whose contents will be replaced by the image at the
corresponding URL, with the produced image spanning
nnn pixels in width.
For example, the screen shot below shows two merge fields, one named
, with a requirement that should be 250 pixels wide in the generated
document, and a second named
with no width specification.
Some things to keep in mind with this method:
- If you leave out the width specification, the image shown in the document will be the same size as the original image at the URL from which it is fetched. But
if you provide a width, the height of the produced image will be correspondingly scaled to preserve the original aspect ratio of the image.
- If there is a problem with retrieving the image, e.g., the image is not found on the server, Apsona will show an error message in the generated document in place of the image,
indicating the nature of the problem.
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:
- Create a merge field, as usual.
- 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
If you like, you can download the .docx template
that produced this screen shot.
At the moment, there are a few limitations:
- This mechanism for dynamic images is only available with Microsoft Word. It is not available with either LibreOffice or Google Docs.
- PDF generation with dynamic images is supported only with documents that use Method 1 above.
- Including dynamic images in emailed documents is supported only with Method 1 above.