Mail Merge Switches
Switches within a Mail Merge merge field may be used to format the resulting output.
Tip
To edit existing merge fields, select the entire merge field which is shown enclosed in chevrons «NLSField» and press Shift+F9 to reveal the field code (or right click on the merge field and select Toggle Field Codes) which will then be shown enclosed in braces {MERGEFIELD NLSField}. Once the merge field has been modified, place the cursor within the braces and press F9 to hide the field code.Important
Beginning with NLS 5.13, changes were made to the way mail merge documents are processed by NLS. Please test all existing Microsoft Word mail merge documents when upgrading to NLS 5.13 and later to ensure that all the merge fields in the document are being processed correctly.String Formatting
To apply font formatting, add a format switch \* Charformat and apply font formatting to the ‘M’ in MERGEFIELD.
Example
{MERGEFIELD cifno \* Charformat} will display cifno in bold text.Example
{MERGEFIELD cifno \* Charformat} will display cifno in the specified colors.Following are format switches that can be used to control capitalization of words.
| Switch | Description |
|---|---|
| \* Caps | Capitalizes the first letter of each word. |
| \* FirstCap | Capitalizes the first letter of the first word. |
| \* Upper | Capitalizes all letters. |
| \* Lower | All letters are in lower case. |
Number and Currency Formatting
To apply number and currency formatting, add a numeric format switch \#.
Numeric format switches are used in combination with the following:
| Switch | Description |
|---|---|
| 0 (zero) | Specifies the minimum numeric places to display including leading zeroes. Example {MERGEFIELD current_interest_rate \# 00.00} displays 05.00 |
| # | Specifies the minimum numeric places to display. If a place has no digit, it is replaced with a space. Example {MERGEFIELD payment_amount \# $###} displays $ 10 |
| x | Does not display digits to its left and if used to the right of a decimal point, the result is rounded to that place. Example {MERGEFIELD cifno \# x##} displays 111 if cifno is 123111{MERGEFIELD current_interest_rate \# 0.00x} displays 0.599 if current_interest_rate is .59911 |
| . (decimal point) | Places a decimal point in its position. |
| , (comma) | Places a digit grouping symbol (thousand separator) as specified in the regional settings in the Control Panel. Example {MERGEFIELD current_payoff_balance \# $,0.00} displays $1,234.56 |
| - (minus) | Places a minus sign on a negative result or adds a space if the result is positive or zero. Example {MERGEFIELD current_payoff_balance \# "$#,##0.00;- $#,##0.00"} displays $1,234.56 for a positive number and - $1,234.56 for a negative number |
| + (plus) | Places a plus sign to a positive result, a minus sign to a negative result, or a space if the result is zero. Example {MERGEFIELD current_payoff_balance \# "+ $#,##0.00"} displays + $1,234.56 for a positive number and - $1,234.56 for a negative number |
| () (parenthesis) | Places negative number within parenthesis and a hyphen in place of zero. Example {MERGEFIELD current_payoff_balance \# "$,0.00;($,0.00);'-'"} displays $1,234.56 for a positive, (1,234,56) for a negative number, and - for zero. |
NotE
Zero values can be suppressed by adding a final semicolon ; at the end (\# "$,0.00;($,0.00);"). This suppresses 0s resulting from empty fields and from fields containing 0s.
Example
{MERGEFIELD current_principal_balance \# "$ ,0.00"} displays $ 99,999.99Conditional String Formatting
To show a past due balance in a different font style when it is over a certain amount, an “if, then, else” field can be used.
Example
{IF {MERGFIELD total_past_due_balance} > 500 {MERGEFIELD total_past_due_balance \* Charformat} {MERGEFIELD total_past_due_balance}} displays 555 in bold red font or 111 in normal font style.Force '0' Substitution for Empty/Missing Records
Use Set Val to force the display of $0.00 for fields that are empty.
Example
{Set Val {MERGEFIELD current_suspense}{=Val \# "$,0.00"}} will result in $0.00 being displayed if current_suspense is empty.Math and Percentage Formatting
Mathematical calculations can be performed by using the EXPRESSION = field.
Example
NLS stores its percentage figures as-is (e.g. 5.01% is stored as 5.01). This can be converted into a decimal number.
{={MERGEFIELD starting_interest_rate}/100 \# 0.00} results in 0.05 if the stored value is 5.01.Conversely, if the stored value is in decimals, it can be converted into a percentage.
{={MERGEFIELD starting_interest_rate}*100 \# 0.00%} results in 5.01% if the stored value is .0501.The precision of the result, as set by 0.00, can be from '0' to '0.000000000000000'.
Note
After pressing F9 to hide the field code, the merge field may display a syntax error. However, the merge field will function correctly in NLS as long as the code was entered correctly.Date Formatting
To apply date formatting, use the date-time format switch \@.
| Switch | Description |
|---|---|
| yyyy | Year. Use yy to display the last two digits of any year. |
| M | Month. Use MMMM to fully spell out the month (e.g. September, October). Use MMM to display the three letter abbreviation for the month (e.g. Sep, Oct). Use MM to display the month in two digits with a leading zero for single digit months (e.g. 09, 10). Use M to display the month in digits (e.g. 9, 10). |
| d | Day. Use dddd to spell out the day of the week (e.g. Sunday, Monday). Use ddd to display the three letter abbreviation of the day (e.g. Sun, Mon). Use dd to display the day in two digits with a leading zero for single digit days (e.g. 09, 10). Use d to display the day in digits (e.g. 9, 10). |
Example
{MERGEFIELD payoff_date \@ "dddd, MMMM d yyyy"} results in Friday, August 5 2016
{MERGEFIELD payoff_date \@ "ddd, d MMM yyyy"} results in Fri, 5 Aug 2016
{MERGEFIELD payoff_date \@ "yyyy.MM.dd"} results in 2016.08.05
{MERGEFIELD payoff_date \@ "d-M-yy"} results in 5-8-16
Note
The d, M, y expressions can be arranged in different order, but note the usage of uppercase “M” for months as the lower case “m” is used for minutes.Ordinal and Cardinal Formatting
Ordinal values can be displayed using the \* Ordinal switch.
Example
{MERGEFIELD input_date \@ "dddd,"} {MERGEFIELD input_date \@ "d" \* Ordinal} {MERGEFIELD input_date \@ "'of' MMMM, yyyy"} results in Thursday, 5th of May, 2016Ordinal values can also be converted to ordinal text with the \* OrdText switch.
Example
{MEGEFIELD input_date \@”dddd,”} {MERGEFIELD input_date \@ “d” \* OrdText \* FirstCap} {MERGEFIELD input_date \@ “’of’ MMMM, yyyy”} results in Thursday, Fifth of May, 2016Values can be displayed as cardinal text with the \* CardText switch.
Example
{MERGEFIELD cifnumber \* CardText} results in one.The result will be in lower case but string format switch can be used to capitalize accordingly.
Values can be displayed as cardinal text with the \* DollarText switch. An ‘and’ will be inserted at the decimal point and the first two decimals will be displayed over the 100 denominator.
Example
{MERGEFIELD total_current_due_balance \* DollarText} results in three hundred and 21/100.Time Formatting
To format how time is displayed, use the date-time format switch \@.
| Switch | Description |
|---|---|
| h or H | Hours. Lower case h denotes 12-hour format and upper case H denotes 24-hour format. Use hh or HH to display a leading zero on single digit hours. |
| m | Minutes. Use mm to display a leading zero on single digit minutes. |
| s | Seconds. Use ss to display a leading zero on single digit seconds. |
| AM/PM | Displays AM or PM. |
Example
{MERGEFIELD time \@ HH:mm} displays 13:01{MERGEFIELD time \@ h:mm:ss AM/PM} displays 1:01:01 PM
U.S. Social Security Number Formatting
Suppress the first five digits in a social security number stored in the TIN1 field formatted as ‘123-45-6789’.
Example
{QUOTE{SET ID {MERGEFIELD cif_tin}}
{SET Last4 {=({ID}*(-1)-ID)/2}}"XXX-XX-"{Last4 \# 0000}}
123-45-6789 results in XXX-XX-6789
U.S. Zip Code Formatting
Format zip codes as a 5-digit or 5+4-digit zip code.
Example
{QUOTE{SET ZipCode {MERGEFIELD zip}}
{IF{ZipCode}> 99999 {SET ZipCode {ZipCode \# "00000'-'0000"}}}
"{=-{=-{ZipCode}-ZipCode}/2 \# 00000;;}{=-({ZipCode}*(-1)-ZipCode)/2 \# ;-0000;}"}
12345 results in 12345
123450000 results in 12345
12345-0000 results in 12345
123451111 results in 12345-1111
Selective Space Insertion
Use \b and \f switches to insert a space only when a field is not blank.
| Switch | Description |
|---|---|
| \b | Specifies text to be inserted before the merge field if the field is not blank |
| \f | Specifies text to be inserted following the merge field if the field is not blank |
Example
{MERGEFIELD firstname1 \f " "}{MERGEFIELD middlename1 \f " "}{MERGEFIELD lastname1}If all fields are not blank, the result will be Mary Jane Smith
If middlename1 is blank, the result will be Mary Smith
Selective Line Break Insertion
Use \b and \f switches to insert line breaks when needed.
Example
{MERGEFIELD street_address1}{MERGEFIELD street_address2 \f "↲"}
{MERGEFIELD city}, {MERGEFIELD state} {MERGEFIELD zip}
Replace ↲ with an actual line break (Shift-Enter)
If all fields are not blank, the result will be
123 Main
MS 123
Any Town, CA 00000
If street_address2 is blank, the result will be
123 Main
Any Town, CA 00000
Without the \f switch, there would be an empty line between street_address1 and the city/state/zip line.
Hyperlinks
Hyperlinks can be created using a HYPERLINK field.
If the field codes are not visible, press Alt+F9 to reveal the field codes. Select Insert > Quick Parts > Field… and select Hyperlink. Uncheck the Preserve formatting during updates checkbox and click OK.
This will result in a {HYPERLINK} field being placed in the document.
For web address:
Place the insertion cursor after HYPERLINK and type "http:// or "https://. Press Ctrl+F9 and enter MERGEFIELD web_address then place a " after the closing } of the MERGEFIELD field.
Example
{HYPERLINK "https://{MERGEFIELD web_address}"}This can also be entered using the following syntax:
{HYPERLINK {MERGEFIELD web_address \b "https://"}}
For email:
Place the insertion cursor after HYPERLINK and type "mailto: . Press Ctrl+F9 and enter MERGEFIELD email then place a " after the closing } of the MERGEFIELD field.
Example
{HYPERLINK "mailto:{MERGEFIELD email}"}The Subject and/or Body of the email can also be predefined:
{HYPERLINK "mailto:{MERGEFIELD email}?subject=Test&body=This%20is%20a%20test"}
Place the insertion cursor between the last " and } then select Insert > Bookmark. Enter any name for the bookmark and click Add. Nothing will appear in the document but this is an important step as it prevents Word from altering the edited HYPERLINK field when the document is closed.
Press Alt+F9 to hide the field code and the text for the hyperlink should read Error! Hyperlink reference not valid.
To replace this with your own text, select Error! Hyperlink reference not valid leaving the period at the end of the sentence unselected.
Enter any text to appear in place of the hyperlink, or to have the actual web address or email address appear in its place, go to Insert > Quick Parts > Field….
Select MergeField and enter web_address or email in the Field name field. Uncheck the Preserve formatting during updates checkbox and click OK.
Press the ⌦ delete key to delete the period that was left unselected previously.
Note
Do not replace or delete the entire Error! Hyperlink reference not valid. block of text at once as this will break the merge field. Always leave at least one character untouched until after the edit has been made.Use caution when editing the HYPERLINK field at a later time as doing so could break its functionality.
