Formatting Tips and Tricks for Adobe Document Generation API

I’ve been having a fun time playing around with our Adobe Document Generation API service. It provides an easy-to-use API for generating PDFs and Microsoft Word docs based on a template and your data. Today, I will give you a deep dive into another topic — formatting.

When I talk about formatting, I’m talking about ways to display excellent information in your documents. Imagine for a moment the following text in your Microsoft Word document:

Sales for cat toys and treats over the past year were ${{ salesTotal }}. 

Now imagine the data sent to our Document Generation API included this value:

{
    // other stuff would be here of course...
    "salesTotal":45309435
}

The end result would look like so:

Sales for cat toys and treats over the past year were $45309435.

That’s readable, but wouldn’t it be nicer if it displayed like so?

Sales for cat toys and treats over the past year were $45,309,435.

The addition of the commas makes it easier to read and drives home just how popular cat toys are, especially when most cats ignore the toy and play with the box it came in instead.

Here’s where JSONata begins to shine. By making usingwerful and flexible functions, we can take our data and reshape it to make it better for our readers. Let’s dive in and look at some examples.

Doing It Yourself

So, while this article's meat is about using JSONata formatting functions, don’t forget that the Document Generation API takes whatever data you throw at it. Going back to our example above, I could solve the problem by simply formatting my data before passing it to the API. For example, this could be done in Node.js:

let data = {
    "salesTotal":45309435
}

data.salesTotal = new Intl.NumberFormat().format(data.salesTotal);

This uses the Intl object, which supports various types of locale-specific formatting.

I mention this because while JSONata is powerful, it may not be able to support every possible use case. Also, it’s a good reminder that before you pass your data to the Document Generation API, you have multiple opportunities to shape and manipulate that data!

Working With Strings

Let’s begin by looking at string manipulation functions. One of the first valuable features you may like is the ability to transform a string into upper or lowercase. Here’s an example:

Upper case: {{ $uppercase(name) }}
Lower case: {{ $lowercase(name) }}

Given the name “Raymond Camden” you get “RAYMOND CAMDEN” and “raymond camden”.

Another useful function is $trim. This function will remove leading and trailing spaces, convert line breaks to spaces, and convert multiple spaces inside a value to one space. Consider this input value:

"longtext":"   This is some long text that will have some line \n\n breaks in it. It's totally interesting.  "

Now let’s include it in our Word doc as is and with $trim:

Trim test: {{ longtext }} End of long text.
Trim test: {{ $trim(longtext) }} End of long text.

The result looks like so:

Notice that even without trim, the line breaks were replaced by spaces. With the trim, look at how much cleaner the display is. Let’s look at another example — $pad. The $pad function will add characters to the beginning or end of a string to match a certain length. So, for example, if we have the last four digits of a credit card number, we may want to display it with a pad of pound signs in front. Given this input:

"ccnum":"1234"

We can create a padded version of it like so:

{{ $pad(ccnum, -12, '#') }}

The function takes three arguments. The first is the string to pad. The next is the number of characters. Positive numbers mean that the pad will be added to the end, and negative numbers mean the front. Finally, we pass in character to use for padding. Here’s the output:

########1234

For a final example, consider an array of data:

"cats": [
    "Luna", "Pig", "Cracker", "Elise", "Sammy"
]

What if you could print these values as one string of names, separated by a comma? The $join function makes this easy:

{{ $join(cats,", ") }}

The function takes an array and a string to join them together. The result is what you would expect:

Luna, Pig, Cracker, Elise, Sammy

Before looking at numerical formatting, a quick note, all of these string functions take strings as arguments. That makes sense; probably, I made a little mistake during my testing. When I first tried to use $pad, I used this input:

"ccnum":1234

You’ll notice that I don’t have quotes around the value since it was a number. When I tried this, the service rightly noticed the issue and threw an error. If you are curious, this is an example of how our SDK will return that error:

Unsupported expression in the document template:Argument 1 of function $pad does not match function signature;

When I saw that, I realized that it was complaining about me passing a number, and not a string, to the function. I fixed it by changing my data, but what if I didn’t want to? It turns out there is a $string function that will fix it for me:

{{ $pad($string(ccnum), -12, '#') }}

Want to see more? Check out the complete list of string functions: http://docs.jsonata.org/string-functions.

Working With Numbers

Now that we’ve played with strings let's look at things we may do with numbers. The first can help make floating-point numbers easier to read. Given a number:

"totalIncome":234.63

You can round the number down using $floor, round the number up using $ceil (short for ceiling), or round “properly” such that anything below .5 goes down and everything else rounds up. (And yes, these functions do the right things for negative numbers.)

Here’s my test input:

Floor: {{ $floor(totalIncome) }}
Ceil: {{ $ceil(totalIncome) }}
Round: {{ $round(totalIncome) }}

And the output:

Floor: 234
Ceil: 235
Round: 235

The most interesting numeric function, at least when it comes to formatting, is $formatNumber. $formatNumber lets you apply a “mask” to numbers. This can be used to add commas to a large number. It can be used to round to a certain number of decimal places. Let’s consider two examples. First, our input values:

"salesTotal":45309435,
"incomeTotal":3248923498.31

The first value represents the total number of items sold and is a whole number. The second value represents monetary income and has decimal places. We can format both using the following:

Format Number: {{ $formatNumber(salesTotal, '#,###') }}
Format Number (with decimal): {{ $formatNumber(incomeTotal, '#,###.00') }}

Notice the difference in masks. This is another example of knowing my data, what is expected, and using the proper formatting. Here’s the output:

Format Number: 45,309,435
Format Number (with decimal): 3,248,923,498.31

As a quick aside, like $string will convert numeric values to strings, you can use $number to go from strings to numerical data. For more, see the numeric functions docs: http://docs.jsonata.org/numeric-functions#number.

Try It Yourself

Want to give it a shot yourself? Sign up for a free trial, and then check out both our docs and the docs over at JSONata. If you have any questions, ask on our forum. We’re here to help!