word_merge_python Function
Syntax
DIM result AS P = word_merge_python(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 Actions below for more information.
- 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
Description
Merges JSON data into a Word template document.
Discussion
A common requirement is to create a Microsoft Word document from a Word template by merging data into placeholders in the Word template documents. There is an existing Xbasic function to do this (the a5_word_merge_dotNet() function), but this function requires that Microsoft Word is installed on the machine where the Alpha Server is running. This precludes the a5_word_merge_dotNet() function from being used in applications that are hosted on Alpha Cloud). The word_merge_python() function does not require that Word be installed and also, this function is significantly faster than the the a5_word_merge_dotNet() function.
Another significant benefit of the word_merge_python() function is the ability to merge data from nested Arrays in the input JSON data into tables in the Word template. Additional rows are automatically added to the table in the template document to accommodate all of the rows in the nested array in the input JSON.
Configuring your Workspace to use word_merge_python()
In order to use the word_merge_python() function you must install Python, which (as of the time of this writing) is not installed by default when you install Alpha Anywhere. Installing the Python dependency in the Alpha Anywhere IDE is done by selecting the Tools > Packages menu command when the Web Control Panel has focus.
Installing the Python dependency in your Web Project is done by clicking the Project Properties button on the Web Control Panel and then clicking the smart field for the Referenced Packages property.
How to Create the Word Template
To create the Word template, create a new Word document and then insert placeholders in the Word document for the fields in your JSON data.
To insert a field placeholder, put your insertion point at the place where you want to insert the placeholder and then press Ctrl-F9.
You can also use the word_template_from_schema() or word_template_from_sample_json() functions to generate a Word template.
This will insert a pair of braces as shown in the above image (DO NOT type the braces yourself).
Type (case insensitive) the following between the braces:
Mergefield name_of_field_in_json_data
For example, say you have a field in your JSON data called Firstname, you would type:
When you are done, press the F9 key (with the insertion point inside the braces). The document will then show the placeholder as follows:
To edit the placeholder, right click on it and select Edit Field...
How to Define Tables in the Word Template for Array Data in the JSON
To insert data from a nested array into a table in the Word Template, insert a Table into the Word document, The table should have two rows - one for column headings and one for placeholders, and as many columns as you need (plus one additional column - which can be hidden, as explained later- where the Linking field must be specified).
For example, consider the following JSON data. This data has a nested array called Children.
{
"Firstname": "John",
"Lastname": "Smith",
"City": "Boston",
"State": "MA",
"Children": [
{
"Name": "Callie",
"Age": 5
},
{
"Name": "Griffin",
"Age": 3
},
{
"Name": "Luke",
"Age": 1
}
]
}The Word template should have a table that looks like this (Note, the << >> characters are not typed in yourself - they are inserted by Word automatically when you insert placeholders as explained above - i.e. by pressing Ctrl - F9):
| Name | Age | |
| <<Children>> | <<Name>> | <<Age>> |
Notice that the first column (i.e. the linking column) has a placeholder with the name of the nested array (Children). The column heading for this this column is irrelevant (and is blank in this example). The data in the array is shown using placeholders in the second row (columns 2 and 3). The column heading for the data columns can be anything you want (i.e. they do not have to match the names of the data properties).
How to Hide the Linking Column
To hide the linking column (i.e. the first column), select the first column and set the font color to white on white. Then set the font size for the column to 1 pixel (the smallest value Word allows), then set the cell border to none, then drag the column divider to the left to make the column as narrow as possible.
After you do this, the first visible column (the Name column in this example) will not have a left border, so select the column and turn on the border for all edges.
Example: Merging JSON into a Word Template
Assume the following JSON data:
{
"CUSTOMERID": "123",
"FIRSTNAME": "Fred",
"LASTNAME": "Thomas",
"COMPANY": "Alpha Anywhere Development",
"ADDRESSES": [
{
"ADDRESSTYPE": "Billing",
"ADDRESS": "123 Billing Street",
"CITY": "Boston",
"STATE": "MA",
"POSTALCODE": "02134"
},
{
"ADDRESSTYPE": "Headquarters",
"ADDRESS": "987 Headquarters Lanest",
"CITY": "Burlington",
"STATE": "MA",
"POSTALCODE": "01803"
},
{
"ADDRESSTYPE": "Shipping",
"ADDRESS": "33 Shipping Ave.",
"CITY": "Lexington",
"STATE": "MA",
"POSTALCODE": "02142"
}
]
}Assume a Word template document that looks like this (Download Word Template):
The linking column in the table is now shown, as it has been hidden. The first column in the table actually has a placeholder in the second row called Addresses to indicate that the table will display data from the nested ADDRESSES array.
Xbasic to merge data into template:
dim json as c
json = <<%txt%
{
"CUSTOMERID": "123",
"FIRSTNAME": "Fred",
"LASTNAME": "Thomas",
"COMPANY": "Alpha Anywhere Development",
"ADDRESSES": [
{
"ADDRESSTYPE": "Billing",
"ADDRESS": "123 Billing Street",
"CITY": "Boston",
"STATE": "MA",
"POSTALCODE": "02134"
},
{
"ADDRESSTYPE": "Headquarters",
"ADDRESS": "987 Headquarters Lanest",
"CITY": "Burlington",
"STATE": "MA",
"POSTALCODE": "01803"
},
{
"ADDRESSTYPE": "Shipping",
"ADDRESS": "33 Shipping Ave.",
"CITY": "Lexington",
"STATE": "MA",
"POSTALCODE": "02142"
}
]
}
%txt%
dim fn_template as c = "c:\word\template.docx"
dim fn_out as c = "c:\word\template_out.docx"
dim result as p
result = word_merge_python(fn_template,fn_out,json)The resulting Word document showing the placeholders replaced with data and showing the Table expanded to show all of the data in the nested array will look like this.
Advanced Actions
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:
Your Alpha Anywhere storage connection string must not be encrypted
Videos
Hiding the Link Column in a Microsoft Word Template
In this video, we show how to hide a column in a table that is used as a linking column. A linking column is used in a table to indicate where nested JSON data should be merged in a Word template. The linking column contains the name of the nested JSON array that contains the values to include in the table.
See Also