Repeating Elements
Repeat an element (eg. Row, Column, etc.) for each item in a list of data.
Last updated
Was this helpful?
Repeat an element (eg. Row, Column, etc.) for each item in a list of data.
Last updated
Was this helpful?
Repeating elements are template elements that contain repeating logic. They dynamically generate multiple instances of the same element by looping through an array (list) of items, creating a new copy for each entry in the array. This allows you to display lists of variable length, and it allows you to display lists without repetition.
See our section on list/array functions on how to manipulate and/or alter array data.
The term repeating element and loop is used interchangeably. They both apply to an element that repeats itself for each item in an array.
Rows, Columns, and Text elements can be repeated for each item in a list of data.
For example, if you are creating an invoice and you want to display all of the products for the order, you can use a repeating to display each item.
Row elements repeat vertically and Column elements repeat horizontally.
To repeat an element, select the element that you want to repeat (for example you have a row that would represent each item in a list) then click the "Edit Logic" button in the properties panel.
When the Logic Editor opens, select the Repeat/Loop tab, add the name of the variable that contains your list, and press "Save".
Now, the selected element will repeat for each item in the items list.
If the data that we've told Documint to repeat the element for is a Collection (list/Array of Objects), then any variables added inside of the repeated element will be within the context of that item. If the data that we're repeating on is a list/Array of Strings, Numbers or Boolean values, then we can display that value using the {{this}} variable.
In this example, we're repeating the Text element for each movie. Because the list of movies is an Array of Strings we use the {{this}} variable to display its value.
In this example, movies is a list of Objects and we can reference its properties directly. So if, for example, the list contains objects representing movies, we can use {{name}} and {{year}} to display the name and year property of each movie object.
If you are repeating a list of objects and use the
{{this}}variable, you will see[object Object]instead. This is because{{this}}refers to the entire object and not to any property in particular.
If you want to display a number for each item in a list, place the {{index}} variable in the repeating element. This is useful for creating numbered lists, or to see the index of the items in your list. The index starts from 1 (unlike a zero-based index) and increases by 1 for each item.
As mentioned in this section, when you are repeating an element, variables used within the repeated element are within the context of the current item in the list. If you want to access data from outside of the current context you can use the ../ syntax to break out of the current context.
In this example, we are repeating a Text element over a list of movies and want to display the name of the streaming service where it's available.
It is possible to repeat elements within repeated elements. This is called nesting. This is useful when you have a collection (array/list of objects) and each of the objects within the collection may contain another collection or list.
To do this, simply specify the name of the list/array property of the current item as the List Variable of the nested element that you want to repeat.
In this example we have a list of deserts (e.g. pie, brownie, and ice cream) each of which may contain a list of disclaimers. What we want to do here is go over each desert and also display any disclaimers the desert may have. We do this by creating a nested loop.
Note: this nested loop is only two levels deep; however, if the items in your collection contain their own collections which in turn may contain their own collections, and so on and so forth, you can nest them repeatedly.
We do recommend - however - to try to keep your data structure simple, as deeply nested loops are difficult to create, maintain, understand, and troubleshoot.
Looping over repeated elements is a common technical challenge. This section covers the frequent issues users encounter and provides guidelines on how to troubleshoot your repeating elements/logic.
If your repeating element is not appearing at all, it could be because of a mistyped list variable, incorrect variables, misplaced repeat logic, or even an empty list.
Ensure the record you are using contains values for this list/array. Sometimes a simple mistake like that can cause what seems like an error with the template.
Make sure the loop has been applied to the correct element. Go to the layers/content tab and click on the element that should be repeating. If the loop is configured correctly, you will see the list variable under "Repeat for each item in:" in the properties tab. If, however, you do not see anything, you may have misplaced or forgot to save the repeating logic.
Once you are there, you should confirm that the list variable is correct. Go to your data source, and double check the name for the field/property that contains the list/array. Then check the name of the list variable in the repeating element. The list variable should follow the syntax for variables with the exception that it is not surrounded with curly brackets. For example: if your record has a field called "Line Items" that contains a list of associated products, the variable name for the repeating element would be line_items.
Confirm the type for your list. If your list contains simple numbers or strings, you will reference the values in the list via the {{this}} variable. If you are looping over a list of objects, check the variables in the repeating element: it could be the case that the repeating element is configured correctly, but the variables are not.
[object Object] indicates you are either using the {{this}} variable to refer to an object (which will be the case if you use {{this}} when looping over a collection), or you are using a property that refers to an object or array. If you are using {{this}}, you need to reference the object's properties directly. Otherwise, you need to check if your property is referencing an object or array, and if it is, apply the correct syntax and/or logic.
If your repeating element does not appear as it should; that is, items that should not be repeating are repeating, or items that should be repeating are not, or maybe the repeating element is not appearing at all (as mentioned above), it may be the case that your repeating logic is not being applied to the correct element.
Make sure to attach your repeating logic directly to the main element you want to repeat. Don't place it on a parent element (too high) or on a child element (too low). If you put the repeating instruction at the wrong level, your document won't display properly.
For example: we have an invoice that displays a list of line items. We want the header to only be displayed once at the top of the list, and we want a row for each of the line items.
If we put the repeating element too low, in this case, on each column of the row, we will end up repeating ourselves unnecessarily, and rows may become misaligned.
If, on the other hand, we put the repeating element too high, in this case, in the row that contains the header and line item row, we will end up a having a header for each row.
We should put the repeating logic in the highest level element that contains the row that should be repeating itself. In this case, it is the row right below the header. This will produce our desired output.
This should be a quick-fix. Misaligned rows occur when you apply the repeating element to each column in a row rather than the entire row. Now you have a situation where each column has its own loop and are independent of each other. As a result, if any of the objects in your collection are missing the property that is being displayed in that column, the result will be that that that column will lag behind the rest.
To fix this just place the repeating element in the row that contains all the columns. Now if any of your objects are missing properties, the rows will remain aligned and you will just see blank spaces instead.
Perhaps the most common problem arising with repeating elements: nested loops can be especially difficult to understand and troubleshoot.
The process for troubleshooting repeating elements that are nested (regardless of how deeply they are nested) is the same as it is for a non-nested repeating elements. You can apply this process to your nested loop by breaking it back down to the point where it stops working and then building it back up level by level using the troubleshooting process listed above.
In terms of positioning, make sure your nested repeating element is contained within its parent element; otherwise it will be missing the context necessary to access the sublist.
If you still cannot get your repeated element working after following all the troubleshooting steps, you may be dealing with a bug or an especially complex use case. If this is the case, please contact Documint support via email or the chat feature in the application.
