Creating Your Own Schema With the Adobe Document Generation Word Add-in
Learn about the updates to Adobe Document Generation API to make it simpler to use.
Join the DZone community and get the full member experience.Join For Free
When Document Generation API launched a few months ago, we included a Microsoft Word add-in to make it simpler for folks to design their Word templates for use within the API. In order to use the add-in, you needed to provide data in JSON format, either pasted in or uploaded via an existing file:
This worked perfectly fine if you had your data ready to go, but that wouldn’t always be possible, especially if you’re starting on a new project and need to quickly start prototyping. Luckily, our latest update adds a few features to make this much simpler. Let’s take a quick look at what’s changed. Note — for folks who’ve already installed the Word add-in, it should update automatically for you. If you haven’t installed this add-in yet, head over to our documentation for instructions on how to do it. Also, read my introduction to Document Generation API if you’ve not had a chance to try it yourself yet.
Creating Your Own Data
The first change you’ll notice is right beneath the interface shown above, a new button that lets you continue without pasting or uploading:
If you select this, you’ll get a new button in the traditional tag editing user interface named “Create Tag”:
Selecting this will open a new dialog that prompts you for the type of data you want to create. You’ll be asked to provide a name, a category, and a type:
Let’s consider the types first. For the most part, this should be self-explanatory, but some things should be clarified. As developers, we’re used to seeing “string” as a way to define text, but non-technical users may want to keep in mind that it’s just a fancy way of saying simple text. If your data represents a person’s name, you would select this.
“Number” would be used for numerical information. Keep in mind this includes numbers with decimals and negative numbers.
“Boolean” is a way of saying something that is either true or false. An example here could be a tag that represents if someone is in management or not.
Finally, “Object” would be how you would create nested data. A good example of this would be addressed. An address consists of multiple parts all grouped together. When you select this type, you’ll get an additional place to enter values beneath it.
After you’ve created a few tags, you can then use them as if you had uploaded or pasted in data manually.
Going back to the Create Tag dialog, the category drop-down is what you would use when building more advanced types of values. So for example, selecting Image will create a tag that when inserted, will be an image. The add-in creates a very simple default image. Here’s how you create it:
And here’s how it will look in your Word template:
Notice I’m in the “Advanced” tab of the interface here. That’s where image tags will show up.
The category drop-down is also where you can create tables and lists. For tables, you’ll be prompted to enter columns and types:
There’s a similar experience for building out lists.
Testing Your Data
Once you’ve set up your tags, you can start designing your template and inserting the tags as normal. Here’s an example where I used all of my creativity (I’m quite proud of it):
Now it’s time to introduce another, incredibly cool feature in the latest update. Did you notice the “Generate document” button in the last screenshot? If not, here’s a close up:
If you have an account with us already and have credentials for the API, you can now generate your document directly RIGHT THEREFROM WORD! Sorry for all caps. I write code every day. I love writing code. But this one little button here is so darn useful I’m absolutely fine with it letting me skip code. Obviously, it’s just for testing, but it makes iterating on your designs that much quicker. After you’ve provided your credentials, when you hit the button you’ll see your tags now rendered in JSON, letting you change things if you want:
After hitting continue, the add-in will take the data and your Word document and do its magic:
If you hit the view button, you’ll be sent to an online version of the generated PDF:
What’s cool is that you can go back to Word, keep working, and then preview again and again until you get it right. As I said, the data is editable so you can also do things like changing the value of Booleans to see how conditional blocks output in different cases. It’s all quick and easy and just a huge improvement to the process as a whole.
If you still haven’t had a chance yet to play with Document Generation, then there’s no time like the present. We also recently launched an interactive web-based demo of the feature as yet another way to make it easy to learn how the API works.
Published at DZone with permission of Raymond Camden, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.