Xbasic

word_merge_json Function

Syntax

DIM result AS P = word_merge_json(C templateFilename, C filenameOut, C json)

Arguments

templateFilenameCharacter

The filename of the Word template document. Can be a URL that points to a remote file.

filenameOutCharacter

The filename for the Word document to be created by merging the JSON data into the template document. (If filenameOut is open and therefore cannot be overwritten, a unique filename is generated and is returned by the function in the result.filename property). filenameOut can also be a JSON string that specifies that the resulting file should be uploaded to S3 or sent via email. See Advanced Options below for more information.

If the filename extension is .pdf, a PDF document is created.

jsonCharacter

The JSON data to be merged into the template document.

Returns

resultPointer

Returns an object with these properties:

errorLogical

Either .t. or .f., indicating if there was an error

errorTextCharacter

Description of the error

filenameCharacter

The name of the file that was created. Will be the same as filenameOut as long as filenameOut is not currently open (and therefore cannot be deleted).

Description

Merges JSON data into a Word template document.

Discussion

The word_merge_json() function merges JSON data into a Microsoft Word template document. This function has no dependencies. Unlike the word_merge_python(), this function does not rely on Python, and unlike a5_word_merge() and a5_word_merge_dotNet(), the function does not require MS Word to be installed.

Another advantage of this function is the ability to convert the resulting Word document directly into a .pdf file (by specify an output filename with a .pdf extension).

The Word template document can be automatically generated from the JSON data using the either the word_template_from_sample_json() or word_template_from_schema() functions.

The advantage of word_merge_json() over word_merge_python() is that you can merge images and use nested tables.

Advanced Options 

Here is a sample JSON definition for the filenameOut parameter to specify that the resulting Word document should be uploaded to an Amazon S3 bucket. The objectName can specify a folder in your S3 bucket. For example, in the example below the 'folder' is 'word_merge').

{
    "type": "Store",
    "storageConnectionString": "your_AA_storage_connection_string",
    "objectName": "word_merge/document1.docx"
}

Here is a sample JSON definition for the filenameOut parameter to specify that the resulting Word document should be emailed:

{
    "type": "email",
    "apikey": "your SparkPost or SendGrid API key",
    "send_to": "comma delimited list of email addresses",
    "send_from": "email address of sender",
    "send_from_friendly_name": "name of sender",
    "subject": "subject",
    "message": "message body",
    "attachment_filename": "name of attachment file e.g. invoice.docx"
}

If you are using SendGrid, prefix the API key with sendgrid:.

For more information about SparkPost API keys, see SparkPost API Keys.

For more information about SendGrid API keys, see SendGrid API Keys.

Your Alpha Anywhere storage connection string cannot be encrypted.

More About Image Field Sizing 

If the JSON data you are merging into the Word template document is an image URL, and you have added the image decorator to the image field placeholder (e.g. <<image:imagefield>>, assuming the JSON property name for the image field is imagefield), the image will be printed at its full size.

It is likely, however, that you will want to control the dimensions of the image. If the image is in a table cell, then you can adjust the size of the table cell. The image will fill the table cell. If the image field is a top-level field (i.e. it is not in a nested array), you can also edit the Word template document, insert a Text Box object (on Word's Insert Ribbon toolbar) and then place the image inside the Text Box object. Size the Text Box to the size you want for the image. The image will fill the Text Box object control.