About data-merge
About data-merge
Data-merge (called Mail Merge in Microsoft Word) is a standard feature of Microsoft Word. Therefore, in Word API, you can also use the template file that has already been created.
A simple example of using Microsoft Word mail merge and Word API regarding how to create a template can be referred in How to take advantage of Microsoft Word mail merge (overview).
This section describes the parts that are common to Word API data-merge.
To execute data-merge with the Word API, a template file and merging data are required.
A template file is a Microsoft Word docx format file in which the data-merge fields are defined.
The merging data is a file in which the data-merge field names are columns and the corresponding data is defined.
The Word API allows you to execute the data-merge of the text (green frame in the figure below) and image (red frame in the figure below).
Microsoft Word documents are divided into a header area (red frame in the figure), a body area (blue frame in the figure) and a footer area (green frame in the figure).
In Word API, you can merge into the data-merge fields defined within paragraphs and cells in each of these areas.
In Word API, you can use CSV and JSON format files for merging data. You can use Shift_JIS, UTF-8 and UTF-8 with BOM to encode each file.
As same as Microsoft Word's standard mail merge feature, data specified in the merging data will be merged.
In Word API, you can merge the images in addition to merging character strings.
Different from normal string merging, it is necessary to specify that there is image merging when creating a template, creating merging data and executing Word API.
Insert regular data-merge fields and alternate image in the same paragraph.
The image size determined at this time is also reflected in the image size of the data-merge execution result.
For the field name, specify the data-merge field name (similar to normal data-merge), and for the data, specify the file name of the image to be merged.
The following files can be used for image data-merge:
You need to set the directory where the files specified as data are stored.
If the file specified for the merging data does not exist, the data-merge result will be the same as the text data-merge.
The specified file name will be merged into the data-merge field and the alternate image will remain.
The figure below shows an example of the execution described in this chapter.
Assume that "Kennedy.png", which is the "Photo" in the third record of the merging data (CSV format) in the figure below, does not exist.
Depending on the merging data, it may exceed the cell width.
In Microsoft Word, if data exceeds the cell width, the excess is displayed with a line break, but in Word API, the following four control methods for editing data are available:
The default setting of Word API and is the same processing as Microsoft Word.
The option "Normal" for each interface corresponds to it.
Adjust the font size so that the data fits on one line.
The option "FontSizeChange" for each interface corresponds to it.
Remove excess characters so that the data fits on one line.
The option "CutExcess" for each interface corresponds to it.
Converts a CutExcessed string to a padding character.
The option "Padding" for each interface corresponds to it.
You can change the output file name as shown in the figure by specifying the field name of the data. This clarifies the correspondence between the output files and the data records.
However, if the data specified in the field name is duplicated in multiple records, the output file will be overwritten by the result of data-merge of subsequent records, so you must specify a field name that is unique in the data.
In the case of default setting, the character string is added to the specified output file name in sequence from 1 in the order of records (n_"output file name".docx).
It is possible to add a character string in the following two formats with the option of the position of the additional character string to the output file name.
This is the default setting of Word API. A character string is added to the beginning of the specified output file ("additional character string"_"output file name".docx).
The option "Head" for each interface corresponds to it.
A character string is added to the end of the specified output file name ("output file name"_"additional character string".docx).
The option "Tail" for each interface corresponds to it.
You can get a list of the data-merge field names defined in the specified template file.
In the case of the figure below, you can get "Number", "Name" and "Photo".
The above is the explanation of the common part of data-merge of Word API. A description of the features specific to complex format template files is given in below.
Simple type data-merge
Compund type data-merge
Nested table type data-merge