Merge fields

The converter provides support for the CKEditor 5 Merge fields feature. Merge fields allow users to create template fields inside an HTML document, which in the case of Export to Word, can either be converted to Word merge fields or populated with provided data.

Merge fields can be configured via config.merge_fields configuration option. Read about this configuration option in API documentation.

# Word merge fields

Word merge fields allow you to effortlessly customize and personalize your documents by dynamically including variable data such as names, addresses, dates, and other unique details from your data source.

This feature is essential for creating tailored communications, whether for letters, emails, labels, envelopes, or directories. By linking your document to various data sources like Excel spreadsheets, Access databases, and Outlook contacts, merge fields pull the exact information you need, ensuring your documents are always up-to-date and accurate. They can save your time by automating the inclusion of personalized details, eliminating the need for manual updates and repetitive data entry, and allowing you to focus on more important tasks.

# Converting to Word merge fields

If the merge fields configuration does not include the data property, the converter will preserve all merge fields in the generated .DOCX file.

Example of converting HTML with merge fields to Word document:

{
 "config": {
  "merge_fields": {
   "prefix": "{",
   "suffix": "}"
  }
 }
}

<p> Hello {NAME}! </p>

Word merge fields are used to create form letters, mailing labels, and other documents that are personalized for each recipient. To learn more about using merge fields in Word, see Microsoft’s article on Mail Merge.

# Word limitations

Some merge field names may contain characters not allowed by Word. As a result of this limitation, when importing the data source, Word will modify it and prompt you to delete or rename incompatible fields during a mail merge.

Consider that we have converted HTML with merge fields to a Word document:

{
 "config": {
  "merge_fields": {
   "prefix": "{",
   "suffix": "}"
  }
 }
}

<p> Hello {FIRST.NAME} {LAST.NAME}! </p>

The . character is not allowed in Word merge fields data source. When you try to perform a mail merge with a data set including that character, Word will display this dialog:

To avoid this issue, make sure that merge field names do not contain characters that are not allowed by Word. As of now, the following characters are not allowed in merge field names: ., -, an empty space, starting merge field with a number (e.g. {1st_name}).

# Inserting data using merge fields

If the merge fields configuration includes the data property, the converter will insert values associated with keys inside the data, which are also placed inside the HTML. Please note that merge fields cannot be used inside HTML attributes or any other part within the markup. They also cannot be used between the opening and closing tags of the style tag.

If the provided data is empty or missing values for some field, merge fields without data will be converted to plain text.

The provided data can be in both HTML and plain text formats. Here is an example:

{
 "config": {
  "merge_fields": {
   "prefix": "{",
   "suffix": "}",
   "data": {
    "FIRST_NAME": "John",
    "LAST_NAME": "<i>Doe</i>"
   }
  }
 }
}

<p> Hello {FIRST_NAME} {LAST_NAME}! </p>