Xbasic

word_template_from_sample_json Function

Syntax

DIM result AS L = word_template_from_sample_json(C json, C templateFilename)

Arguments

jsonCharacter

The sample JSON data

templateFilenameCharacter

Filename of the Word merge template document to create.

Returns

resultLogical

Returns .t. or .f. indicating whether or not the template file was created.

Description

Creates a Word template from sample JSON data.

Discussion

Example 

Assume you have the following sample JSON data in a variable called JSONData:

{
    "name":"Belinda Monat",
    "image":"http://aadocuments.s3.amazonaws.com/headshots/AllisonBerman.png",
    "children":[
        {"name":"Callie","image":"http://aadocuments.s3.amazonaws.com/headshots/NancyShmidt.png"},
        {"name":"Griffin","image":"http://aadocuments.s3.amazonaws.com/headshots/TonyJones.png"}
    ]
}

The following Xbasic can be used to create a Word template:

dim fnTemplate as c = "c:\data\wordTemplate1.docx"
dim flag as L
flag = word_template_from_sample_json(JSONdata,fnTemplate)

If you then open the template document in Word it will show as follows:

Note that all of the property name in the sample JSON data (name, image, and children) are shown as merge fields in the template document.

Since the children property name is an array, the template documents shows <<children>> and <</children>> to indicate that the children is an array.

Within the <<children>> group merge field for <<name>> and <<image>> are shown (these are the properties of each item in the children array.

images/wordmergetemplate.gif
Generated Word Template

If you then merge the JSON data into the template using the word_merge_json() function...

dim mergedFilename = "c:\data\mergedTemplate1.docx"
dim result as P
result = word_merge_json(fnTemplate, mergedFilename, JSONdata)

...the resulting Word document looks like this:

images/wordmerge3.gif
Word Template with JSON data merged into it using word_merge_json()

Notice that the image urls are just treated as data. So the merge document shows the image URLs and not the images themselves. It is likely that you might want the merge document to show the actual image and not the image URL.

In order to do this, it is necessary to modify the merge template document to add decorators to some of the merge fields to indicate that the merge fields are image references.

To add a decorator to a merge field, edit the template document in Word. Right click on a merge field. The right click menu will display the menu shown below. Select the Edit Field... menu option.

images/wordmerge30.jpg

The Edit Field window appears.

Make sure that the MergeField category is selected.

Add the decorator (image:) as a prefix to the field name.

images/wordmerge31.jpg

The image below shows how the template document appears in Word after decorators have been added to the <<image>> placeholder at the top level and the <<image>> placeholder within the <<children>> group.

images/wordmerge4.gif

When the JSON data is merged into the modified template document, the following Word document is created. Notice that now, the actual images are shown, rather than the text URL.

images/wordmerge20.jpg

In addition to the image decorator, you can also use the html decorator. The html decorator is used to indicate that the JSON data contain HTML data that should be rendered as HTML, rather than plain text.

When you use the html decorator to indicate that the JSON field has HTML text, there are limitations as to what HTML elements and styles are supported. You may need to experiment to determine if the HTML markup in your JSON data is supported.

Instead of using the word_template_from_sample_json() function to create the template from sample data, you might want to use the word_template_from_schema() function because this function will automatically add the necessary decorators to the merge fields. You will not have to edit the template to manually add the decorators to the merge fields.