Repeating list datafields
Last updated
Last updated
Repeating list datafields are a very special type of datafield. They differ from the other types of datafields in two aspects:
While all other types of datafields can only hold one single type of value (e.g. text, currency, number, date, etc.), a repeating list can in principle hold any type of value and are therefore very versatile.
Similar to list of texts type datafields, they enable users to enter multiple values into one datafield.
In order to insert a repeating list datafield, simply create a new datafield and click on repeating list.
As mentioned above, repeating list datafields are special in that they can contain elements of all other data types in Clause9: text, true/false, number, floating point number, currency, date and duration.
In most cases, however, it will be useful and often even necessary to limit this to only one type of data (e.g. to improve user experience, making it impossible for the end user to enter the wrong data type). This can be done by editing the datafield, setting the element type to the desired type of data and saving the changes.
Repeating list datafields allow you to store multiple values, possibily of different datatypes, in a single datafield. Conceptually, you can think of the datafield as creating an (imaginary) column of a table. Inserting a new value (element) into the datafield adds another row cell to that column. Thus, each repeating list datafield in essence stores a column with as many cells (rows) as there are elements in that datafield.
This logic is also visualized in the datafield pane. As you can see in the screenshot, the repeating list datafield called items-to-return stores multiple values. It essentially stores a column of items that need to be returned.
Keeping that in mind, repeating list datafields enable you to do the following things:
You can insert a list of values on a single insertion point into a single clause (whereas the items themselves can be different datatypes) using a single repeating list datafield. For instance, we can insert a list of items that need to be returned by an employee, by using a single single datafield (items-to-return).
You can repeat document elements (clauses, bullets, table rows, documents,…) whereby each element contains one data input (“table row”) from the repeating list datafield. So, instead of having a single clause that says which items need to be returned, Clause9 can automatically display a new clause for each item that was included in the repeating list datafield. Each element is used in a new clause.
An even more powerful use of repeating list datafields is “linking” columns in an (imaginary) table together. Different repeating list datafields that are used in the same repeating clause, bullet or table row will thus form one large table, where each repeating list datafield can be thought of as a column in that table and each element in those datafields as a row in the table. The images below give a practical example:
As can be seen in the above example, each first element of a repeating list datafield is displayed in the first repeating bullet, each second element is displayed in the second bullet and each third element is displayed in the third bullet. Conceptually, you can think of these inputs forming the following table:
year | number-shares | strike-price |
2021 | 100 | 15,000 EUR |
2022 | 200 | 30,000 EUR |
2023 | 300 | 40,000 EUR |
More information on how to create repeating clauses, bullets or tables can be found below under Use cases.
As shown above, with repeating list datafields you can repeat elements (such as clauses) based on the data input (“table row”) of a repeating list datafield. In order to achieve this, we first need to create a clause with a repeating list datafield, in the example below called name.
Under the advanced pane, we then navigate to repeat clause and choose the datafield based on which the clause shall be repeated. In this case, we want a new clause to be added for each new name that we input into our datafield. So, we have to choose the name datafield.
If we now insert multiple names in this repeating list datafield, you can see that a new clause is created for each new name.
Clause9 achieves such “clause magic” because of the way it stores the repeating list data input. Although the value input is stored in the same datafield, each item is still stored as a separate value. This allows Clause9 to iterate through each value input (“table row”) and use it in a separate clause.
With repeating list datafields, you can create tables with repeating rows. In this example, we want a new row to be added for each new name or intern number that we input. In order to do so, a table first needs to be created. The datafield name and intern-number are both repeating list datafields.
In the datafield pane, we can now input multiple values and multiple datatypes.
In the document preview, you will be able to see that for each new data element that we input, a new row will be added. In tables, there is no special setting to be applied. Rows containing repeating list datafields will be repeated automatically.
Clause9 allows you to create a lot more repeating “clause magic” than just repeating clauses and table rows! You can also repeat bullets or even entire documents. That is especially useful for use cases like advanced party introduction clauses. If you want to know more about this topic, feel free to check out this article.
Repeating list datafields may remind you of another special type of datafields: list of texts datafields. (You may recall that list of texts datafields also allow you to store multiple data values using a single datafield.) However, there are two key differences between these two types:
As suggested by the name, list of texts can only store text values. So, if you want to insert any other data types (numbers, floating point numbers, duration, …) you need to use repeating list datafields instead.
The second difference is that, by default, without any extra measures being taken, each list of text will be displayed as a whole.
In the screenshot below, the items that need to be returned by the intern are inserted using a list of texts datafield. The advanced setting “repeat clause” was applied to make the clause repeat itself for each new list item. First of all, you can see that the clause was repeated three times since there are three list items. Secondly, this example also shows that with list of texts datafields, the list is always displayed as a whole, i.e. every three list items are displayed in each clause.
You can, however, take extra measures to extract the individual items from the list of texts. In the example above, for example you could use the following code:
which results in:
Similarly, you could also use @bullets(#items-to-return^element) or one of its variations to turn the list of texts into a bulleted list:
When used inside repeating clauses or table rows, repeating list datafields act as the corresponding non-list type datafield — i.e. the clause will actually “see” each individual element in the list, instead of the text as a whole, e.g. a text element of a repeating list datafield will act as a text type datafield, a date element of a repeating list datafield will act as a date type datafield and so on. That also means that in the Clause9 grammar, conditions must be written to take that into account. E.g. for a text element the grammar would be: {#concept^repeating-list-text = "sample text": text to display} and not the condition grammar that you would use for lists: {"sample text" in #concept^repeating-list-text: text to display}.
Note however that for repeating list datafields that were not assigned a specific element type, once you used a certain comparison operator that only “makes sense” with a certain datatype, you must stick with the data type that was assigned to the repeating list datafield by implication.
The condition {#test^repeating-list > 10 : This number is bigger than 10.} only makes sense if the data input is a number or a floating point number, not for instance a text. So, even though we can technically use any data type, the data type that makes sense is implied by the condition.
Thus, if we use this condition {#test^repeating-list = "text" : This is some text.} next, we are suggesting that the data input is text. If the user would then insert a date type element, Clause9 will then be confused as to which data type the input shall be and an error message will prompt.
In some cases, you want the repeating list datafield to display its entire list even inside a repeating clause or table row. Or — for example — you want to use a special function that only works on list type datafields (e.g. the @count special function) inside a repeating clause/table row.
By default however, inside a repeating clause or table row, the repeating list datafield will act exactly the same way a “normal” (non-list type) datafield acts. That means that, as we have seen, the repeating clause/table row will only display the one element that corresponds to that row (cf. above). That also means that for conditions, the datafield will act as its non-list counterpart (cf. above).
There is a way to force the repeating list datafield to again act as a list datafield inside repeating clauses/table rows and that is by including an underscore in the datafield reference in the Clause9 grammar, like this: #concept^_repeating-list. Written like this, the datafield will always act like a list datafield and will thus display all elements that were inserted into it and can be used for special functions that require list datafields (e.g. @count(#concept^_repeating-list).
Besides repeating lists, you can also use @for and @for-calc to create “repeating” words, sentences, paragraphs, table rows, etc. This is an advanced subject, explained in great depth in another page.
