Word Template Helpers with Word Field Codes

When creating templates in Microsoft Word, Fields act as placeholders (bookmarks) to dynamically insert data from eBECAS/EDMISS. During the merge process, data is inserted exactly as it is, without any logic or advanced formatting. While this is sufficient in most cases, there may be situations where you need to apply conditional logic or formatting based on the merged data. This is where Microsoft Word Field Codes become useful.

This article applies only to templates created in Microsoft Word. For online templates, refer to this article: Template Helpers.

What Are Word Field Codes?

MS Word Fields alone are limited to inserting raw data without additional logic or formatting. To enhance their functionality, MS Word Field Codes which extends MS Word Fields' functionality can be used to dynamically process and format the inserted data.

{ MERGEFIELD student-dob \@ "MMMM d, yyyy" }

Here, { MERGEFIELD student-dob } is the Word Fields, and \@ "MMMM d, yyyy" is the MS Word Field Codes that formats the date.

By using MS Word Field Codes, users can:

• Automatically format text, dates, and currency values when merging documents

• Perform basic calculations within a document to dynamically display results

• Apply conditional logic to show different content based on specific data conditions

Considerations for Microsoft Word Field Codes

• Since Word Document Templates are built using MS Word’s native features, they do not support Template Helpers, except in Grid Tables, which are exclusive to HTML-based templates. To achieve dynamic content generation within Word Document Templates, users have to utilize MS Word Field Codes which act as Template Helper in HTML-based templates for formatting, calculations, and conditional logic.

• MS Word Field Codes are a built-in Microsoft Word feature and are not provided by eBECAS/EDMISS NextGen.

• They only apply to Word Document Template and are not available in HTML-based templates.

• They can only be used for Single Bookmarks. Grid Bookmarks in Grid Tables can utilize Template Helpers in Word Document Template.

• Before proceeding, it is recommended to familiarize yourself with Creating a Template from a Word File.

Format

Date

To display date type data in different formats, the @ format switch in MS Word Field Codes can be used.

Syntax

{ MERGEFIELD ReplaceWithFieldApiName \@ "DateFormat" } 

• For more details of available date formatting, visit here.

Example

• { MERGEFIELD students-dob \@ "dd/MM/yyyy" } → 21/01/2025

• { MERGEFIELD students-dob \@ "d MMMM yyyy" } → 21 January 2025

Currency

By default, amounts retrieved from the database are plain numbers, lacking currency symbols, thousand separators, and decimal points. Simply adding a currency symbol manually does not resolve the formatting issues. To ensure proper display, the # format switch in MS Word Field Codes can be used.

Syntax

{ MERGEFIELD ReplaceWithFieldApiName \# "CurrencyFormat" }

• For more details on formatting numbers and currency in MS Word Field Codes, refer to the official Microsoft documentation: Format a number or currency field (support.microsoft.com)

Example

• { MERGEFIELD offers-offer_amount } → 12500.0

• { MERGEFIELD offers-offer_amount \# "$,##0.00" } → $12,500.00

• { MERGEFIELD offers-offer_amount \# "€#,##0.00" } → €12.500,50

• { MERGEFIELD offers-offer_amount \# "# ##0,00" } € → 12 500,50 €

Formula

MS Word Field Codes allow basic arithmetic operations to be performed using MERGEFIELD.

Syntax

{ = { MERGEFIELD ReplaceWithFieldApiName1 } (Operator) { MERGEFIELD ReplaceWithFieldApiName2 } }

MERGEFIELD must be inserted using CTRL + F9, rather than manually typing {} braces.

Operators

• +: Addition

• -: Subtraction

• *: Multiplication

• /: Division

Example

• { MERGEFIELD offers-accommodation_amount } → 5000.0

• { MERGEFIELD offers-arrangement_amount } → 150.0

• { = { MERGEFIELD offers-accommodation_amount } + { MERGEFIELD offers-arrangement_amount } } → 5150.0

• { = { MERGEFIELD offers-accommodation_amount } + { MERGEFIELD offers-arrangement_amount } \# "$,##0.00"} → $5,150.00

Conditional

MS Word Field Codes support conditional logic to display different values based on field comparisons.

Syntax

{ IF { MERGEFIELD ReplaceWithFieldApiName } (Operator) "ComparisonValue" “ValueIfTrue" "ValueIfFalse" }

MERGEFIELD must be inserted using CTRL + F9, rather than manually typing {} braces.

• { MERGEFIELD ReplaceWithFieldApiName } is retrieved and the value is compared using the specified ComparisonValue.

• If true, ValueIfTrue is displayed.

• Otherwise, ValueIfFalse is displayed.

Operators

• =: Equals to ComparisonValue

• <>: Not equals to ComparisonValue

• >: Greater than ComparisonValue

• <: Less than ComparisonValue

Example

• { MERGEFIELD students-first_name } → Ryan

• { IF { MERGEFIELD students-first_name } = "Ryan" “His name is Ryan" "His name is not Ryan" } → His name is Ryan

• { IF { MERGEFIELD students-first_name } <> "Ryan" “His name is Ryan" "His name is not Ryan" } → His name is not Ryan

Nested Conditions

Syntax

{ IF { MERGEFIELD ReplaceWithFieldApiName } (ComparisonOperator1) "ComparisonValue1" “ValueIfTrue1" { IF { MERGEFIELD ReplaceWithFieldApiName } (ComparisonOperator2) "ComparisonValue2" “ValueIfTrue2" "ValueIfFalse" } }

MERGEFIELD and nested conditions must be inserted using CTRL + F9, rather than manually typing {} braces.

• If { MERGEFIELD ReplaceWithFieldApiName } meets ComparisonValue1 based on ComparisonOperator1, then ValueIfTrue1 is displayed.

• If not, the second condition is checked. If { MERGEFIELD ReplaceWithFieldApiName } meets ComparisonValue2 based on ComparisonOperator2, then ValueIfTrue2 is displayed.

• Otherwise, ValueIfFalse is displayed.

Example

• { MERGEFIELD offer-location } → Brisbane

• { IF { MERGEFIELD offer-location } = "Gold Coast" "Classes start at 9:00 AM." { IF { MERGEFIELD offer-location } = "Ipswich" "Classes start at 9:30 AM." "Classes start at 10:00 AM." } } → Classes start at 10:00AM.

Inserting an Image

Standard MERGEFIELD fields do not support images stored in eBECAS/EDMISS NextGen.
To insert images dynamically, use a special image field format.

Syntax

{ MERGEFIELD "ReplaceWithImageFieldApiName IMAGE |PixelWidth|" }

• Retrieves the image field data through ReplaceWithImageFieldApiName and set the image size through PixelWidth.

Example

• { MERGEFIELD "students-student_photo IMAGE" } → Insert the Student Photo in the original size.

• { MERGEFIELD "students-student_photo IMAGE 100" } → Insert the Student Photo in the 100px width size.