One of the fascinating aspects of Adobe Document Generation is how incredibly flexible it is. One aspect of the API that can enhance the final result is the ability to include images in your template. In a typical use case, you would provide a static image defined in your data used with the API. In this blog post, I will demonstrate a more advanced example — dynamically generating images, in our case, charts, on the fly.
Before we get into a more advanced demo, let’s quickly cover the basics. (My coworker has an intense look into Document Generation and images you should check out.) As our docs describe, using a dynamic image in your Word template requires a few steps.
First, you add an image to your document. It doesn’t matter what the image you pick, it’s just a placeholder, but you’ll want to place it in your document as you like and ensure you’ve sized it as expected. Once done, you right-click on the image and select the “Edit Alt Text” option. In that alt text, you supply JSON:
location-path property must point to the key-value used in your data that includes the image data. So, for example, given the above
location-path value, the data I use with the API could look like so:
As the example demonstrates, the image data must be a Base64 encoded version of the image. If you’ve never seen that before, it looks somewhat like this:
You can also use the Word Add On to insert images for you. If the sample data you added includes a Base64 value, you can select it in the Images portion of the Advanced tab.
So, you can already dynamically change the image in the final result PDF or Word document at this point. To do so, you swap out the value. Imagine you’ve got two options for an image in your document, a picture of a cat or a dog. You embed a placeholder image in the Word template and link it to a value,
pet. Before sending your template and data to the Document Generation API, you would use the correct value:
As you can see, depending on some particular boolean value, the data will either have the encoded version of the cat or dog picture. (Obviously, one is better than the other, and I’m talking about the cat.)
While this qualifies as dynamic, we can take it a step further.
Using Dynamic Images
We will create a document describing the number of cats in a shelter over the previous six months for our scenario. This data is returned from an internal reporting system and can be represented like so:
The data consists of an array of values ordered from the oldest to newest. Each item in the array has a date stamp and a numeric amount. Let’s start with a template that has a table of data.
By itself, it’s nice and straightforward and outputs cleanly. Here’s what the PDF looks like when generated:
It “works,” but a chart could make it easier to read. You could more clearly see trends over time and make better judgments based on the data provided. But how do we get a dynamic chart into the Word template?
For our demo we are going to make use of QuickChart. QuickChart is a “service wrapper” around the open source Chart.js package. It basically takes the functionality of Chart.js and lets you get static images of charts by crafting a URL. For example, consider this URL:
You can see a URL parameter defining various aspects of the chart, including the type (
bar), the labels, and the actual data. You can see the result of that here:
While the URL is a bit complex (and can be even more complex), it provides a solution to our issue. Given that we have our data from our internal AP, we must “rewrite” it in a URL that works for QuickChart.
I built that first. It takes in my ordered data to create a URL on QuickChart that uses the line graph format and specifies a specific height and width. Here’s that function:
Perhaps I would modify it here if I wanted to add more chart features, like custom colors. With that done, I added a placeholder image to my Word doc and specified the size. Ben covers this as tip #6 in his excellent article, Adobe Document Generation API: Working with Images.
One thing I would add to this recommendation is to switch Word to use pixel height and width for images instead of inches. In your Word settings, under Advanced, go to Display and enable “Show pixels for HTML features”:
We can set a specific height and width (500 by 300) for the image and center it right beneath the table with this enabled.
The alt text for the image looks like so:
As a reminder, when we pass our data to the Document Generation API, it will expect the image key to contain the Base64 data of our image. How do we do that? With another function!
urlToBase64 function does exactly what it sounds like – it hits a remote URL, gets the data, and converts it. Now we have all the parts we need, let’s look at a complete example:
Taking it from the top, I begin by specifying variables for my input, data, and output. My cat data, in this case, is a complex coded JSON file, as shown above. I then call
generateQuickChatURL with my data and assign the result to the
image value. Finally, this gets passed to a utility function (
generateFromTemplate) that uses our SDK to create the PDF. Here’s how the final PDF looks: