Loops can be used to iterate through multiple records and fields to be merged into in your document.  Examples of this are displaying a list of contacts, or displaying a list of violations associated with an evaluation.  Loops may also be filtered to limit the merge to selected records.  An example of this is filtering a contact loop to only merge contacts that have a particular affiliation type/role code.

Basic Loop Syntax

When editing a document template, double-clicking a bold field in the Insertable Fields list will insert a foreach loop into the document template. The example below inserts a permits loop into a document template:

Withing the opening <<foreach>> and closing <</foreach>> tags, the merge fields for that loop can be inserted. The following example displays the permitNumber within the loop:

Loop Variable Naming

Note that permit in the example above is a variable name than can be chosen by the template developer. For a more compact display, this variable name can be substituted with a different value if desired. Shorter variable names can improve readability and layout of a template since the code takes up less space in the document. In the example below, the variable p is substituted for permit in the previous example:

Nested Loops

Loops can be nested within one another when supported by the selected datasource(s). For example an form with a repeating section that contains an advanced table will require two nested loops to access the advanced table data. The example below shows an example of a nested loop using a hypothetical datasource:

Merge Field Scope within a Loop

Within a loop, you have access to all the variables at levels above the current loop. In the example below, the p.permitNumber is accessed from within the permitContacts child loop:

When a Loop is Not a Loop!

The beginning of this section mentions a bold entry in the Insertable Fields list represents a loop. This is not always true. More specifically, bold entries represent an object that is a container for additional elements. That object may or may not be a list. For example, the ”currentUser” and “environmentSettings” entries in the Insertable Fields list can be inserted using a foreach loop, however because there is only ever one record returned for both of these entries, you can also reference the object’s properties directly without using a foreach loop. For example, both syntax examples will work and will produce exactly the same output:

How is this possible? AceOffix evaluates each object in the merge field data at the time the document is being rendered. It determines in real time whether an object is a list (an array in technical terms) or just a named collection of individual data elements (“scalar” in technical terms). If it is scalar, it will also be treated as a list with just one row, allowing for either syntax to be used.

This can be helpful when using form submission datasources in document templates. The merge field representing the form is always scalar (only one logical row) and therefore, the properties can be reference using the simpler syntax above without the foreach loop.

Formatting Lists and Tables in a Document using Loops

Loops are most often used in bulleted/numbered lists or in tables in a Word document.

Formatting Lists

To format a foreach loop, check the examples below:

The last loop formatting in the examples above uses IndexOf() and Ternary "?:" to decide whether to place a comma "," or not to place anything after the first item, then the "." is placed after closing the foreach loop,  which translates into "is this true ? Yes : No". The code will result in adding a comma after each item except the last item in a list where a "." will be added.

Formatting Tables

A foreach statement within a table will create new table rows for each item in the list. In the example below, for each feature ID, a new row within the table will be created and the associated fields filled:

Extension Methods for Loops (Sorting, Filtering and More)

Foreach loop can be combined with extension methods to access data within the dataset such as .Where, .Take(), .OrderBy(), etc..

Using Lambda Expressions

In order to take advantage of many AceOffix capabilities including sorting and filtering loops, you will want to become familiar with lambda expressions. In the examples below. you will see that each repeating element is followed by a function name (e.g. Where, OrderBy, etc.) and then an expression in parenthesis. For example:

<<foreach [contact in contacts.Where(x => x.affiliationTypeCode == "MNR_HAUL")]>>

The x => x.item notation is a so-called lambda expression. Any letter can be chosen to replace x. It's a shorthand way of saying "take x and return this property of x". For example, in the contact examples given above, "x" is used to represent the contact and "x => x.affiliationTypeCode" means "take the contact and return the affiliationTypeCode for that contact".

Filtered Loops (Where)

To filter a loop so that it only displays certain data (such as only displaying a contact with a specific affiliation type), add a Where clause to the foreach syntax. For example, the following code only displays those contacts that have an affiliation type of manure hauler ("MNR_HAUL"):

To filter the loop using multiple criteria, add additional expressions within the Where clause, separated by appropriate boolean operators (such as && for "and" or || for "or"). For example, the following snippet returns the phone number of the contact only if the affiliation type is "MNR_HAUL" and the Phone Type Description is "Office":

To protect against multiple matching records being returned (such as 2 or more manure haulers in the example above), add .Take(1) to the markup:

To return a different record when a specified record does not exist, syntax such as the following can be used:

In this example, the foreach loop will filter based on an affiliation type of "ENGR". The syntax Take(1) is used to return the first value, in cases in which multiple contacts with the same affiliation type are returned. In this case, the Contact Last Name is returned. An if statement is used to check if the count of affiliation type "ENGR" is 0 (using .Count() == 0) and, if so, to return the contact with the "OWNR" affiliation type.

Sorting Loops (OrderBy)

To add sorting to a loop so that it displays the data in a certain order, add an ".OrderBy" or "OrderByDescending" clause to the foreach syntax.

In the above example the code will sort contacts based on the contact's Last Name and will display Contact First Name, Contact Last Name in a list.

For more examples, see the Tips and Tricks section below

Other Useful Methods (Sum, Count, Take…)

A full list of supported methods can be found on Microsoft's Enumerable Class support page.

Other useful methods are listed below

Combining Methods

The methods above can be combined together. 

The following example shows a loop that combines  Where(), Order By(), and Take() methods.

Loop Tips and Tricks

Returning Distinct Results Using foreach and a Variable

Consider a document template that needs to show the distinct list of receiving waters across multiple permitted features. Specifying distinct results is important here because in almost all cases, the receiving water for all features will be the same.

Unfortunately, the Distinct() method does not appear to work in the current version of the document template editor. The following is a workaround that returns the desired results:

1. Set a local variable to a default value (e.g., "None").

2. Setup a foreach loop to iterate through all of the features.

3. Within the loop, compare the receiving water to the local variable. If different:

   1. Set the local variable = the receiving water;

   2. Display the receiving water.

4. If the receiving water is the same as the local variable, then ignore and move on.

A syntax example is shown below. (Note that carriage returns have been added here for visibility only, using the code as written this way will cause many unwanted carriage returns).

Breaking Out of a Loop

Sometimes it's useful or necessary to break out of a loop when a particular condition has been met or value has been found. This can be achieved by doing the following:

1. Create a variable and set it to "true". 

2. At the beginning of the loop, check to see that the variable is equal to "true".

3. Somewhere in the loop, perhaps when a specific condition has been met, set the value of the variable to "false".

The following code illustrates this. (The code is indented here for legibility but doesn't need to be indented in the document template.)

In the above example, the text "W50-51 Failure to meet the applicable requirements..." is displayed if the reference begins with “W50-51”.

Sorting by a Text Field Containing Numbered Items stored as Text (nSPECT Questions)

If trying to sort an ordered list in a tag value (1. 2. 3. etc..) then you'll need to have the .OrderBy only look at those specific values; otherwise it will sort incorrectly. One way to do that is to use the .Substring() function, in combination with the .IndexOf() function and the Convert.ToDouble() function, as shown below. 

Explanation of the above string: 

• .OrderBy() must be in between the [] of the foreach statement, attached to the last tag name.

• Convert.ToDouble() is used to enclose the specific text you are trying to sort by (i.e. c => c.questions) c.questions here is what you are trying to have OrderBy sort off of.   **Please note ToInt() has not worked in this situation, so ToDouble() is best. 

• .Substring(start, end) is used to pick out a certain part of the tag value. In this example, the user wants to pick out whatever is before the period since those will be the numbers in the list of questions.  So the user has the Substring start at 0 (the beginning of the tag value) and then end at the .IndexOf(".") the period. 

• .IndexOf() will give the exact placement of the period in the string so that when it looks at the substring of (0, c.questions.IndexOf(".")) it will only be looking at "1" as the first question. If the numbers were proceeded by a "-" (dash), then  c.questions.IndexOf("-") would be used instead. You can look for any unique value this way. If it's not a unique value, only the first occurrence of that value will be found.  

On this page

Related Content