Using array data in sentences

Items in an array can be displayed as a comma separated string in a sentence.

The examples below describe methods used to cater for the different possibilities of one, two, or more than two items in such a list, and the logic required to choose whether to separate the items with commas, an “and” or if a full stop is needed after the last item.

Display a list as a comma separated string

These examples use a repeating section <<rs_ to loop through a list of colours, displaying each colour one after the other across the page, via the <<colour>> field.

These examples also reference two built-in-variables of Docmosis that are useful when looping through a list using <<rs_ being:

$itemnum: this is set to the number of the current item. 
$size: this equals the total number of items in the list.

Conditional Sections <<cs_ can then be used to check what the current item is, when looping through the items in the list, to determine whether a “comma”, an “and”, or a “full stop” is inserted after the item.

Example 1 - Just commas

This example works by checking if the current colour is "not the last colour" in the list.

The steps are:

1. Use a repeating section to loop through the colourList data: <<rs_colourList>>...<<es_colourList>>.
2. Display the colour in the current list position: <<colour>>.
3. Use a conditional section to check that this is not the last item in the list, and if it's not, display a comma followed by a space: <<cs_{$itemnum<$size}>>, <<es_>>.

Example 2 - Adding surrounding text

This example displays the list of colours in a semicolon separated list, preceded by the text "Colours", and ending with a full stop.

The full stop shown after the <<es_colourList>> instruction is significant. This results in the full stop being displayed at the end of the sentence, after completion of the repeating section which loops through all the colours in the list.

The steps are:

1. Display the text "Colours:".
2. Use a repeating section to loop through the colourList data: <<rs_colourList>>...<<es_colourList>>.
3. Within the repeating section, carry out these steps:
   1. Display the colour from the current position in the list: <<colour>>. 
   2. Use a conditional section to check that this not the last item in the list, and if it's not, display a semicolon followed by a space: <<cs_{$itemnum<$size}>>; <<es_>>.
4. After the repeating section, display a full stop.

Example 3 - Adding an "and"

This example goes one step further by showing an “and” between the last two colours.

This is achieved through another conditional section which checks to see whether the current colour is the second last colour in the list:  <<cs_{$itemnum=$size-1}>>.

If it is the second last colour, then it is followed by “ and ”.

Keeping paired items together 

Sometimes lists contain paired values which should be kept together, with a comma separating each “paired item”.

A classic example is a list of people whose first and last names should remain together, rather than split across lines, to ensure easy readability of a sentence.

To illustrate this, a list of all the members of a committee is used in the examples below.

Example 4

This advanced example ensures that the first name and the last name of any committee member are not split between the end of one line and the beginning of the next line.

These are the steps:

1. Use a repeating section to loop through the committeeList data: <<rs_committeeList>>...<<es_committeeList>>.
2. Within the repeating section, follow these steps:
   1. Concatenate the first name and the last name, using the + operator in a Docmosis expression, and assign to a $name variable: <<$name = {firstname + ‘ ’ + lastname}>>. 
   2. Replace any spaces and hyphens which exist in the concatenated name with non-breaking spaces and non-breaking hyphens: <<$name = {replace(replace($name,‘ ’,‘ ’),‘-’,‘‑’)}>>. See note, below.
   3. Use a conditional section to check if this is before the second-last item in the list. If so, display a comma followed by a space: <<cs_{$itemnum<$size-1}>>, <<es_>>.
   4. Use a conditional section to check if this is the second-last item in the list, and if it is, display "and ": <<cs_{$itemnum = $size-1}>>and <<es>>.
3. After the repeating section, display a full stop.

Note: The example ensures that names such as "Jo Anne Smith" or "Mary-Anne Sauter" or "Kyle Peters-Smith" do not split over separate lines as a result of the spaces and hyphens they contain. 

The Docmosis replace string function is used twice through this expression {replace(replace($name,’ ‘,’ ‘),’-‘,’ ‘)}.  Firstly the normal space characters are replaced with non-breaking space characters. The resultant string from the inner replace function, which now has non-breaking spaces, is passed to the outer replace function.  The second use of  replace  replaces any breaking hyphens with non-breaking hyphens. 

To see the difference between normal spaces and hyphens, and non-breaking space and hyphen characters, select Show/Hide ¶ on the Home ribbon tab in Word.

• To insert a non-breaking space press Ctrl + Shift + Spacebar.
• To insert a non-breaking hyphen press Ctrl + Shift + hyphen.

 Example 5

The code used in this example achieves the same result as in Example 4.

This alternative approach may be more readable than the previous example as it is spread over many lines.

Docmosis will remove a line from a template where it is purely an instruction to Docmosis and there is no field that results in output on the line.

In this second method, the sentence is built up name-by-name using the $line variable.  The majority of the lines are removed and only the  <<$line>>  results in output in the generated document.