Mail Merge Expressions and Directives

As of version 5.2 of the Nimblex Platform, we have added several special directives to the Mail Merge system:

  • if <Expr>
  • foreach $item in <Expr>
  • foreach ($index, $item) in <Expr>
  • value-of  <Expr>

These special directives take the form of a Microsoft Word MergeField preceded by an exclamation mark (!).

E.g.

  • { MERGEFIELD “!if [Some Boolean value]” } Other text { MERGEFIELD “!end-if” }
  • { MERGEFIELD “!foreach $value in [Some Array value]” } Other text { MERGEFIELD “!end-foreach” }
  • { MERGEFIELD “!foreach ($i, $item) in [Some Array value]” }
  • { MERGEFIELD “!value-of [Anything]” }
  • { MERGEFIELD “!value-of $value” }
  • { MERGEFIELD “!value-of [Anything] at 1 format “”$0.00″”” }

These directives give you a great deal of flexibility on top of the ‘Default’ Word mail merge.

Expressions (5.3+)

The Mail Merge expression syntax supports these expressions as parameters to the various directives.

  • <Expr> format <String Expr>
  • <Expr> at <String|Number Expr>

Format

You may use this expression structure to format your number of datetime value.

E.g.

1000 format "$0.00" // outputs $1000.00
$datevalue format "dd-MMM-yyyy" // outputs 28-Feb-2016

At

This expression type allows you to index an array or hash.

E.g.

$arr AT 1 // gets the value in the first position of this array
$hash AT "banana" // gets the value associated with key 'banana'

Container Directives

The following directives support several versions depending on context:

  • if
  • foreach

Differing versions are supported for:

  • Paragraphs
  • Table rows
  • Lists (dotted or numbered)

Paragraph

The paragraph variation of a directive has this structure:

{ MERGEFIELD "!if [Some Boolean value]" } Any number of paragraphs, or other content { MERGEFIELD "!end-if" }

Table Row

When positioned at the start of a table row (first position, first cell), this will apply to the whole table row. I.e. an IF may exclude/include the row, and and FOREACH may repeat the row a given number of times.

{ MERGEFIELD "!tablerow:if [Some Boolean value]" }

Lists

When positioned at the start of a list item, this will apply to the whole list item (including nested lists). I.e. an IF may exclude/include the list item, and and FOREACH may repeat the list item (and nested list items) a given number of times.

{ MERGEFIELD "!listitem:if [Some Boolean value]" } Any list item content (including directives)

IF

The IF directive allows you to include/exclude content based on the value of a field or variable.

FOREACH

The FOREACH directive allows you to repeat content based on the value of a field or variable. This value is expected to be an array, and the contents of the directive will be repeated for each element. The specified variable name (In the below examples $value) will contain the ‘current’ item in the array.

There are two versions of this directive:

  • { MERGEFIELD “!foreach $value in [Some Array value]” }
  • { MERGEFIELD “!foreach ($i, $item) in [Some Array value]” }

The second version has a named variable (in this case $i) that contains the 1-based index of the current element.

VALUE-OF

This directive simply outputs the value of its single parameter.

Related Articles